@vellumai/assistant 0.11.2-dev.202608050309.fa8263f → 0.11.2-dev.202608050507.7e832db

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.2-dev.202608050309.fa8263f",
+  "version": "0.11.2-dev.202608050507.7e832db",
   "license": "MIT",
   "type": "module",
   "exports": {

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

@@ -1410,9 +1410,11 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     expect(sent[2].content[0].type).toBe("text");
   });
 
-  test("orphaned server_tool_use at end of messages gets synthetic result (no synthetic user append)", async () => {
-    // Orphaned server_tool_use at the end should get a synthetic
-    // web_search_tool_result but no synthetic user message.
+  test("unanswered server_tool_use in the final assistant message is left intact for deferred execution", async () => {
+    // When the final assistant message ends with an unanswered
+    // server_tool_use, the API executes the search on this request (the
+    // pause_turn / deferred-execution contract). The tail must go back
+    // verbatim with no synthetic result, or the search is cancelled.
     const messages: Message[] = [
       userMsg("Search something"),
       {
@@ -1434,12 +1436,11 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{ type: string; tool_use_id?: string }>;
     }>;
 
-    // Original 2 messages, with synthetic result injected in assistant message
+    // Original 2 messages, assistant tail verbatim: no synthetic result
     expect(sent).toHaveLength(2);
     expect(sent[1].role).toBe("assistant");
+    expect(sent[1].content).toHaveLength(1);
     expect(sent[1].content[0].type).toBe("server_tool_use");
-    expect(sent[1].content[1].type).toBe("web_search_tool_result");
-    expect(sent[1].content[1].tool_use_id).toBe("srvtoolu_end");
   });
 
   test("server_tool_use with matching web_search_tool_result passes through unchanged", async () => {
@@ -1568,7 +1569,11 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     expect(webSearchResults[0].tool_use_id).toBe("srvtoolu_search");
   });
 
-  test("mixed tool_use and server_tool_use — only client-side tool_use gets pairing, server tools pass through", async () => {
+  test("mixed tool_use and deferred server_tool_use tail goes out verbatim", async () => {
+    // The mixed parallel group is the deferred-execution trigger: the API
+    // returns stop_reason tool_use without running the search, and runs it on
+    // the next request when the client tool results come back with the
+    // assistant message unchanged. No split, no synthetic result.
     const messages: Message[] = [
       userMsg("Do things"),
       {
@@ -1583,7 +1588,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
           },
         ],
       },
-      // Only tu_a has a result — server_tool_use doesn't need one in the user message
+      // Only tu_a has a result; the deferred search has none yet
       toolResultMsg("tu_a", "result A"),
     ];
     await provider.sendMessage(messages);
@@ -1597,27 +1602,139 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       }>;
     }>;
 
-    // Assistant message should have tool_use in paired portion, server_tool_use in carryover
-    // ensureToolPairing splits: paired = [tool_use(tu_a)], carryover = [server_tool_use(srvtoolu_b)]
-    // Result: assistant(tool_use) → user(tool_result) → assistant(server_tool_use) → user(synthetic_continuation)
+    // assistant(tool_use, server_tool_use) → user(tool_result), verbatim
+    expect(sent).toHaveLength(3);
     const assistantMsg = sent[1];
     expect(assistantMsg.role).toBe("assistant");
-    expect(assistantMsg.content[0].type).toBe("tool_use");
+    expect(assistantMsg.content.map((b) => b.type)).toEqual([
+      "tool_use",
+      "server_tool_use",
+    ]);
 
     const userAfterAssistant = sent[2];
     expect(userAfterAssistant.role).toBe("user");
-    // Only tool_result for tu_a — no synthetic web_search_tool_result
     expect(userAfterAssistant.content[0]).toMatchObject({
       type: "tool_result",
       tool_use_id: "tu_a",
     });
 
-    // server_tool_use preserved in a carryover assistant message with synthetic result
-    const carryoverAssistant = sent[3];
-    expect(carryoverAssistant.role).toBe("assistant");
-    expect(carryoverAssistant.content[0].type).toBe("server_tool_use");
-    expect(carryoverAssistant.content[1].type).toBe("web_search_tool_result");
-    expect(carryoverAssistant.content[1].tool_use_id).toBe("srvtoolu_b");
+    // No synthetic web_search_tool_result anywhere; the API runs the search
+    const allBlocks = sent.flatMap((m) => m.content);
+    expect(
+      allBlocks.filter((b) => b.type === "web_search_tool_result"),
+    ).toHaveLength(0);
+  });
+
+  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"),
+      {
+        role: "assistant",
+        content: [
+          { type: "text", text: "Checking both." },
+          { type: "tool_use", id: "tu_read", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_s1",
+            name: "web_search",
+            input: { query: "news one" },
+          },
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_s2",
+            name: "web_search",
+            input: { query: "news two" },
+          },
+        ],
+      },
+      toolResultMsg("tu_read", "file contents"),
+    ];
+    await provider.sendMessage(messages);
+
+    const sent = lastStreamParams!.messages as Array<{
+      role: string;
+      content: Array<{ type: string; id?: string; tool_use_id?: string }>;
+    }>;
+
+    expect(sent).toHaveLength(3);
+    expect(sent[1].content.map((b) => b.type)).toEqual([
+      "text",
+      "tool_use",
+      "server_tool_use",
+      "server_tool_use",
+    ]);
+    const allBlocks = sent.flatMap((m) => m.content);
+    expect(
+      allBlocks.filter((b) => b.type === "web_search_tool_result"),
+    ).toHaveLength(0);
+  });
+
+  test("cross-message server tool pair from a completed deferred execution is preserved verbatim", async () => {
+    // After a deferred search executes, history carries the split pair: the
+    // server_tool_use in one assistant message and its web_search_tool_result
+    // heading the next assistant message. Both sides must pass through
+    // untouched: no synthetic result on the use, no text downgrade on the
+    // result.
+    const messages: Message[] = [
+      userMsg("Check the file and the news"),
+      {
+        role: "assistant",
+        content: [
+          { type: "text", text: "On it." },
+          { type: "tool_use", id: "tu_a", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_deferred",
+            name: "web_search",
+            input: { query: "news" },
+          },
+        ],
+      },
+      toolResultMsg("tu_a", "file contents"),
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "web_search_tool_result",
+            tool_use_id: "srvtoolu_deferred",
+            content: [
+              {
+                type: "web_search_result",
+                url: "https://example.com",
+                title: "Example",
+                encrypted_content: "enc_deferred",
+              },
+            ],
+          },
+          { type: "text", text: "Here is the news." },
+        ],
+      },
+      userMsg("thanks, anything else?"),
+    ];
+    await provider.sendMessage(messages);
+
+    const sent = lastStreamParams!.messages as Array<{
+      role: string;
+      content: Array<{ type: string; id?: string; tool_use_id?: string }>;
+    }>;
+
+    expect(sent).toHaveLength(5);
+    expect(sent[1].content.map((b) => b.type)).toEqual([
+      "text",
+      "tool_use",
+      "server_tool_use",
+    ]);
+    expect(sent[3].content.map((b) => b.type)).toEqual([
+      "web_search_tool_result",
+      "text",
+    ]);
+    // Exactly the original result block, still a result block
+    const allBlocks = sent.flatMap((m) => m.content);
+    const results = allBlocks.filter(
+      (b) => b.type === "web_search_tool_result",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].tool_use_id).toBe("srvtoolu_deferred");
   });
 
   test("orphaned server_tool_use from interrupted stream gets repaired in multi-turn conversation", async () => {

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

@@ -572,8 +572,10 @@ describe("repairHistory", () => {
     ).toBe(true);
   });
 
-  test("trailing server_tool_use gets synthetic result in same assistant message", () => {
-    // No trailing user message needed — result goes in the assistant message
+  test("trailing server_tool_use is preserved as a deferred execution", () => {
+    // An unanswered server_tool_use at the tail is a deferred search the
+    // provider executes on the next request; repairing it would cancel the
+    // search.
     const messages: Message[] = [
       { role: "user", content: [{ type: "text", text: "Go" }] },
       {
@@ -591,21 +593,107 @@ describe("repairHistory", () => {
 
     const { messages: repaired, stats } = repairHistory(messages);
 
-    expect(stats.missingToolResultsInserted).toBe(1);
-    // Result is in the assistant message
+    expect(stats.missingToolResultsInserted).toBe(0);
     expect(repaired).toHaveLength(2);
     expect(repaired[1].role).toBe("assistant");
-    expect(repaired[1].content).toHaveLength(2);
-    expect(repaired[1].content[1]).toMatchObject({
-      type: "web_search_tool_result",
-      tool_use_id: "stu_1",
-      content: {
-        type: "web_search_tool_result_error",
-        error_code: "unavailable",
-      },
+    expect(repaired[1].content).toHaveLength(1);
+    expect(repaired[1].content[0]).toMatchObject({
+      type: "server_tool_use",
+      id: "stu_1",
     });
   });
 
+  test("deferred mixed tail (tool_use + server_tool_use, then tool_result) survives a reload untouched", () => {
+    // Persisted mid-deferral shape: the model called a client tool and a
+    // search in one parallel group, the client result came back, and the
+    // daemon reloaded before the next model call ran the search.
+    const messages: Message[] = [
+      { role: "user", content: [{ type: "text", text: "Check both" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "file_read", 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: "file" },
+        ],
+      },
+    ];
+
+    const { messages: repaired, stats } = repairHistory(messages);
+
+    expect(stats.missingToolResultsInserted).toBe(0);
+    expect(stats.orphanToolResultsDowngraded).toBe(0);
+    expect(repaired).toHaveLength(3);
+    expect(repaired[1].content.map((b) => b.type)).toEqual([
+      "tool_use",
+      "server_tool_use",
+    ]);
+  });
+
+  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" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "stu_split",
+            name: "web_search",
+            input: { query: "news" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "tu_a", content: "file" },
+        ],
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "web_search_tool_result",
+            tool_use_id: "stu_split",
+            content: [
+              {
+                type: "web_search_result",
+                url: "https://example.com",
+                title: "Example",
+              },
+            ],
+          },
+          { type: "text", text: "Found it." },
+        ],
+      },
+    ];
+
+    const { messages: repaired, stats } = repairHistory(messages);
+
+    expect(stats.missingToolResultsInserted).toBe(0);
+    expect(stats.orphanToolResultsDowngraded).toBe(0);
+    expect(repaired[1].content.map((b) => b.type)).toEqual([
+      "tool_use",
+      "server_tool_use",
+    ]);
+    expect(repaired[3].content.map((b) => b.type)).toEqual([
+      "web_search_tool_result",
+      "text",
+    ]);
+  });
+
   test("synthetic web_search_tool_result is placed immediately after its server_tool_use, not at end", () => {
     // Regression: synthetic results appended to the end of the content array
     // get separated from their server_tool_use by ensureToolPairing's split
@@ -648,6 +736,12 @@ describe("repairHistory", () => {
           },
         ],
       },
+      // A later assistant message closes the deferral window: the searches
+      // never executed, so they are genuine orphans.
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "Skill ready." }],
+      },
     ];
 
     const { messages: repaired, stats } = repairHistory(messages);
