fix(ai-anthropic): preserve web_search/web_fetch results across turns (#839)

.changeset/anthropic-server-tool-roundtrip.md

@@ -0,0 +1,18 @@
+---
+'@tanstack/ai-anthropic': patch
+'@tanstack/ai': patch
+---
+
+Preserve Anthropic server-tool results (`web_search` / `web_fetch`) across turns.
+
+Previously the Anthropic adapter dropped `server_tool_use` and
+`web_search_tool_result` / `web_fetch_tool_result` blocks while streaming, so the
+evidence never round-tripped — a follow-up turn could no longer see the prior
+web-search sources (issue #839). These now stream as a **provider-executed**
+tool call carrying the raw result, which the agent loop skips (never executed
+client-side) and the adapter replays verbatim into the next request. Adds the
+`ProviderExecutedToolMetadata` convention plus `isProviderExecutedToolCall` /
+`getProviderExecutedMetadata` helpers to `@tanstack/ai`.
+
+(No e2e: aimock cannot synthesize `server_tool_use` blocks; covered by unit
+tests and verified live against the Anthropic API.)

docs/config.json

@@ -77,7 +77,8 @@
         {
           "label": "Provider Tools",
           "to": "tools/provider-tools",
-          "addedAt": "2026-04-21"
+          "addedAt": "2026-04-21",
+          "updatedAt": "2026-06-26"
         },
         {
           "label": "Provider Skills",

docs/tools/provider-tools.md

@@ -45,6 +45,47 @@ const stream = chat({
 })
 ```
 
+## Multi-turn persistence
+
+Provider tools run on the provider's own infrastructure, so their results
+(e.g. Anthropic `web_search` sources, `web_fetch` page contents) come back
+embedded in the assistant turn rather than as a separate tool message. TanStack
+AI preserves those results on the assistant message, so when you feed the prior
+conversation back into the next `chat()` call the model still sees the earlier
+evidence — no special handling required:
+
+```typescript
+import { chat, StreamProcessor } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { webSearchTool } from '@tanstack/ai-anthropic/tools'
+
+const adapter = anthropicText('claude-opus-4-6')
+const tools = [webSearchTool({ name: 'web_search', type: 'web_search_20250305' })]
+
+const processor = new StreamProcessor()
+for await (const chunk of chat({
+  adapter,
+  tools,
+  messages: [{ role: 'user', content: 'Find two sources on the drone market.' }],
+})) {
+  processor.processChunk(chunk)
+}
+processor.finalizeStream()
+
+// The follow-up turn can still cite the previous search results.
+const followUp = chat({
+  adapter,
+  tools,
+  messages: [
+    ...processor.getMessages(),
+    { role: 'user', content: 'List the exact sources you used.' },
+  ],
+})
+```
+
+The search/fetch call surfaces as a provider-executed `tool-call` part on the
+assistant message; the agent loop never tries to run it client-side.
+
 ## Type-level guard
 
 Every provider-specific tool factory (e.g. `webSearchTool`, `computerUseTool`)

packages/ai-anthropic/src/adapters/text.ts

@@ -28,11 +28,14 @@ import type {
   ContentBlockParam,
   DocumentBlockParam,
   ImageBlockParam,
+  ServerToolUseBlockParam,
   TextBlockParam,
   ThinkingBlockParam,
   ToolUseBlockParam,
   URLImageSource,
   URLPDFSource,
+  WebFetchToolResultBlockParam,
+  WebSearchToolResultBlockParam,
 } from '@anthropic-ai/sdk/resources/messages'
 import type Anthropic_SDK from '@anthropic-ai/sdk'
 import type { AnthropicBeta } from '@anthropic-ai/sdk/resources/beta/beta'
@@ -57,6 +60,83 @@ import type {
 } from '../message-types'
 import type { AnthropicClientConfig } from '../utils'
 
+/**
+ * The block type carried by an Anthropic provider-executed (server) tool's
+ * stored result. Mirrors the `*_tool_result` block emitted by the streaming
+ * API so it can be replayed verbatim into a later turn.
+ */
+type AnthropicServerToolResultBlockType =
+  | 'web_search_tool_result'
+  | 'web_fetch_tool_result'
+
+/**
+ * Anthropic payload stashed on a provider-executed tool call's `metadata`
+ * (under the `anthropic` key, alongside `providerExecuted: true`). Holds enough
+ * to reconstruct the original `server_tool_use` + `*_tool_result` blocks so the
+ * model still sees prior `web_search` / `web_fetch` evidence on the next turn.
+ */
+interface AnthropicServerToolMetadata {
+  serverToolType: ServerToolUseBlockParam['name']
+  resultBlockType: AnthropicServerToolResultBlockType
+  /** Raw result block content, preserved verbatim from the stream. */
+  result: unknown
+}
+
+/**
+ * Narrow an opaque tool-call `metadata` to {@link AnthropicServerToolMetadata}
+ * when it follows the provider-executed convention, else `null`.
+ */
+function readAnthropicServerToolMetadata(
+  metadata: unknown,
+): AnthropicServerToolMetadata | null {
+  if (typeof metadata !== 'object' || metadata === null) return null
+  const outer = metadata as { providerExecuted?: unknown; anthropic?: unknown }
+  if (outer.providerExecuted !== true) return null
+  const inner = outer.anthropic
+  if (typeof inner !== 'object' || inner === null) return null
+  const { serverToolType, resultBlockType, result } = inner as {
+    serverToolType?: unknown
+    resultBlockType?: unknown
+    result?: unknown
+  }
+  if (
+    typeof serverToolType !== 'string' ||
+    (resultBlockType !== 'web_search_tool_result' &&
+      resultBlockType !== 'web_fetch_tool_result')
+  ) {
+    return null
+  }
+  return {
+    // Validated as a string above; widen back to the SDK's tool-name union.
+    serverToolType: serverToolType as ServerToolUseBlockParam['name'],
+    resultBlockType,
+    result,
+  }
+}
+
+/**
+ * Reconstruct the `*_tool_result` block param from stored server-tool metadata.
+ * The `result` content is opaque round-trip data, asserted to the SDK's param
+ * content type at this single boundary.
+ */
+function buildServerToolResultBlock(
+  toolUseId: string,
+  meta: AnthropicServerToolMetadata,
+): WebSearchToolResultBlockParam | WebFetchToolResultBlockParam {
+  if (meta.resultBlockType === 'web_search_tool_result') {
+    return {
+      type: 'web_search_tool_result',
+      tool_use_id: toolUseId,
+      content: meta.result as WebSearchToolResultBlockParam['content'],
+    }
+  }
+  return {
+    type: 'web_fetch_tool_result',
+    tool_use_id: toolUseId,
+    content: meta.result as WebFetchToolResultBlockParam['content'],
+  }
+}
+
 /**
  * Computes the `betas` array for a Messages request. Unions:
  * - `interleaved-thinking-2025-05-14` when interleaved thinking is enabled,
@@ -636,6 +716,25 @@ export class AnthropicTextAdapter<
             parsedInput = toolCall.function.arguments
           }
 
+          // Provider-executed server tools (e.g. web_search) replay as the
+          // original `server_tool_use` + result blocks so the model still sees
+          // the prior evidence. Their result was captured verbatim during
+          // streaming (see processAnthropicStream).
+          const serverMeta = readAnthropicServerToolMetadata(toolCall.metadata)
+          if (serverMeta) {
+            const serverToolUseBlock: ServerToolUseBlockParam = {
+              type: 'server_tool_use',
+              id: toolCall.id,
+              name: serverMeta.serverToolType,
+              input: parsedInput,
+            }
+            contentBlocks.push(serverToolUseBlock)
+            contentBlocks.push(
+              buildServerToolResultBlock(toolCall.id, serverMeta),
+            )
+            continue
+          }
+
           const toolUseBlock: ToolUseBlockParam = {
             type: 'tool_use',
             id: toolCall.id,
@@ -806,6 +905,14 @@ export class AnthropicTextAdapter<
     // input.
     let currentServerTool: { id: string; name: string; input: string } | null =
       null
+    // Completed server tools awaiting their matching result block. Anthropic
+    // emits `server_tool_use` then a separate `*_tool_result` block; we hold
+    // the call here (keyed by id) until the result arrives so we can emit a
+    // single provider-executed tool call carrying the raw result for round-trip.
+    const completedServerTools = new Map<
+      string,
+      { id: string; name: string; input: string }
+    >()
 
     // AG-UI lifecycle tracking
     const runId = options.runId ?? genId()
@@ -881,6 +988,61 @@ export class AnthropicTextAdapter<
                 },
               )
             }
+
+            // Emit the server tool as a single provider-executed tool call,
+            // carrying its raw result so the evidence (e.g. web_search sources)
+            // round-trips into the next turn's request. The agent loop skips
+            // provider-executed calls, so this never triggers client execution.
+            const serverTool = completedServerTools.get(
+              event.content_block.tool_use_id,
+            )
+            if (serverTool) {
+              completedServerTools.delete(serverTool.id)
+
+              let parsedInput: unknown = {}
+              try {
+                const parsed = serverTool.input
+                  ? JSON.parse(serverTool.input)
+                  : {}
+                parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
+              } catch {
+                parsedInput = {}
+              }
+
+              const serverToolMetadata = {
+                providerExecuted: true,
+                anthropic: {
+                  serverToolType: serverTool.name,
+                  resultBlockType: event.content_block.type,
+                  result: content,
+                },
+              }
+
+              currentToolIndex++
+              yield {
+                type: EventType.TOOL_CALL_START,
+                toolCallId: serverTool.id,
+                toolCallName: serverTool.name,
+                toolName: serverTool.name,
+                parentMessageId: messageId,
+                model,
+                timestamp: Date.now(),
+                index: currentToolIndex,
+                metadata: serverToolMetadata,
+              }
+              yield {
+                type: EventType.TOOL_CALL_END,
+                toolCallId: serverTool.id,
+                toolCallName: serverTool.name,
+                toolName: serverTool.name,
+                model,
+                timestamp: Date.now(),
+                input: parsedInput,
+              }
+
+              // Text after the server tool starts a fresh message segment.
+              hasEmittedTextMessageStart = false
+            }
           } else if (event.content_block.type === 'thinking') {
             accumulatedThinking = ''
             accumulatedSignature = ''
@@ -1095,6 +1257,9 @@ export class AnthropicTextAdapter<
                   input: currentServerTool.input,
                 },
               )
+              // Hold the call until its result block arrives so we can emit
+              // both together as one provider-executed tool call.
+              completedServerTools.set(currentServerTool.id, currentServerTool)
             }
             currentServerTool = null
           } else if (