@vellumai/assistant 0.12.2-dev.202609162214.308bda0 → 0.12.2-dev.202609162314.7778bc8

package/docs/desktop-browser-cli.md

@@ -24,7 +24,7 @@ The desktop client bypasses personal-browser discovery, extension reconnect wait
 
 Tab IDs are ephemeral numeric aliases for this managed browser's CDP target IDs. They are never personal extension tab IDs. Initial attachment selects an existing HTTP(S) page or opens a blank tab. Use `tabs list` and `tabs select --tab-id <id>` to choose explicitly. Navigation, tab selection, document replacement and release clear the desktop snapshot map. Personal-browser snapshots use a separate namespace.
 
-CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications are outside the browser CLI; users can interact with them directly in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation.
+CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications are outside the browser CLI; users can interact with them directly in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation. For logins, the assistant uses saved credentials first and securely collects missing credentials with `assistant credentials prompt`, then fills the login form itself. Every CAPTCHA and bot-detection challenge, including sliders and press-and-hold checks, is handed to the user before the assistant attempts it. When human interaction is needed, the assistant calls `ask_question` with `desktopHelp: { message, doneLabel, skipLabel }` in the user's language. The tool releases held browser input and reserves the desktop before publishing a question with `presentation: "virtual_desktop"`. The live viewer mounts only in the attended Electron window, with browser focus as a fallback on older shells and the web, so conversations release it when focus changes. A busy viewer offers Reconnect if the previous connection has not finished closing. The compact card lives in the scrolling message transcript, with expandable instructions and a preview capped at 384 pixels wide. It hosts the shared live viewer, with Step In opening its full desktop modal and Done or Skip resolving the existing question response. The assistant retains an exclusive human-help reservation while waiting. Done resumes the same conversation's automation lease for its fresh snapshot; Skip, closure, timeout and cancellation release it. The browser idle timer does not expire a pending human-help reservation. The live preview connects after Show live preview or Step In, and reuses an already-open picture-in-picture viewer. Other devices receiving the card do not automatically open a stream. When the request resolves, its interactive viewer closes or returns to the read-only PiP session that was open before the request. Skip does not imply the obstacle was resolved. Older clients show the same request as a normal Done/Skip question, with model-localized labels retained in history. Channels without dynamic UI return guidance to continue in the app rather than waiting on an unusable card.
 
 The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Turn-triggered cancellation retries cleanup automatically until it succeeds or ownership changes. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
 

package/openapi.yaml

@@ -21322,6 +21322,9 @@ paths:
                                             additionalProperties: false
                                         freeTextPlaceholder:
                                           type: string
+                                        presentation:
+                                          type: string
+                                          const: virtual_desktop
                                       required:
                                         - id
                                         - question
@@ -21364,6 +21367,9 @@ paths:
                                             additionalProperties: false
                                         freeTextPlaceholder:
                                           type: string
+                                        presentation:
+                                          type: string
+                                          const: virtual_desktop
                                       required:
                                         - id
                                         - question
@@ -21833,6 +21839,9 @@ paths:
                                                     additionalProperties: false
                                                 freeTextPlaceholder:
                                                   type: string
+                                                presentation:
+                                                  type: string
+                                                  const: virtual_desktop
                                               required:
                                                 - id
                                                 - question
@@ -21875,6 +21884,9 @@ paths:
                                                     additionalProperties: false
                                                 freeTextPlaceholder:
                                                   type: string
+                                                presentation:
+                                                  type: string
+                                                  const: virtual_desktop
                                               required:
                                                 - id
                                                 - question
@@ -25728,6 +25740,9 @@ paths:
                                     additionalProperties: false
                                 freeTextPlaceholder:
                                   type: string
+                                presentation:
+                                  type: string
+                                  const: virtual_desktop
                               required:
                                 - id
                                 - question

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609162214.308bda0",
+  "version": "0.12.2-dev.202609162314.7778bc8",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/agent-loop.test.ts

