fix(claude): replay Anthropic server-tool exchanges on the translated lane (carry #7205)

docs-site/src/content/docs/guides/claude-code.md

@@ -962,7 +962,7 @@ The proxy translates every Anthropic Messages API request into the Codex Respons
 | User `tool_result` | `function_call_output` (`is_error` → `[tool error]` prefix) |
 | `tool_reference` in a tool result | Text `Tool loaded: <tool_name>` in the paired result; preserves loaded-tool names without adding declarations or enabling translated server-side deferral |
 | `thinking` / `redacted_thinking` replay | `reasoning` items with bounded `ocxr1` envelopes for signatures and redacted payloads |
-| Function tools | `{type: "function"}` (`web_search*` → `{type: "web_search"}`). On a route to `api.anthropic.com`, the typed `web_search_*` and `web_fetch_*` declarations are also sent to Anthropic as declared and run server-side, unless the web-search sidecar supplies `web_search` itself. Each search or fetch comes back to the client as its `server_tool_use` block and its `web_search_tool_result` or `web_fetch_tool_result` |
+| Function tools | `{type: "function"}` (`web_search*` → `{type: "web_search"}`). On a route to `api.anthropic.com`, the typed `web_search_*` and `web_fetch_*` declarations are also sent to Anthropic as declared and run server-side, unless the web-search sidecar supplies `web_search` itself. A search or fetch with a matching call and complete input comes back to the client as its `server_tool_use` block and its `web_search_tool_result` or `web_fetch_tool_result`, verbatim. Orphan results are dropped without synthesizing a call, while the surrounding text is preserved. When the client sends a complete pair back in its history, the next `api.anthropic.com` request carries it in place only if the following block uniquely identifies its original turn. Repeated anchors, unmatched or duplicate call/result ids, malformed call input, or a result appearing before its call drop the exchange. Call input must be an object with a nonempty search query or fetch URL string; other destinations never see the exchange |
 | `tool_choice` | `auto`→`auto`, `none`→`none`, `any`→`required`, named function→`{type:"function",name}`, hosted WebSearch/web_search→`{type:"web_search"}` |
 | `max_tokens` | `max_output_tokens` |
 | `stop_sequences` | `stop` |

src/adapters/anthropic.ts

@@ -522,13 +522,13 @@ function streamedToolArgumentsParse(assembled: string): boolean {
   }
 }
 