@@ -866,6 +960,12 @@ describe("repairHistory", () => {
           },
         ],
       },
+      // A later exchange closes the deferral window for stu_missing_result.
+      { role: "user", content: [{ type: "text", text: "and?" }] },
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "done" }],
+      },
     ];
 
     const { messages: repaired, stats } = repairHistory(messages);

package/src/__tests__/web-search-history.test.ts

@@ -328,4 +328,100 @@ describe("stripHistoricalWebSearchResults", () => {
     const afterTypes = messages[0].content.map((b) => b.type);
     expect(afterTypes).toEqual(beforeTypes);
   });
+
+  test("drops the server_tool_use of a cross-message pair from a deferred execution", () => {
+    // Deferred execution places the web_search_tool_result at the head of the
+    // assistant message after the client tool round-trip. Both sides of the
+    // pair must go together, or the leftover server_tool_use reads as an
+    // orphan and gets a synthetic error result downstream.
+    const messages: Message[] = [
+      { role: "user", content: [{ type: "text", text: "Check both" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "text", text: "On it" },
+          { type: "tool_use", id: "tu_read", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "stu_deferred",
+            name: "web_search",
+            input: { query: "deferred query" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "tu_read", content: "file" },
+        ],
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "web_search_tool_result",
+            tool_use_id: "stu_deferred",
+            content: [
+              {
+                type: "web_search_result",
+                url: "https://example.com",
+                title: "Deferred",
+                encrypted_content: "tok",
+              },
+            ],
+          },
+          { type: "text", text: "Found it." },
+        ],
+      },
+    ];
+
+    const { messages: result, stats } =
+      stripHistoricalWebSearchResults(messages);
+
+    // The use in the earlier assistant message is dropped with its result
+    expect(result[1].content.map((b) => b.type)).toEqual(["text", "tool_use"]);
+    const summarized = result[3].content[0];
+    expect(summarized.type).toBe("text");
+    expect((summarized as { text: string }).text).toContain("deferred query");
+    expect((summarized as { text: string }).text).toContain(
+      "https://example.com",
+    );
+    expect(stats.serverToolUsesDropped).toBe(1);
+    expect(stats.blocksStripped).toBe(1);
+    expect(stats.messagesModified).toBe(2);
+  });
+
+  test("leaves a pending server_tool_use with no result anywhere untouched", () => {
+    // A resultless use at the tail is a deferred search the provider executes
+    // on this request; stripping it would cancel the search.
+    const messages: Message[] = [
+      { role: "user", content: [{ type: "text", text: "Check both" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_read", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "stu_pending",
+            name: "web_search",
+            input: { query: "pending" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "tu_read", content: "file" },
+        ],
+      },
+    ];
+
+    const { messages: result, stats } =
+      stripHistoricalWebSearchResults(messages);
+
+    expect(result).toEqual(messages);
+    expect(stats.serverToolUsesDropped).toBe(0);
+    expect(stats.blocksStripped).toBe(0);
+    expect(stats.messagesModified).toBe(0);
+  });
 });