@@ -2550,6 +2550,141 @@ describe("AgentLoop", () => {
     expect(noRetryNudge).toBeUndefined();
   });
 
+  // A native web search left deferred by the same assistant turn (a
+  // server_tool_use with no result, alongside the client tool call) runs on
+  // the next request only if that request's tool-result message holds
+  // tool_result blocks alone. The coaching then rides inside the errored
+  // tool_result instead of as a trailing text block.
+  test("folds retry coaching into the tool_result when the assistant turn left a server tool deferred", async () => {
+    const mixedTurn: ProviderResponse = {
+      content: [
+        {
+          type: "tool_use",
+          id: "t1",
+          name: "read_file",
+          input: { path: "/missing.txt" },
+        },
+        {
+          type: "server_tool_use",
+          id: "srvtoolu_1",
+          name: "web_search",
+          input: { query: "news" },
+        },
+      ],
+      model: "mock-model",
+      usage: { inputTokens: 10, outputTokens: 5 },
+      stopReason: "tool_use",
+    };
+    const { provider, calls } = createMockProvider([
+      mixedTurn,
+      textResponse("Reported the missing file."),
+    ]);
+    const toolExecutor = async () => ({
+      content: "Error: HTTP 404",
+      isError: true,
+    });
+
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+      tools: dummyTools,
+      toolExecutor,
+    });
+    await loop.run({
+      requestId: "test-request",
+      messages: [userMessage],
+      onEvent: () => {},
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    expect(calls).toHaveLength(2);
+    const followUpMessages = calls[1].messages;
+    const followUp = followUpMessages[followUpMessages.length - 1];
+    expect(followUp.role).toBe("user");
+    expect(followUp.content.map((b) => b.type)).toEqual(["tool_result"]);
+    const erroredToolResult = followUp.content[0] as Extract<
+      ContentBlock,
+      { type: "tool_result" }
+    >;
+    expect(erroredToolResult.is_error).toBe(true);
+    expect(erroredToolResult.content).toContain("Error: HTTP 404");
+    expect(erroredToolResult.content).toContain("looks recoverable");
+  });
+
+  // A deferred search answered by a message with text after the results
+  // (history assembled elsewhere) is rejected by the provider as unpaired.
+  // The ordering-repair retry stamps the synthetic result rather than
+  // re-sending the same history.
+  test("repairs a deferred search rejected as unpaired instead of re-sending the same history", async () => {
+    const mixedTurn: Message = {
+      role: "assistant",
+      content: [
+        {
+          type: "tool_use",
+          id: "t1",
+          name: "read_file",
+          input: { path: "/a" },
+        },
+        {
+          type: "server_tool_use",
+          id: "srvtoolu_1",
+          name: "web_search",
+          input: { query: "news" },
+        },
+      ],
+    };
+    const answeredWithText: Message = {
+      role: "user",
+      content: [
+        {
+          type: "tool_result",
+          tool_use_id: "t1",
+          content: "Error: HTTP 404",
+          is_error: true,
+        },
+        { type: "text", text: "<system_notice>retry</system_notice>" },
+      ],
+    };
+    const { provider, calls } = createMockProvider([
+      new Error(
+        "Anthropic API error (400): messages.1: `web_search` tool use with id `srvtoolu_1` was found without a corresponding `web_search_tool_result` block",
+      ),
+      textResponse("recovered"),
+    ]);
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
+    const events: AgentEvent[] = [];
+
+    const { history } = await loop.run({
+      requestId: "test-request",
+      messages: [userMessage, mixedTurn, answeredWithText],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    expect(calls).toHaveLength(2);
+    expect(events.filter((e) => e.type === "error")).toHaveLength(0);
+    // Deep repair stamped the synthetic result on the orphaned search, and the
+    // outbound sanitizer then summarized the answered pair as text, so the
+    // retry carries no unanswered server_tool_use.
+    expect(calls[1].messages[1].content.map((b) => b.type)).toEqual([
+      "tool_use",
+      "text",
+    ]);
+    expect(calls[1].messages[1].content[1]).toMatchObject({
+      type: "text",
+      text: expect.stringContaining("results unavailable"),
+    });
+    expect(history[history.length - 1]).toEqual({
+      role: "assistant",
+      content: [{ type: "text", text: "recovered" }],
+    });
+  });
+
   // Retry coaching stops after a tool fails 3 times in a row — past that the
   // error is likely unrecoverable and further coaching only burns tokens.
   test("stops appending retry coaching after 3 consecutive failures of a tool", async () => {

package/src/__tests__/anthropic-provider.test.ts

@@ -1650,6 +1650,61 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     ).toHaveLength(0);
   });
 
+  test("mixed tail answered by a tool_result plus trailing text gets a synthetic web_search_tool_result", async () => {
+    // Text after the client result closes the assistant turn on the provider
+    // side, which then rejects the unanswered search as unpaired. The search
+    // is an orphan here, so the synthetic error result keeps the request
+    // valid at the cost of that one search.
+    const messages: Message[] = [
+      userMsg("Do things"),
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "web_fetch", input: {} },
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_b",
+            name: "web_search",
+            input: { query: "test" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            tool_use_id: "tu_a",
+            content: "Error: HTTP 404",
+            is_error: true,
+          },
+          { type: "text", text: "<system_notice>retry</system_notice>" },
+        ],
+      },
+    ];
+    await provider.sendMessage(messages);
+
+    const sent = lastStreamParams!.messages as Array<{
+      role: string;
+      content: Array<{ type: string; tool_use_id?: string }>;
+    }>;
+
+    // The repaired pair leaves the mixed message: ensureToolPairing keeps the
+    // client tool_result adjacent to its tool_use and moves the now-answered
+    // server pair into its own assistant turn, ahead of the trailing text.
+    expect(sent.map((m) => m.content.map((b) => b.type))).toEqual([
+      ["text"],
+      ["tool_use"],
+      ["tool_result"],
+      ["server_tool_use", "web_search_tool_result"],
+      ["text"],
+    ]);
+    expect(sent[3].content[1]).toMatchObject({
+      type: "web_search_tool_result",
+      tool_use_id: "srvtoolu_b",
+    });
+  });
+
   test("deferred mixed heartbeat shape with text and multiple searches goes out verbatim", async () => {
     const messages: Message[] = [
       userMsg("Heartbeat: check the file and the news"),

package/src/__tests__/history-repair.test.ts

@@ -643,6 +643,59 @@ describe("repairHistory", () => {
     ]);
   });
 
+  test("deferred mixed tail answered by a tool_result plus trailing text gets a synthetic result", () => {
+    // Text after the client result closes the assistant turn on the provider
+    // side, which then rejects the unanswered search as unpaired. The search
+    // is an orphan here, so the synthetic error result keeps the request
+    // valid at the cost of that one search. `deepRepairHistory` is the loop's
+    // recovery path for that rejection.
+    const messages: Message[] = [
+      { role: "user", content: [{ type: "text", text: "Check both" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "web_fetch", input: {} },
+          {
+            type: "server_tool_use",
+            id: "stu_deferred",
+            name: "web_search",
+            input: { query: "news" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            tool_use_id: "tu_a",
+            content: "Error: HTTP 404",
+            is_error: true,
+          },
+          { type: "text", text: "<system_notice>retry</system_notice>" },
+        ],
+      },
+    ];
+
+    const { messages: repaired, stats } = deepRepairHistory(messages);
+
+    expect(stats.missingToolResultsInserted).toBe(1);
+    expect(repaired).toHaveLength(3);
+    expect(repaired[1].content.map((b) => b.type)).toEqual([
+      "tool_use",
+      "server_tool_use",
+      "web_search_tool_result",
+    ]);
+    expect(repaired[1].content[2]).toMatchObject({
+      type: "web_search_tool_result",
+      tool_use_id: "stu_deferred",
+    });
+    expect(repaired[2].content.map((b) => b.type)).toEqual([
+      "tool_result",
+      "text",
+    ]);
+  });
+
   test("cross-message server tool pair from a completed deferred execution survives a reload untouched", () => {
     const messages: Message[] = [
       { role: "user", content: [{ type: "text", text: "Check both" }] },

package/src/__tests__/server-tool-pairing.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+
+import { analyzeServerToolPairing } from "../providers/server-tool-pairing.js";
+import type { ContentBlock, Message } from "../providers/types.js";
+
+const DEFERRED_ID = "srvtoolu_deferred";
+
+const opener: Message = {
+  role: "user",
+  content: [{ type: "text", text: "Check both" }],
+};
+
+/** Assistant turn calling a client tool and a native web search together. */
+const mixedTail: Message = {
+  role: "assistant",
+  content: [
+    { type: "tool_use", id: "tu_a", name: "web_fetch", input: {} },
+    {
+      type: "server_tool_use",
+      id: DEFERRED_ID,
+      name: "web_search",
+      input: { query: "news" },
+    },
+  ],
+};
+
+const clientResult: ContentBlock = {
+  type: "tool_result",
+  tool_use_id: "tu_a",
+  content: "Error: HTTP 404",
+  is_error: true,
+};
+
+const guidance: ContentBlock = {
+  type: "text",
+  text: "<system_notice>retry</system_notice>",
+};
+
+describe("analyzeServerToolPairing", () => {
+  test("an unanswered use with nothing after it is deferred", () => {
+    const pairing = analyzeServerToolPairing([opener, mixedTail]);
+
+    expect(pairing.deferredUseIds).toEqual(new Set([DEFERRED_ID]));
+    expect(pairing.resolvedPairIds.size).toBe(0);
+  });
+
+  test("an unanswered use answered by tool_result blocks alone is deferred", () => {
+    const pairing = analyzeServerToolPairing([
+      opener,
+      mixedTail,
+      { role: "user", content: [clientResult] },
+    ]);
+
+    expect(pairing.deferredUseIds).toEqual(new Set([DEFERRED_ID]));
+  });
+
+  test("guidance text after the tool_result makes the use an orphan, not a deferral", () => {
+    // The trailing text closes the assistant turn on the provider side, which
+    // then rejects the unanswered use as unpaired; the repair passes stamp a
+    // synthetic result instead of preserving it.
+    const pairing = analyzeServerToolPairing([
+      opener,
+      mixedTail,
+      { role: "user", content: [clientResult, guidance] },
+    ]);
+
+    expect(pairing.deferredUseIds.size).toBe(0);
+    expect(pairing.resolvedPairIds.size).toBe(0);
+  });
+
+  test("a user text message after the tool_result message makes the use an orphan", () => {
+    const pairing = analyzeServerToolPairing([
+      opener,
+      mixedTail,
+      { role: "user", content: [clientResult] },
+      { role: "user", content: [{ type: "text", text: "also do this" }] },
+    ]);
+
+    expect(pairing.deferredUseIds.size).toBe(0);
+  });
+
+  test("a use answered in its own message is resolved and never deferred", () => {
+    const pairing = analyzeServerToolPairing([
+      opener,
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_done",
+            name: "web_search",
+            input: { query: "news" },
+          },
+          {
+            type: "web_search_tool_result",
+            tool_use_id: "srvtoolu_done",
+            content: [],
+          },
+        ],
+      },
+      { role: "user", content: [guidance] },
+    ]);
+
+    expect(pairing.resolvedPairIds).toEqual(new Set(["srvtoolu_done"]));
+    expect(pairing.deferredUseIds.size).toBe(0);
+  });
+});

package/src/__tests__/tool-result-follow-up.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildToolResultFollowUp } from "../agent/tool-result-follow-up.js";
+import type { ContentBlock, Message, TextContent } from "../providers/types.js";
+
+const opener: Message = {
+  role: "user",
+  content: [{ type: "text", text: "Check both" }],
+};
+
+/** Assistant turn calling two client tools and a native web search together. */
+const mixedTurn: Message = {
+  role: "assistant",
+  content: [
+    { type: "tool_use", id: "tu_a", name: "web_fetch", input: {} },
+    { type: "tool_use", id: "tu_b", name: "file_read", input: {} },
+    {
+      type: "server_tool_use",
+      id: "srvtoolu_deferred",
+      name: "web_search",
+      input: { query: "news" },
+    },
+  ],
+};
+
+/** The same turn without the search: nothing is deferred. */
+const clientOnlyTurn: Message = {
+  role: "assistant",
+  content: mixedTurn.content.filter((b) => b.type === "tool_use"),
+};
+
+const erroredResult: ContentBlock = {
+  type: "tool_result",
+  tool_use_id: "tu_a",
+  content: "Error: HTTP 404",
+  is_error: true,
+};
+
+const okResult: ContentBlock = {
+  type: "tool_result",
+  tool_use_id: "tu_b",
+  content: "file contents",
+  is_error: false,
+};
+
+const guidance: TextContent = {
+  type: "text",
+  text: "<system_notice>retry</system_notice>",
+};
+
+describe("buildToolResultFollowUp", () => {
+  test("returns the results untouched when there is no guidance", () => {
+    const results = [erroredResult, okResult];
+
+    expect(buildToolResultFollowUp([opener, mixedTurn], results, [])).toBe(
+      results,
+    );
+  });
+
+  test("appends guidance as separate blocks when no server tool is deferred", () => {
+    const followUp = buildToolResultFollowUp(
+      [opener, clientOnlyTurn],
+      [erroredResult, okResult],
+      [guidance],
+    );
+
+    expect(followUp).toEqual([erroredResult, okResult, guidance]);
+  });
+
+  test("folds guidance into the errored tool_result when a server tool is deferred", () => {
+    const followUp = buildToolResultFollowUp(
+      [opener, mixedTurn],
+      [erroredResult, okResult],
+      [guidance],
+    );
+
+    expect(followUp.map((b) => b.type)).toEqual(["tool_result", "tool_result"]);
+    expect(followUp[0]).toEqual({
+      ...erroredResult,
+      content: `Error: HTTP 404\n\n${guidance.text}`,
+    });
+    expect(followUp[1]).toBe(okResult);
+  });
+
+  test("falls back to the last tool_result when none errored", () => {
+    const followUp = buildToolResultFollowUp(
+      [opener, mixedTurn],
+      [okResult, { ...okResult, tool_use_id: "tu_a" }],
+      [guidance],
+    );
+
+    expect(followUp.map((b) => b.type)).toEqual(["tool_result", "tool_result"]);
+    expect(followUp[0]).toBe(okResult);
+    expect(followUp[1]).toMatchObject({
+      tool_use_id: "tu_a",
+      content: `file contents\n\n${guidance.text}`,
+    });
+  });
+});

package/src/agent/loop.ts

@@ -42,6 +42,7 @@ import type {
   Provider,
   ProviderResponse,
   SendMessageOptions,
+  TextContent,
   ToolDefinition,
   ToolResultContent,
 } from "../providers/types.js";
@@ -74,6 +75,7 @@ import {
   isRepairableOrderingError,
   isUserTerminalHistoryError,
 } from "./history-repair/history-repair.js";
+import { buildToolResultFollowUp } from "./tool-result-follow-up.js";
 
 const log = getLogger("agent-loop");
 
@@ -1558,7 +1560,7 @@ export class AgentLoop {
       turn: number,
     ): Promise<{
       resultBlocks: ContentBlock[];
-      additionalContextBlocks: ContentBlock[];
+      additionalContextBlocks: TextContent[];
     }> => {
       if (conversationDir) {
         const toolCallByUseId = new Map(
@@ -1583,7 +1585,7 @@ export class AgentLoop {
         180_000;
 
       const resultBlocks: ContentBlock[] = [];
-      const additionalContextBlocks: ContentBlock[] = [];
+      const additionalContextBlocks: TextContent[] = [];
       for (const block of rawBlocks) {
         if (block.type !== "tool_result") {
           resultBlocks.push(block);
@@ -2964,16 +2966,20 @@ export class AgentLoop {
 
         toolUseTurns++;
 
-        // Append any guidance a post-tool-use hook surfaced via
-        // `additionalContext` (e.g. tool-error retry coaching) as separate
-        // blocks. They join the provider-bound history below but were not part
-        // of the tool_result events emitted above, so the model sees the
-        // guidance while the client-facing and persisted tool output stay the
-        // tool's actual result.
-        resultBlocks.push(...additionalContextBlocks);
-
-        // Add tool results as a user message and continue the loop.
-        history.push({ role: "user", content: resultBlocks });
+        // Add the tool results, plus any guidance a post-tool-use hook
+        // surfaced via `additionalContext` (e.g. tool-error retry coaching),
+        // as a user message and continue the loop. The guidance joins the
+        // provider-bound history only: it was not part of the tool_result
+        // events emitted above, so the client-facing and persisted tool
+        // output stay the tool's actual result.
+        history.push({
+          role: "user",
+          content: buildToolResultFollowUp(
+            history,
+            resultBlocks,
+            additionalContextBlocks,
+          ),
+        });
 
         // Invoke checkpoint callback after tool results are in history.
         // Handoff takes precedence over the budget gate: a handoff decision

package/src/agent/tool-result-follow-up.ts

@@ -0,0 +1,70 @@
+// Content of the user message that answers a tool-calling assistant turn:
+// the tool_result blocks plus any guidance a post-tool-use hook surfaced via
+// `additionalContext`.
+
+import { analyzeServerToolPairing } from "../providers/server-tool-pairing.js";
+import type {
+  ContentBlock,
+  Message,
+  TextContent,
+  ToolResultContent,
+} from "../providers/types.js";
+
+/**
+ * Hook guidance rides as separate blocks after the results, so the model sees
+ * it while each tool_result stays the tool's actual output. The exception is
+ * an assistant turn that left a server tool (native web search) deferred: the
+ * provider runs a deferred server tool only when the answering message holds
+ * tool_result blocks alone, and any block after the results closes the
+ * assistant turn, after which the provider rejects the unanswered server tool
+ * as unpaired. The guidance is then folded into the content of the last
+ * errored tool_result (the last tool_result when none errored), where the
+ * model still sees it and the search still runs.
+ */
+export function buildToolResultFollowUp(
+  history: ReadonlyArray<Message>,
+  resultBlocks: ContentBlock[],
+  additionalContextBlocks: ReadonlyArray<TextContent>,
+): ContentBlock[] {
+  if (additionalContextBlocks.length === 0) {
+    return resultBlocks;
+  }
+  const targetIndex = foldTargetIndex(resultBlocks);
+  const pairing = analyzeServerToolPairing([
+    ...history,
+    { role: "user", content: resultBlocks },
+  ]);
+  if (pairing.deferredUseIds.size === 0 || targetIndex < 0) {
+    return [...resultBlocks, ...additionalContextBlocks];
+  }
+  const target = resultBlocks[targetIndex] as ToolResultContent;
+  const folded: ToolResultContent = {
+    ...target,
+    content: [target.content, ...additionalContextBlocks.map((b) => b.text)]
+      .filter((text) => text.length > 0)
+      .join("\n\n"),
+  };
+  return resultBlocks.map((block, index) =>
+    index === targetIndex ? folded : block,
+  );
+}
+
+/** Index of the last errored tool_result, else the last tool_result, else -1. */
+function foldTargetIndex(blocks: ReadonlyArray<ContentBlock>): number {
+  let lastResult = -1;
+  for (let index = blocks.length - 1; index >= 0; index--) {
+    const block = blocks[index];
+    // guard:allow-tool-result-only: the answering user message carries client
+    // tool_result blocks only; server-side results live in assistant messages.
+    if (block.type !== "tool_result") {
+      continue;
+    }
+    if (block.is_error) {
+      return index;
+    }
+    if (lastResult < 0) {
+      lastResult = index;
+    }
+  }
+  return lastResult;
+}