-/** A string field of a server tool's streamed input (web_search `query`, web_fetch `url`); "" when it did not parse. */
-function serverToolInputField(json: string, key: "query" | "url"): string {
+/** A server tool's complete streamed input; undefined when it cannot be recovered. */
+function serverToolInput(json: string): Record<string, unknown> | undefined {
   try {
-    const value = (JSON.parse(json) as Record<string, unknown> | null)?.[key];
-    return typeof value === "string" ? value : "";
+    const input = JSON.parse(json) as unknown;
+    return isAnthropicRecord(input) ? input : undefined;
   } catch {
-    return "";
+    return undefined;
   }
 }
 
@@ -735,7 +735,16 @@ function orphanToolResultContent(msg: OcxToolResultMessage): string | unknown[]
 function messagesToAnthropicFormat(
   parsed: OcxParsedRequest,
   toolNames: { toWire: (name: string) => string },
+  serverReplay?: ReadonlyMap<string, readonly Record<string, unknown>[]>,
 ): { system: string | undefined; messages: unknown[] } {
+  // The client's server-tool exchanges go back ahead of the block they preceded. Their anchors are
+  // unique in the caller's history (replayedAnthropicServerBlocks drops repeated ones); each is used once.
+  const pendingReplay = new Map(serverReplay);
+  const replayed = (anchor: string) => {
+    const blocks = pendingReplay.get(anchor) ?? [];
+    pendingReplay.delete(anchor);
+    return blocks;
+  };
   // One allocator for the whole request: a tool_result must resolve to the SAME wire id its
   // call got, and two distinct raw ids must never collapse into one. Conforming ids are claimed
   // first so a rewritten id can never squat on an id another call legitimately owns.
@@ -789,9 +798,13 @@ function messagesToAnthropicFormat(
         for (const part of aMsg.content) {
           if (part.type === "text") {
             const text = (part as OcxTextContent).text;
+            for (const b of replayed(`text:${text}`)) appendPreface(b);
             if (text) appendPreface({ type: "text", text });
           } else if (part.type === "thinking") {
             const t = part as OcxThinkingContent;
+            // Server blocks that preceded this reasoning keep their place, even when it is dropped below.
+            for (const data of t.redacted ?? []) for (const b of replayed(`redacted:${data}`)) appendPreface(b);
+            for (const b of replayed(`thinking:${t.signature}`)) appendPreface(b);
             // History minted under another serving identity (or already rejected as opaque) is not
             // this destination's to verify: drop its opaque blocks, as the Responses passthrough does.
             if (parsed._stripReasoningEncryptedContent === true) continue;
@@ -806,6 +819,7 @@ function messagesToAnthropicFormat(
             }
           } else if (part.type === "toolCall") {
             const tc = part as OcxToolCall;
+            for (const b of replayed(`call:${tc.id}`)) appendPreface(b);
             const flatName = namespacedToolName(tc.namespace, tc.name);
             // Normalized here, and identically for the matching tool_result above, so a history
             // replayed from another provider path keeps its call/result pairing (#1767).
@@ -998,7 +1012,9 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
         throw new Error("anthropic provider requires a non-empty apiKey (authMode: key)");
       }
 
-      const { system, messages } = messagesToAnthropicFormat(parsed, toolNames);
+      // Only api.anthropic.com runs Anthropic's server tools, so only it gets their history back.
+      const { system, messages } = messagesToAnthropicFormat(parsed, toolNames,
+        usesNativeAnthropicEndpoint(provider) ? parsed._anthropicServerReplay : undefined);
       // Before image normalization, so the framing block is present for every downstream pass.
       if (isAgentRouterEndpoint(provider.baseUrl)) applyAgentRouterLanguageFraming(messages);
       // Primary image layer: resize/re-encode to fit Anthropic limits without dropping
@@ -1336,36 +1352,26 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
                   // no result in this response and must not surface as a completed search.
                   serverSearch = { id: block.id, json: "", streaming: true };
                 }
-                if (block.type === "web_search_tool_result" && typeof block.tool_use_id === "string") {
+                if ((block.type === "web_search_tool_result" || block.type === "web_fetch_tool_result") && typeof block.tool_use_id === "string") {
+                  // The begin/end pair the sidecar emits, plus both blocks verbatim so the Claude client holds a
+                  // replayable copy. Without this response's matching call and complete input, drop the
+                  // exchange instead of inventing a call that could poison the client's next request.
+                  const fetch = block.type === "web_fetch_tool_result";
+                  const input = serverSearch?.id === block.tool_use_id ? serverToolInput(serverSearch.json) : undefined;
+                  if (!input) break;
                   const hits = Array.isArray(block.content) ? block.content as Array<{ url?: unknown; title?: unknown }> : undefined;
-                  // The begin/end pair the sidecar emits. A result whose call came in an earlier response has no query here.
-                  const query = serverSearch?.id === block.tool_use_id ? serverToolInputField(serverSearch.json, "query") : "";
                   yield { type: "web_search_call_begin", id: block.tool_use_id };
                   yield {
                     type: "web_search_call_end",
                     id: block.tool_use_id,
-                    queries: query ? [query] : [],
-                    // A failed search carries one error object instead of the hit list.
-                    status: hits ? "completed" : "failed",
+                    queries: typeof input.query === "string" && input.query.length > 0 ? [input.query] : [],
+                    // A failed call carries one error object instead of the hit list / fetched page.
+                    status: (fetch ? (block.content as { type?: unknown } | undefined)?.type === "web_fetch_result" : hits) ? "completed" : "failed",
                     sources: (hits ?? []).flatMap(h => typeof h.url === "string"
                       ? [{ url: h.url, ...(typeof h.title === "string" ? { title: h.title } : {}) }] : []),
-                  };
-                  serverSearch = undefined;
-                }
-                if (block.type === "web_fetch_tool_result" && typeof block.tool_use_id === "string") {
-                  // Relayed as the same cell, opened at the result for the same reason; the result is
-                  // carried verbatim (a web_fetch_result document or a web_fetch_tool_error).
-                  const result = block.content ?? { type: "web_fetch_tool_error", error_code: "unavailable" };
-                  const url = (result as { url?: unknown }).url;
-                  yield { type: "web_search_call_begin", id: block.tool_use_id };
-                  yield {
-                    type: "web_search_call_end",
-                    id: block.tool_use_id,
-                    queries: [],
-                    status: (result as { type?: unknown }).type === "web_fetch_result" ? "completed" : "failed",
-                    fetch: {
-                      url: typeof url === "string" ? url : serverSearch?.id === block.tool_use_id ? serverToolInputField(serverSearch.json, "url") : "",
-                      result,
+                    anthropic: {
+                      use: { type: "server_tool_use", id: block.tool_use_id, name: fetch ? "web_fetch" : "web_search", input },
+                      result: block as Record<string, unknown>,
                     },
                   };
                   serverSearch = undefined;
@@ -1415,7 +1421,7 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
                   yield { type: "tool_call_delta", arguments: delta.partial_json };
                 } else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string" && serverSearch?.streaming
                     && serverSearch.json.length < 4096) {
-                  // Capped: an input past 4 KiB loses its label (query / url), never the call.
+                  // Capped: input that cannot be recovered drops its exchange instead of inventing a call.
                   serverSearch.json += delta.partial_json.slice(0, 4096 - serverSearch.json.length);
                 }
                 break;

src/bridge/internal.ts

@@ -1,5 +1,6 @@
 import type {
   AdapterEvent,
+  AnthropicServerBlocks,
   OcxMessagePhase,
   OcxProviderContinuationState,
   OcxProviderOpaqueToolCallMetadata,
@@ -186,9 +187,12 @@ export function adapterFailureFromEvent(event: Extract<AdapterEvent, { type: "er
  * This fixes items created from here on. History recorded before it is repaired at the
  * replay boundary by `backfillWebSearchQueries()` in the Responses adapter.
  */
-export function webSearchAction(queries: string[], fetch?: { url: string }): Record<string, unknown> {
+export function webSearchAction(queries: string[], anthropic?: AnthropicServerBlocks): Record<string, unknown> {
   // Anthropic's server-side web_fetch opens one page instead of searching.
-  if (fetch) return { type: "open_page", url: fetch.url };
+  if (anthropic?.use.name === "web_fetch") {
+    const url = (anthropic.result.content as { url?: unknown } | undefined)?.url ?? (anthropic.use.input as { url?: unknown }).url;
+    return { type: "open_page", url: typeof url === "string" ? url : "" };
+  }
   const first = queries[0] ?? "";
   return { type: "search", query: first, queries: queries.length > 0 ? queries : [first] };
 }

src/bridge/response-json.ts

@@ -547,9 +547,9 @@ function buildResponseJSONWithBudget(
         const safeSources = safeWebSearchSources(e.sources);
         pushOutput({
           type: "web_search_call", id: `ws_${uuid()}`, status: e.status ?? "completed",
-          action: webSearchAction(e.queries, e.fetch),
+          action: webSearchAction(e.queries, e.anthropic),
           ...(safeSources.length > 0 ? { sources: safeSources } : {}),
-          ...(e.fetch ? { fetch_result: e.fetch.result } : {}),
+          ...(e.anthropic ? { anthropic_blocks: e.anthropic } : {}),
         });
         if (safeSources.length > 0) {
           for (const source of safeSources) {

src/bridge/sse.ts

@@ -1,6 +1,7 @@
 import { anthropicProgressItems } from "../responses/anthropic-progress";
 import type {
   AdapterEvent,
+  AnthropicServerBlocks,
   OcxMessagePhase,
   OcxProviderContinuationState,
   OcxProviderOpaqueToolCallMetadata,
@@ -685,15 +686,15 @@ export function bridgeToResponsesSSE(
       // leaves a "Searching the web" spinner spinning forever.
       // `sources` rides on the done item (additive field; codex-rs serde ignores unknown fields) so
       // downstream translators (claude outbound) can fill web_search_tool_result content.
-      // `fetch` (Anthropic's server-side web_fetch) makes the cell a page open and rides its result
-      // verbatim as `fetch_result`, for the same claude outbound translator.
-      const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[], sources?: { url: string; title?: string }[], fetch?: { url: string; result: unknown }) => {
+      // `anthropic` (Anthropic's server-side call) rides verbatim as `anthropic_blocks`, for the same
+      // claude outbound translator; a web_fetch makes the cell a page open.
+      const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[], sources?: { url: string; title?: string }[], anthropic?: AnthropicServerBlocks) => {
         if (!currentWebSearch) return;
         const item = {
           type: "web_search_call", id: currentWebSearch.itemId, status,
-          action: webSearchAction(queries, fetch),
+          action: webSearchAction(queries, anthropic),
           ...(sources && sources.length > 0 ? { sources } : {}),
-          ...(fetch ? { fetch_result: fetch.result } : {}),
+          ...(anthropic ? { anthropic_blocks: anthropic } : {}),
         };
         emit("response.output_item.done", { output_index: currentWebSearch.outputIndex, item });
         retainFinishedItem(item as OutputItem);
@@ -1231,7 +1232,7 @@ export function bridgeToResponsesSSE(
                 currentWebSearch = { itemId: wsItemId2, eventId: event.id, outputIndex };
               }
               const safeSources = safeWebSearchSources(event.sources);
-              closeCurrentWebSearch(event.status ?? "completed", event.queries, safeSources, event.fetch);
+              closeCurrentWebSearch(event.status ?? "completed", event.queries, safeSources, event.anthropic);
               // Queue this search's sources for the next assistant message (dedup by URL).
               if (safeSources.length > 0) {
                 for (const source of safeSources) {

src/claude/inbound-content-options.ts

@@ -87,6 +87,72 @@ export function declaredAnthropicServerTools(raw: unknown): Rec[] | undefined {
   return tools.length > 0 ? tools : undefined;
 }
 
+/** Validate original call/result order without inventing inputs or pairing a later call backwards. */
+function replayableServerRun(run: readonly Rec[]): boolean {
+  const pending = new Map<string, Rec>();
+  const completed = new Set<string>();
+  for (const block of run) {
+    if (block.type === "server_tool_use") {
+      const { id, name, input } = block;
+      if (typeof id !== "string" || !id.startsWith("srvtoolu_") || pending.has(id) || completed.has(id)
+        || (name !== "web_search" && name !== "web_fetch") || !isRec(input)) return false;
+      const prototype = Object.getPrototypeOf(input);
+      const required = input[name === "web_search" ? "query" : "url"];
+      if ((prototype !== Object.prototype && prototype !== null)
+        || typeof required !== "string" || required.trim().length === 0) return false;
+      pending.set(id, block);
+    } else {
+      const id = block.tool_use_id;
+      if (typeof id !== "string") return false;
+      const call = pending.get(id);
+      if (!call || block.type !== `${call.name}_tool_result`
+        || (Array.isArray(block.content) && !block.content.every(h => isRec(h) && typeof h.encrypted_content === "string"))) return false;
+      pending.delete(id);
+      completed.add(id);
+    }
+  }
+  return completed.size > 0 && pending.size === 0;
+}
+
+/**
+ * Completed Anthropic server-tool exchanges (`server_tool_use` + `web_search_tool_result` /
+ * `web_fetch_tool_result`) in the caller's assistant history. The Responses body drops them, so
+ * an Anthropic destination re-inserts them out of body, keyed by the block that follows each run
+ * in its message: `call:<tool_use id>`, `text:<text>`, `thinking:<signature>` or
+ * `redacted:<data>`, all of which survive translation. An anchor that occurs more than once in the
+ * assistant history (string content included) cannot name one owner, so its run stays dropped,
+ * as it was before replay existed. A run with none, an unpaired call, a
+ * non-Anthropic id, or a search hit without `encrypted_content` is not replayable and stays dropped.
+ */
+export function replayedAnthropicServerBlocks(raw: unknown): Map<string, Rec[]> | undefined {
+  if (!isRec(raw) || !Array.isArray(raw.messages)) return undefined;
+  const out = new Map<string, Rec[]>();
+  const seen = new Map<string, number>();
+  const count = (anchor: string) => seen.set(anchor, (seen.get(anchor) ?? 0) + 1);
+  for (const message of raw.messages) {
+    if (!isRec(message) || message.role !== "assistant") continue;
+    if (typeof message.content === "string") count(`text:${message.content}`);
+    if (!Array.isArray(message.content)) continue;
+    let run: Rec[] = [];
+    for (const block of message.content.filter(isRec)) {
+      if (block.type === "server_tool_use" || block.type === "web_search_tool_result" || block.type === "web_fetch_tool_result") {
+        // The caller's breakpoints are dropped on this lane, as for the declared tools above.
+        run.push({ ...block, cache_control: undefined });
+        continue;
+      }
+      const anchor = block.type === "tool_use" ? `call:${String(block.id)}`
+        : block.type === "text" ? `text:${String(block.text)}`
+        : block.type === "thinking" ? `thinking:${String(block.signature)}`
+        : block.type === "redacted_thinking" ? `redacted:${String(block.data)}` : undefined;
+      if (anchor) count(anchor);
+      if (anchor && replayableServerRun(run)) out.set(anchor, run);
+      run = [];
+    }
+  }
+  for (const anchor of out.keys()) if ((seen.get(anchor) ?? 0) > 1) out.delete(anchor);
+  return out.size > 0 ? out : undefined;
+}
+
 export function toolChoiceToResponses(choice: unknown, body: Rec): void {
   if (!isRec(choice)) return;
   if (choice.disable_parallel_tool_use === true) body.parallel_tool_calls = false;