refactor(tools): unify tool APIs and result handling (#38367)

2026-07-23 17:13:31 -04:00 · 2026-07-23 17:13:31 -04:00 · 79c1544072
commit 79c1544072
parent 8cac010bac
133 changed files with 3602 additions and 2770 deletions
--- a/packages/cli/test/acp/event-behavior.test.ts
+++ b/packages/cli/test/acp/event-behavior.test.ts
@ -218,8 +218,7 @@ describe("acp event behavior", () => {
            sessionID: "ses_tools",
            assistantMessageID: "msg_tools",
            callID: "call_ok",
-            structured: { phase: 1 },
-            content: [{ type: "text", text: "working" }],
+            metadata: { phase: 1 },
          }),
        )
        send(
@ -227,9 +226,8 @@ describe("acp event behavior", () => {
            sessionID: "ses_tools",
            assistantMessageID: "msg_tools",
            callID: "call_ok",
-            structured: { exit: 0 },
+            metadata: { exit: 0 },
            content: [{ type: "text", text: "done" }],
-            result: { code: 0 },
            executed: true,
          }),
        )
@ -255,8 +253,7 @@ describe("acp event behavior", () => {
            sessionID: "ses_tools",
            assistantMessageID: "msg_tools",
            callID: "call_fail",
-            structured: { bytes: 0 },
-            content: [{ type: "text", text: "opening" }],
+            metadata: { bytes: 0 },
          }),
        )
        send(
@ -313,12 +310,10 @@ describe("acp event behavior", () => {
        locations: [{ path: resolve("/workspace", "sub") }],
        rawInput: { command: "printf done", workdir: "sub" },
      })
-      expect(updates[2]?.update).toMatchObject({
-        content: [{ type: "content", content: { type: "text", text: "working" } }],
-      })
+      expect(updates[2]?.update).not.toHaveProperty("content")
      expect(updates[3]?.update).toMatchObject({
        content: [{ type: "content", content: { type: "text", text: "done" } }],
-        rawOutput: { structured: { exit: 0 }, result: { code: 0 } },
+        rawOutput: { metadata: { exit: 0 } },
      })
      expect(updates[7]?.update).toMatchObject({
        kind: "read",
@ -327,7 +322,7 @@ describe("acp event behavior", () => {
          { type: "content", content: { type: "text", text: "opening" } },
          { type: "content", content: { type: "text", text: "not found" } },
        ],
-        rawOutput: { structured: { bytes: 0 }, error: "not found" },
+        rawOutput: { metadata: { bytes: 0 }, error: "not found" },
      })
      expect(response.stopReason).toBe("end_turn")
    } finally {
@ -379,7 +374,7 @@ describe("acp event behavior", () => {
        { type: "content", content: { type: "text", text: "done" } },
        { type: "content", content: { type: "image", mimeType: "image/png", data: "AAAA" } },
      ],
-      rawOutput: { structured: { exit: 0 }, result: { code: 0 } },
+      rawOutput: { metadata: { exit: 0 } },
    })
    expect(updates[8]?.update).toMatchObject({
      toolCallId: "call_running",
@ -618,12 +613,11 @@ function replayFixtureMessages(): SessionMessageInfo[] {
          state: {
            status: "completed",
            input: { command: "printf done" },
-            structured: { exit: 0 },
+            metadata: { exit: 0 },
            content: [
              { type: "text", text: "done" },
              { type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png", name: "image.png" },
            ],
-            result: { code: 0 },
          },
        },
        {
@ -634,8 +628,7 @@ function replayFixtureMessages(): SessionMessageInfo[] {
          state: {
            status: "running",
            input: { command: "pwd" },
-            structured: {},
-            content: [{ type: "text", text: "/workspace" }],
+            metadata: {},
          },
        },
        {
@ -646,7 +639,7 @@ function replayFixtureMessages(): SessionMessageInfo[] {
          state: {
            status: "error",
            input: { filePath: "/workspace/missing.ts" },
-            structured: { bytes: 0 },
+            metadata: { bytes: 0 },
            content: [{ type: "text", text: "partial" }],
            error: { type: "tool.error", message: "failed hard" },
          },
@ -679,7 +672,7 @@ function replayToolMessage(id: string) {
        state: {
          status: "completed",
          input: { command: "printf done" },
-          structured: { exit: 0 },
+          metadata: { exit: 0 },
          content: [{ type: "text", text: "done" }],
        },
      },
--- a/packages/cli/test/acp/permission-behavior.test.ts
+++ b/packages/cli/test/acp/permission-behavior.test.ts
@ -28,7 +28,7 @@ describe("acp permission behavior", () => {
      cwd: "/workspace",
      toolName: "edit",
      toolInput: { filePath: "/workspace/file.ts" },
-      structured: {},
+      metadata: {},
    })

    expect(writes).toEqual([])
@ -193,7 +193,7 @@ describe("acp permission behavior", () => {
            sessionID: "ses_edit",
            assistantMessageID: "msg_edit",
            callID: "call_edit",
-            structured: { files: [{ file: "file.ts" }], replacements: 1 },
+            metadata: { files: [{ file: "file.ts" }], replacements: 1 },
            content: [{ type: "text", text: "edited" }],
            executed: true,
          }),
@ -286,7 +286,7 @@ describe("acp permission behavior", () => {
            sessionID: "ses_patch",
            assistantMessageID: "msg_patch",
            callID: "call_patch",
-            structured: { files: [{ file: "first.ts" }, { file: "second.ts" }] },
+            metadata: { files: [{ file: "first.ts" }, { file: "second.ts" }] },
            content: [{ type: "text", text: "patched" }],
            executed: true,
          }),
--- a/packages/cli/test/acp/tool.test.ts
+++ b/packages/cli/test/acp/tool.test.ts
@ -63,7 +63,7 @@ describe("acp tools", () => {
          { type: "file", mime: "image/png", name: "image.png", uri: `data:image/png;base64,${image}` },
          { type: "file", mime: "text/plain", name: "note.txt", uri: "data:text/plain;base64,bm90ZQ==" },
        ],
-        structured: {},
+        metadata: {},
      }).content,
    ).toEqual([
      {
@ -93,7 +93,7 @@ describe("acp tools", () => {
          content: "created",
        },
        content: [{ type: "text", text: "wrote /tmp/file.ts" }],
-        structured: {},
+        metadata: {},
      }).content,
    ).toEqual([
      {
@ -103,20 +103,22 @@ describe("acp tools", () => {
    ])
  })

-  test("uses clean structured read content instead of model-facing formatting", () => {
+  test("unwraps read's JSON page envelope instead of showing model-facing formatting", () => {
    expect(
      completedToolUpdate({
        toolCallId: "tool-read",
        toolName: "read",
        input: { path: "/tmp/file.ts" },
-        content: [{ type: "text", text: "<content>1: first\n2: second</content>" }],
-        structured: {
-          type: "text-page",
-          content: "first\nsecond",
-          mime: "text/plain",
-          offset: 1,
-          truncated: false,
-        },
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { type: "text-page", content: "first\nsecond", mime: "text/plain", offset: 1, truncated: false },
+              null,
+              2,
+            ),
+          },
+        ],
      }).content,
    ).toEqual([{ type: "content", content: { type: "text", text: "first\nsecond" } }])

@ -125,13 +127,17 @@ describe("acp tools", () => {
        toolCallId: "tool-list",
        toolName: "read",
        input: { path: "/tmp" },
-        content: [],
-        structured: {
-          entries: [
-            { path: "a.ts", type: "file" },
-            { path: "src", type: "directory" },
-          ],
-        },
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              entries: [
+                { path: "a.ts", type: "file" },
+                { path: "src", type: "directory" },
+              ],
+            }),
+          },
+        ],
      }).content,
    ).toEqual([{ type: "content", content: { type: "text", text: "a.ts\nsrc" } }])
  })
@ -171,7 +177,7 @@ describe("acp tools", () => {
          newString: "after",
        },
        content: [{ type: "text", text: "Edit applied successfully." }],
-        structured: { output: "Edit applied successfully." },
+        metadata: { output: "Edit applied successfully." },
      }),
    ).toEqual({
      toolCallId: "tool-1",
@ -189,7 +195,7 @@ describe("acp tools", () => {
        },
      ],
      rawOutput: {
-        structured: { output: "Edit applied successfully." },
+        metadata: { output: "Edit applied successfully." },
      },
    })
  })