package/src/agent/history-repair/history-repair.ts

@@ -15,6 +15,7 @@
  * recover — so detection and repair of ordering drift live together as one unit.
  */
 
+import { analyzeServerToolPairing } from "../../providers/server-tool-pairing.js";
 import type {
   ContentBlock,
   Message,
@@ -69,6 +70,10 @@ export function repairHistory(messages: Message[]): RepairResult {
   let pendingToolUseIds = new Set<string>();
   // tool_result blocks stripped from assistant messages, keyed by tool_use_id
   let recoveredResults = new Map<string, ToolResultContent>();
+  // Server-tool pairs can legitimately span messages (deferred execution) or
+  // sit unanswered at the tail (the provider runs the search on the next
+  // request), so orphanhood is judged against the whole list, not per message.
+  const serverToolPairing = analyzeServerToolPairing(messages);
 
   for (const [msgIndex, msg] of messages.entries()) {
     if (msg.role === "assistant") {
@@ -100,36 +105,32 @@ export function repairHistory(messages: Message[]): RepairResult {
         }
       }
 
-      // Pair server-side tool blocks within the same assistant message.
-      // Server tools (e.g. web_search) emit server_tool_use + matching
-      // web_search_tool_result. Either side can go missing — the synthetic
-      // result is inserted IMMEDIATELY AFTER the orphan server_tool_use (not
+      // Repair orphaned server-side tool blocks. Server tools (e.g.
+      // web_search) emit server_tool_use + matching web_search_tool_result;
+      // orphanhood comes from `serverToolPairing`, which resolves pairs
+      // across messages and exempts the deferred tail. The synthetic result
+      // is inserted IMMEDIATELY AFTER the orphan server_tool_use (not
       // appended to the end) so ensureToolPairing's split at tool_use
       // boundaries cannot separate the pair. An orphan
-      // web_search_tool_result (no preceding server_tool_use) is downgraded
-      // to text — Anthropic rejects the request otherwise.
-      const serverToolIds = new Set(
-        cleanedContent
-          .filter(
-            (b): b is ServerToolUseContent => b.type === "server_tool_use",
-          )
-          .map((b) => b.id),
-      );
-      const matchedServerIds = new Set(
-        cleanedContent
-          .filter((b) => b.type === "web_search_tool_result")
-          .map((b) => (b as { tool_use_id: string }).tool_use_id),
-      );
+      // web_search_tool_result with no use anywhere is downgraded to text.
+      // Anthropic rejects the request otherwise.
       const orphanedServerIds = new Set<string>();
-      for (const id of serverToolIds) {
-        if (!matchedServerIds.has(id)) {
-          orphanedServerIds.add(id);
-        }
-      }
       const orphanedWebSearchResultIds = new Set<string>();
-      for (const id of matchedServerIds) {
-        if (!serverToolIds.has(id)) {
-          orphanedWebSearchResultIds.add(id);
+      for (const b of cleanedContent) {
+        if (b.type === "server_tool_use") {
+          const id = (b as ServerToolUseContent).id;
+          if (
+            !serverToolPairing.resolvedPairIds.has(id) &&
+            !serverToolPairing.deferredUseIds.has(id)
+          ) {
+            orphanedServerIds.add(id);
+          }
+        }
+        if (b.type === "web_search_tool_result") {
+          const id = (b as { tool_use_id: string }).tool_use_id;
+          if (!serverToolPairing.resolvedPairIds.has(id)) {
+            orphanedWebSearchResultIds.add(id);
+          }
         }
       }
 

package/src/daemon/web-search-history.ts

@@ -20,18 +20,27 @@ export interface StripResult {
 /**
  * Replaces every `web_search_tool_result` block in the message list with a
  * plain `text` summary of its results, and drops the paired `server_tool_use`
- * that produced it.
+ * that produced it, wherever that use lives. The pair usually shares one
+ * assistant message, but a deferred execution (the API runs the search on the
+ * request after a mixed server/client parallel tool group) places the result
+ * at the head of the following assistant message, so pairing is resolved
+ * across the whole list. Dropping both sides together keeps the history free
+ * of unpaired server-tool blocks, which the provider layer would otherwise
+ * repair with a synthetic error result.
+ *
+ * A `server_tool_use` with no result anywhere in the list is left untouched:
+ * either the search is still pending (deferred tail, executed by the provider
+ * on this request) or it is a genuine orphan the provider layer repairs.
  *
  * Anthropic's `encrypted_content` tokens attached to each `web_search_result`
  * are opaque server tokens with bounded validity (they expire and/or are
  * route-scoped). Replaying a stale token produces
  * `messages.N.content.M: Invalid encrypted_content in search_result block`.
  * For historical turns the model does not need the opaque token to re-read
- * the body — a title+url summary is sufficient to preserve context.
+ * the body: a title+url summary is sufficient to preserve context.
  *
- * Intended to run on `runMessages` immediately before the agent loop starts a
- * new turn, at which point every `web_search_tool_result` in the list is by
- * definition from a prior turn.
+ * Runs on the outbound message list before each model call; every executed
+ * search in the list is summarized regardless of which turn produced it.
  */
 export function stripHistoricalWebSearchResults(
   messages: Message[],
@@ -42,42 +51,45 @@ export function stripHistoricalWebSearchResults(
     messagesModified: 0,
   };
 
-  const next: Message[] = messages.map((msg) => {
-    const droppedServerToolUseIds = new Set<string>();
-    const transformed: ContentBlock[] = [];
-
+  const strippedToolUseIds = new Set<string>();
+  for (const msg of messages) {
     for (const block of msg.content) {
-      if (block.type !== "web_search_tool_result") {
-        continue;
+      if (block.type === "web_search_tool_result") {
+        strippedToolUseIds.add(
+          (block as WebSearchToolResultContent).tool_use_id,
+        );
       }
-      const wsr = block as WebSearchToolResultContent;
-      const query = findQueryForToolUseId(msg.content, wsr.tool_use_id);
-      transformed.push(formatAsText(wsr, query));
-      droppedServerToolUseIds.add(wsr.tool_use_id);
-      stats.blocksStripped++;
-    }
-
-    if (droppedServerToolUseIds.size === 0) {
-      return msg;
     }
+  }
 
+  const next: Message[] = messages.map((msg) => {
+    let modified = false;
     const rewritten: ContentBlock[] = [];
-    let wsrIndex = 0;
+
     for (const block of msg.content) {
       if (block.type === "server_tool_use") {
         const stu = block as ServerToolUseContent;
-        if (droppedServerToolUseIds.has(stu.id)) {
+        if (strippedToolUseIds.has(stu.id)) {
           stats.serverToolUsesDropped++;
+          modified = true;
           continue;
         }
         rewritten.push(block);
       } else if (block.type === "web_search_tool_result") {
-        rewritten.push(transformed[wsrIndex++]);
+        const wsr = block as WebSearchToolResultContent;
+        rewritten.push(
+          formatAsText(wsr, findQueryForToolUseId(messages, wsr.tool_use_id)),
+        );
+        stats.blocksStripped++;
+        modified = true;
       } else {
         rewritten.push(block);
       }
     }
 
+    if (!modified) {
+      return msg;
+    }
     stats.messagesModified++;
     return { ...msg, content: rewritten };
   });
@@ -86,19 +98,21 @@ export function stripHistoricalWebSearchResults(
 }
 
 function findQueryForToolUseId(
-  blocks: ContentBlock[],
+  messages: Message[],
   toolUseId: string,
 ): string | null {
-  for (const b of blocks) {
-    if (b.type !== "server_tool_use") {
-      continue;
-    }
-    const stu = b as ServerToolUseContent;
-    if (stu.id !== toolUseId) {
-      continue;
+  for (const msg of messages) {
+    for (const b of msg.content) {
+      if (b.type !== "server_tool_use") {
+        continue;
+      }
+      const stu = b as ServerToolUseContent;
+      if (stu.id !== toolUseId) {
+        continue;
+      }
+      const q = stu.input?.query;
+      return typeof q === "string" ? q : null;
     }
-    const q = stu.input?.query;
-    return typeof q === "string" ? q : null;
   }
   return null;
 }

package/src/providers/anthropic/client.ts

@@ -18,6 +18,12 @@ import {
   PLACEHOLDER_EMPTY_TURN,
 } from "../placeholder-sentinels.js";
 import { recordProviderRequestDiagnostics } from "../request-diagnostics.js";
+import {
+  analyzeServerToolPairing,
+  isServerToolUseBlock,
+  isWebSearchToolResultBlock,
+  type ServerToolPairing,
+} from "../server-tool-pairing.js";
 import { createStreamTimeout } from "../stream-timeout.js";
 import type {
   ContentBlock,
@@ -489,73 +495,54 @@ function normalizeFollowingUserContent(
   };
 }
 
-/** Type-guard for server_tool_use blocks. */
-function isServerToolUseBlock(
-  block: unknown,
-): block is { type: "server_tool_use"; id: string; name: string } {
-  return (
-    typeof block === "object" &&
-    block != null &&
-    (block as { type: string }).type === "server_tool_use"
-  );
-}
-
-/** Type-guard for web_search_tool_result blocks. */
-function isWebSearchToolResultBlock(block: unknown): block is {
-  type: "web_search_tool_result";
-  tool_use_id: string;
-  content: unknown;
-} {
-  return (
-    typeof block === "object" &&
-    block != null &&
-    (block as { type: string }).type === "web_search_tool_result"
-  );
-}
-
 /**
- * Repair orphaned server-side tool blocks within assistant messages. Server-
- * side tools (e.g. web_search) are self-paired: the assistant message should
- * contain both server_tool_use and its matching web_search_tool_result. Either
- * side can go missing — a partial stream may drop the result, or a downstream
- * step (history reload, message split, compaction) may drop the use block.
- * Both cases trigger an Anthropic 400 on the next request, so this function
- * handles both directions:
+ * Repair orphaned server-side tool blocks within assistant messages, using the
+ * cross-message pairing from {@link analyzeServerToolPairing}. A pair can go
+ * missing on either side: a partial stream may drop the result, or a
+ * downstream step (history reload, message split, compaction) may drop the use
+ * block. Both cases trigger an Anthropic 400 on the next request, so this
+ * function handles both directions:
  *
- *   - server_tool_use without paired result: inject a synthetic error result.
- *   - web_search_tool_result without paired server_tool_use: downgrade to a
+ *   - server_tool_use without a paired result: inject a synthetic error
+ *     result.
+ *   - web_search_tool_result without a paired server_tool_use: downgrade to a
  *     text block describing what was found so the model retains context.
+ *
+ * Deferred use blocks (see {@link ServerToolPairing.deferredUseIds}) are not
+ * orphans: they are left intact so the provider executes the search on this
+ * request instead of seeing a synthetic failure.
  */
 function repairOrphanedServerToolBlocks(
   messages: Anthropic.MessageParam[],
+  pairing: ServerToolPairing,
 ): Anthropic.MessageParam[] {
+  if (pairing.deferredUseIds.size > 0) {
+    log.info(
+      { deferredIds: Array.from(pairing.deferredUseIds) },
+      "Preserving deferred server_tool_use blocks for provider-side execution",
+    );
+  }
   return messages.map((msg) => {
     if (msg.role !== "assistant") {
       return msg;
     }
     const content = Array.isArray(msg.content) ? msg.content : [];
 
-    const serverToolUseIds = new Set<string>();
-    const webSearchResultIds = new Set<string>();
-    for (const block of content) {
-      if (isServerToolUseBlock(block)) {
-        serverToolUseIds.add(block.id);
-      }
-      if (isWebSearchToolResultBlock(block)) {
-        webSearchResultIds.add(block.tool_use_id);
-      }
-    }
-
     const orphanServerToolUseIds = new Set<string>();
-    for (const id of serverToolUseIds) {
-      if (!webSearchResultIds.has(id)) {
-        orphanServerToolUseIds.add(id);
-      }
-    }
     const orphanWebSearchResultIds = new Set<string>();
-    for (const id of webSearchResultIds) {
-      if (!serverToolUseIds.has(id)) {
-        orphanWebSearchResultIds.add(id);
+    for (const block of content) {
+      if (
+        isServerToolUseBlock(block) &&
+        !pairing.resolvedPairIds.has(block.id) &&
+        !pairing.deferredUseIds.has(block.id)
+      ) {
+        orphanServerToolUseIds.add(block.id);
+      }
+      if (
+        isWebSearchToolResultBlock(block) &&
+        !pairing.resolvedPairIds.has(block.tool_use_id)
+      ) {
+        orphanWebSearchResultIds.add(block.tool_use_id);
       }
     }
 
@@ -709,9 +696,18 @@ function findActiveToolUseContinuationStart(
 
 function ensureToolPairing(
   messages: Anthropic.MessageParam[],
+  pairing: ServerToolPairing,
 ): Anthropic.MessageParam[] {
   const result: Anthropic.MessageParam[] = [];
 
+  // Messages carrying a deferred or cross-message-paired server tool block
+  // must go out verbatim: the provider pairs and executes these blocks across
+  // messages itself, and reordering or splitting them breaks that pairing.
+  const verbatimIds = new Set([
+    ...pairing.deferredUseIds,
+    ...pairing.crossMessageIds,
+  ]);
+
   let i = 0;
   while (i < messages.length) {
     const msg = messages[i];
@@ -724,8 +720,23 @@ function ensureToolPairing(
 
     const content = Array.isArray(msg.content) ? msg.content : [];
 
+    const hasVerbatimServerBlock =
+      verbatimIds.size > 0 &&
+      content.some(
+        (block) =>
+          (isServerToolUseBlock(block) && verbatimIds.has(block.id)) ||
+          (isWebSearchToolResultBlock(block) &&
+            verbatimIds.has(block.tool_use_id)),
+      );
+
     const { pairedContent, carryoverContent, toolUseIds } =
-      splitAssistantForToolPairing(content);
+      hasVerbatimServerBlock
+        ? {
+            pairedContent: content,
+            carryoverContent: [] as Anthropic.ContentBlockParam[],
+            toolUseIds: getOrderedToolUseIds(content),
+          }
+        : splitAssistantForToolPairing(content);
 
     if (toolUseIds.length === 0) {
       result.push(msg);
@@ -2016,7 +2027,11 @@ export class AnthropicProvider implements Provider {
       formatted[i] = { ...msg, content: stripped };
     }
 
-    return ensureToolPairing(repairOrphanedServerToolBlocks(formatted));
+    const serverToolPairing = analyzeServerToolPairing(formatted);
+    return ensureToolPairing(
+      repairOrphanedServerToolBlocks(formatted, serverToolPairing),
+      serverToolPairing,
+    );
   }
 
   /**

package/src/providers/server-tool-pairing.ts

@@ -0,0 +1,134 @@
+// Single source of truth for pairing server-side tool blocks (e.g. native
+// web_search) across a message list. Pure leaf module: consumed by the
+// provider formatter, load-time history repair, and any other pass that must
+// distinguish a genuine orphan from a pair the provider manages itself.
+
+/**
+ * Minimal structural message shape shared by daemon `Message[]` and
+ * `Anthropic.MessageParam[]`.
+ */
+export interface ServerToolPairingMessage {
+  role: string;
+  content: string | ReadonlyArray<unknown>;
+}
+
+/** Type-guard for server_tool_use blocks. */
+export function isServerToolUseBlock(
+  block: unknown,
+): block is { type: "server_tool_use"; id: string; name: string } {
+  return (
+    typeof block === "object" &&
+    block != null &&
+    (block as { type: string }).type === "server_tool_use"
+  );
+}
+
+/** Type-guard for web_search_tool_result blocks. */
+export function isWebSearchToolResultBlock(block: unknown): block is {
+  type: "web_search_tool_result";
+  tool_use_id: string;
+  content: unknown;
+} {
+  return (
+    typeof block === "object" &&
+    block != null &&
+    (block as { type: string }).type === "web_search_tool_result"
+  );
+}
+
+function isToolResultShapedBlock(block: unknown): boolean {
+  return (
+    typeof block === "object" &&
+    block != null &&
+    (block as { type?: string }).type === "tool_result"
+  );
+}
+
+function contentBlocks(msg: ServerToolPairingMessage): ReadonlyArray<unknown> {
+  return Array.isArray(msg.content) ? msg.content : [];
+}
+
+/**
+ * Pairing analysis for server-side tool blocks across the whole message list.
+ *
+ * Server-side tools are provider-executed, and the pair can legitimately span
+ * messages: when the model requests a server tool and a client tool in the
+ * same parallel tool-call group, the API defers the search (stop_reason
+ * `tool_use`, no result emitted) and executes it on the next request, placing
+ * the web_search_tool_result at the head of the next assistant message. Both
+ * the deferred tail and the resulting split pair must be sent back verbatim
+ * for the provider to pair and execute them.
+ */
+export interface ServerToolPairing {
+  /**
+   * Ids with a complete use/result pair: the server_tool_use appears in the
+   * same message as its web_search_tool_result or in an earlier one.
+   */
+  resolvedPairIds: Set<string>;
+  /**
+   * Unanswered use ids in the final assistant message of an active tool-loop
+   * continuation (only user messages after it, carrying tool_result blocks or
+   * nothing at all). The provider executes these on this request.
+   */
+  deferredUseIds: Set<string>;
+  /** Ids whose use/result pair spans two messages. */
+  crossMessageIds: Set<string>;
+}
+
+export function analyzeServerToolPairing(
+  messages: ReadonlyArray<ServerToolPairingMessage>,
+): ServerToolPairing {
+  const useIndexById = new Map<string, number>();
+  const resultIndexById = new Map<string, number>();
+  let lastAssistantIndex = -1;
+
+  messages.forEach((msg, index) => {
+    if (msg.role !== "assistant") {
+      // Server-tool blocks legitimately live only in assistant messages; a
+      // stray result in a user message is a repair concern, not a pair.
+      return;
+    }
+    lastAssistantIndex = index;
+    for (const block of contentBlocks(msg)) {
+      if (isServerToolUseBlock(block) && !useIndexById.has(block.id)) {
+        useIndexById.set(block.id, index);
+      }
+      if (
+        isWebSearchToolResultBlock(block) &&
+        !resultIndexById.has(block.tool_use_id)
+      ) {
+        resultIndexById.set(block.tool_use_id, index);
+      }
+    }
+  });
+
+  const resolvedPairIds = new Set<string>();
+  const crossMessageIds = new Set<string>();
+  useIndexById.forEach((useIndex, id) => {
+    const resultIndex = resultIndexById.get(id);
+    if (resultIndex !== undefined && resultIndex >= useIndex) {
+      resolvedPairIds.add(id);
+      if (resultIndex > useIndex) {
+        crossMessageIds.add(id);
+      }
+    }
+  });
+
+  const deferredUseIds = new Set<string>();
+  if (lastAssistantIndex >= 0) {
+    const trailing = messages.slice(lastAssistantIndex + 1);
+    const trailingAllUser = trailing.every((m) => m.role === "user");
+    const trailingHasToolResult = trailing.some((m) =>
+      contentBlocks(m).some(isToolResultShapedBlock),
+    );
+    if (trailingAllUser && (trailing.length === 0 || trailingHasToolResult)) {
+      for (const block of contentBlocks(messages[lastAssistantIndex])) {
+        if (isServerToolUseBlock(block) && !resolvedPairIds.has(block.id)) {
+          deferredUseIds.add(block.id);
+        }
+      }
+    }
+  }
+
+  return { resolvedPairIds, deferredUseIds, crossMessageIds };
+}