@ -209,7 +215,7 @@ describe("acp tools", () => {
    })
  })

-  test("builds completed raw output with structured data and optional result", () => {
+  test("builds completed raw output with optional metadata", () => {
    const attachments = [
      {
        type: "file",
@ -225,12 +231,10 @@ describe("acp tools", () => {
        toolName: "read",
        input: {},
        content: [],
-        structured: { output: "done", metadata: { exit: 0 }, attachments },
-        result: "done",
+        metadata: { output: "done", metadata: { exit: 0 }, attachments },
      }).rawOutput,
    ).toEqual({
-      structured: { output: "done", metadata: { exit: 0 }, attachments },
-      result: "done",
+      metadata: { output: "done", metadata: { exit: 0 }, attachments },
    })

    expect(
@ -239,9 +243,8 @@ describe("acp tools", () => {
        toolName: "read",
        input: {},
        content: [],
-        structured: { output: "done" },
      }).rawOutput,
-    ).toEqual({ structured: { output: "done" } })
+    ).toEqual({})
  })

  test("extracts image attachments only from data URLs", () => {
@ -255,7 +258,7 @@ describe("acp tools", () => {
          { type: "file", mime: "image/png", uri: "https://example.com/image.png" },
          { type: "file", mime: "text/plain", uri: "data:text/plain;base64,BBBB" },
        ],
-        structured: {},
+        metadata: {},
      }).content,
    ).toEqual([
      {
@ -272,7 +275,7 @@ describe("acp tools", () => {
        toolName: "read",
        input: { filePath: "/tmp/a" },
        content: [{ type: "text", text: "partial output" }],
-        structured: { path: "/tmp/a" },
+        metadata: { path: "/tmp/a" },
        error: "failed",
      }),
    ).toEqual({
@ -286,7 +289,7 @@ describe("acp tools", () => {
        { type: "content", content: { type: "text", text: "partial output" } },
        { type: "content", content: { type: "text", text: "failed" } },
      ],
-      rawOutput: { structured: { path: "/tmp/a" }, error: "failed" },
+      rawOutput: { metadata: { path: "/tmp/a" }, error: "failed" },
    })
  })
 })
--- a/packages/cli/test/import-boundaries.test.ts
+++ b/packages/cli/test/import-boundaries.test.ts
@ -23,7 +23,12 @@ describe("CLI frontend import boundaries", () => {

    expect(Object.keys(run).sort()).toEqual(["runNonInteractive", "runV1Bridge"])
    expect(Object.keys(mini).sort()).toEqual(["runMiniFrontend"])
-    expect(Object.keys(tool).sort()).toEqual(["toolInlineInfo", "toolOutputText"])
+    expect(Object.keys(tool).sort()).toEqual([
+      "nonEmptyToolContent",
+      "readDisplayText",
+      "toolInlineInfo",
+      "toolOutputText",
+    ])
    expect(Object.keys(cli.exports).filter((key) => key === "./mini" || key.startsWith("./mini/"))).toEqual([])
  })

--- a/packages/cli/test/run/noninteractive.test.ts
+++ b/packages/cli/test/run/noninteractive.test.ts
@ -134,15 +134,14 @@ function failedTool(inputID: string): V2Event[] {
        sessionID: "ses_1",
        assistantMessageID: "msg_failed_tool",
        callID: "call_failed_tool",
-        structured: { checkpoint: 1 },
-        content: [{ type: "text", text: "partial output" }],
+        metadata: { checkpoint: 1 },
      },
    },
    {
      id: "evt_failed_tool_terminal",
      created: 4,
      type: "session.tool.failed",
-      durable: { aggregateID: "ses_1", seq: 4, version: 1 },
+      durable: { aggregateID: "ses_1", seq: 4, version: 2 },
      data: {
        sessionID: "ses_1",
        assistantMessageID: "msg_failed_tool",
@ -190,12 +189,12 @@ function successfulGrep(inputID: string): V2Event[] {
      id: "evt_grep_success",
      created: 3,
      type: "session.tool.success",
-      durable: { aggregateID: "ses_1", seq: 3, version: 1 },
+      durable: { aggregateID: "ses_1", seq: 3, version: 2 },
      data: {
        sessionID: "ses_1",
        assistantMessageID: "msg_grep",
        callID: "call_grep",
-        structured: { matches: 2 },
+        metadata: { matches: 2 },
        content: [{ type: "text", text }],
        executed: false,
      },
@ -258,9 +257,7 @@ async function run(input: {
  spyOn(sdk.session, "wait").mockImplementation(() => input.wait?.() ?? wait.promise)
  spyOn(sdk.message, "list").mockImplementation(() =>
    ok({
-      data: input.messages?.(promptID) ?? [
-        { id: promptID, type: "user", text: "hello", time: { created: 1 } },
-      ],
+      data: input.messages?.(promptID) ?? [{ id: promptID, type: "user", text: "hello", time: { created: 1 } }],
      cursor: {},
    }),
  )
@ -316,7 +313,7 @@ afterEach(() => {
 })

 describe("runNonInteractivePrompt", () => {
-  test("keeps formatted tool output and compact structured metadata in JSON", async () => {
+  test("keeps formatted tool output and compact tool metadata in JSON", async () => {
    const output = await capture({ format: "json", turn: successfulGrep })
    const events = output.stdout
      .split("\n")
@ -332,13 +329,13 @@ describe("runNonInteractivePrompt", () => {
          status: "completed",
          output: expect.stringContaining("Found 2 matches"),
          metadata: {
-            structured: { matches: 2 },
+            metadata: { matches: 2 },
            content: [{ type: "text", text: expect.stringContaining("/src/a.ts") }],
          },
        },
      },
    })
-    expect(events[0].part.state.metadata.structured).toEqual({ matches: 2 })
+    expect(events[0].part.state.metadata.metadata).toEqual({ matches: 2 })
    expect(events[0].part.state.metadata.result).toBeUndefined()
  })

@ -534,7 +531,7 @@ describe("runNonInteractivePrompt", () => {
        id: "call_failed_tool",
        state: {
          status: "completed",
-          structured: { checkpoint: 1 },
+          metadata: { checkpoint: 1 },
          content: [{ type: "text", text: "partial output" }],
        },
      },
@ -544,7 +541,7 @@ describe("runNonInteractivePrompt", () => {
        id: "call_failed_tool",
        state: {
          status: "error",
-          structured: { checkpoint: 1 },
+          metadata: { checkpoint: 1 },
          content: [{ type: "text", text: "partial output" }],
          error: { message: "tool failed" },
        },
@ -574,7 +571,7 @@ describe("runNonInteractivePrompt", () => {
      },
    })
    expect(events[0].part.state.output).toBeUndefined()
-    expect(events[0].part.state.metadata.structured).toBeUndefined()
+    expect(events[0].part.state.metadata.metadata).toBeUndefined()
    expect(events[0].part.state.metadata.content).toBeUndefined()
    expect(output.stderr).toBe("")
  })