@strav/brain 1.0.0-alpha.16 → 1.0.0-alpha.17

package/src/providers/anthropic_provider.ts

@@ -27,9 +27,9 @@ import Anthropic from '@anthropic-ai/sdk'
 import type { AgentResult } from '../agent_result.ts'
 import type { AnthropicProviderConfig } from '../brain_config.ts'
 import { DEFAULT_MODEL } from '../brain_config.ts'
+import { BrainError } from '../brain_error.ts'
 import type { Provider, RunWithToolsOptions } from '../provider.ts'
 import type { Tool } from '../tool.ts'
-import { ToolExecutionError } from '../tool_execution_error.ts'
 import type {
   ChatOptions,
   ChatResult,
@@ -39,13 +39,17 @@ import type {
   MCPToolResultBlock,
   MCPToolUseBlock,
   Message,
+  ServerTool,
   StreamEvent,
   SystemPrompt,
   TextBlock,
   ToolResultBlock,
   ToolUseBlock,
 } from '../types.ts'
+import type { AgentGenerateResult } from '../agent_generate_result.ts'
+import type { AgentStreamEvent } from '../agent_stream_event.ts'
 import { parseGenerated, type OutputSchema } from '../output_schema.ts'
+import { runToolWithRecovery } from '../tool_runner.ts'
 
 const EPHEMERAL_CACHE = { type: 'ephemeral' } as const
 
@@ -78,7 +82,7 @@ export class AnthropicProvider implements Provider {
 
   async chat(messages: readonly Message[], options: ChatOptions = {}): Promise<ChatResult> {
     const params = this.buildParams(messages, options)
-    const response = await this.client.messages.create(params)
+    const response = await this.client.messages.create(params, reqOpts(options))
     return this.toChatResult(response)
   }
 
@@ -87,7 +91,7 @@ export class AnthropicProvider implements Provider {
     options: ChatOptions = {},
   ): AsyncIterable<StreamEvent> {
     const params = this.buildParams(messages, options)
-    const stream = this.client.messages.stream(params)
+    const stream = this.client.messages.stream(params, reqOpts(options))
     for await (const event of stream) {
       if (
         event.type === 'content_block_delta' &&
@@ -111,12 +115,15 @@ export class AnthropicProvider implements Provider {
     const base = this.buildParams(messages, options)
     // count_tokens only accepts a subset of MessageCreateParams; build
     // a focused payload that matches what apps actually need to budget.
-    const result = await this.client.messages.countTokens({
-      model: base.model,
-      messages: base.messages,
-      ...(base.system !== undefined ? { system: base.system } : {}),
-      ...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
-    })
+    const result = await this.client.messages.countTokens(
+      {
+        model: base.model,
+        messages: base.messages,
+        ...(base.system !== undefined ? { system: base.system } : {}),
+        ...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
+      },
+      reqOpts(options),
+    )
     return result.input_tokens
   }
 
@@ -151,10 +158,13 @@ export class AnthropicProvider implements Provider {
     const useMcpBeta = mcpServers.length > 0
 
     while (true) {
+      checkAborted(options.signal)
       const params = this.buildParams(workingMessages, options) as Anthropic.MessageCreateParamsNonStreaming & {
         mcp_servers?: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition[]
       }
       params.tools = [
+        // Server tools placed first when present (from buildParams).
+        ...((params.tools ?? []) as Anthropic.ToolUnion[]),
         ...tools.map((t) => ({
           name: t.name,
           description: t.description,
@@ -193,9 +203,10 @@ export class AnthropicProvider implements Provider {
           : [...baseBetas, 'mcp-client-2025-11-20']
         response = (await this.client.beta.messages.create(
           params as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming,
+          reqOpts(options),
         )) as unknown as Anthropic.Message
       } else {
-        response = await this.client.messages.create(params)
+        response = await this.client.messages.create(params, reqOpts(options))
       }
       addUsage(aggregated, response.usage)
       lastStopReason = response.stop_reason ?? null
@@ -226,27 +237,142 @@ export class AnthropicProvider implements Provider {
       )
       const resultBlocks: ContentBlock[] = []
       for (const block of toolUseBlocks) {
-        const tool = toolMap.get(block.name)
-        if (!tool) {
-          throw new ToolExecutionError(
-            block.name,
-            block.id,
-            new Error(`Tool "${block.name}" is not registered.`),
-          )
+        const { content, isError } = await runToolWithRecovery(
+          toolMap.get(block.name),
+          block.name,
+          block.id,
+          block.input,
+          options,
+        )
+        const resultBlock: ToolResultBlock = {
+          type: 'tool_result',
+          toolUseId: block.id,
+          content,
+          ...(isError ? { isError: true } : {}),
+        }
+        resultBlocks.push(resultBlock)
+      }
+      workingMessages.push({ role: 'user', content: resultBlocks })
+
+      iterations++
+      if (iterations >= maxIterations) {
+        return {
+          text: collectText(response.content),
+          messages: workingMessages,
+          iterations,
+          stopReason: 'max_iterations',
+          usage: aggregated,
         }
-        let output: unknown
-        try {
-          output = await tool.execute(block.input, {
-            callId: block.id,
-            context: options.context ?? {},
-          })
-        } catch (cause) {
-          throw new ToolExecutionError(block.name, block.id, cause)
+      }
+    }
+  }
+
+  async runWithToolsAndSchema<T>(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    schema: OutputSchema<T>,
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentGenerateResult<T>> {
+    const maxIterations = options.maxIterations ?? 10
+    const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
+    const workingMessages: Message[] = [...messages]
+    const aggregated: ChatUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    }
+    let iterations = 0
+    let lastStopReason: string | null = null
+
+    const mcpServers = options.mcpServers ?? []
+    const useMcpBeta = mcpServers.length > 0
+
+    while (true) {
+      checkAborted(options.signal)
+      const params = this.buildParams(workingMessages, options) as Anthropic.MessageCreateParamsNonStreaming & {
+        mcp_servers?: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition[]
+      }
+      params.tools = [
+        // Server tools placed first when present (from buildParams).
+        ...((params.tools ?? []) as Anthropic.ToolUnion[]),
+        ...tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: t.inputSchema as Anthropic.Tool.InputSchema,
+        })),
+        ...mcpServers
+          .filter((s) => s.tools?.enabled !== false)
+          .map((s) => ({
+            type: 'mcp_toolset' as const,
+            mcp_server_name: s.name,
+            ...(s.tools?.allowedTools ? { allowed_tools: [...s.tools.allowedTools] } : {}),
+          })),
+      ] as unknown as Anthropic.MessageCreateParams['tools']
+      params.output_config = {
+        ...(params.output_config ?? {}),
+        format: { type: 'json_schema', schema: schema.jsonSchema },
+      }
+
+      let response: Anthropic.Message
+      if (useMcpBeta) {
+        params.mcp_servers = mcpServers.map((s) => {
+          const def: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition = {
+            type: 'url',
+            name: s.name,
+            url: s.url,
+          }
+          if (s.authorizationToken !== undefined) def.authorization_token = s.authorizationToken
+          return def
+        })
+        const baseBetas = (params as { betas?: readonly string[] }).betas ?? []
+        ;(params as { betas?: string[] }).betas = baseBetas.includes('mcp-client-2025-11-20')
+          ? [...baseBetas]
+          : [...baseBetas, 'mcp-client-2025-11-20']
+        response = (await this.client.beta.messages.create(
+          params as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming,
+          reqOpts(options),
+        )) as unknown as Anthropic.Message
+      } else {
+        response = await this.client.messages.create(params, reqOpts(options))
+      }
+      addUsage(aggregated, response.usage)
+      lastStopReason = response.stop_reason ?? null
+
+      workingMessages.push({
+        role: 'assistant',
+        content: fromAnthropicContent(response.content),
+      })
+
+      if (response.stop_reason !== 'tool_use') {
+        const text = collectText(response.content)
+        return {
+          value: parseGenerated(text, schema),
+          text,
+          messages: workingMessages,
+          iterations,
+          stopReason: lastStopReason ?? 'end_turn',
+          usage: aggregated,
         }
+      }
+
+      const toolUseBlocks = response.content.filter(
+        (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use',
+      )
+      const resultBlocks: ContentBlock[] = []
+      for (const block of toolUseBlocks) {
+        const { content, isError } = await runToolWithRecovery(
+          toolMap.get(block.name),
+          block.name,
+          block.id,
+          block.input,
+          options,
+        )
         const resultBlock: ToolResultBlock = {
           type: 'tool_result',
           toolUseId: block.id,
-          content: typeof output === 'string' ? output : JSON.stringify(output),
+          content,
+          ...(isError ? { isError: true } : {}),
         }
         resultBlocks.push(resultBlock)
       }
@@ -254,8 +380,12 @@ export class AnthropicProvider implements Provider {
 
       iterations++
       if (iterations >= maxIterations) {
+        const text = collectText(response.content)
+        // Last turn was a tool_use response, so text may be empty —
+        // surface what we have but the value will likely fail parse.
         return {
-          text: collectText(response.content),
+          value: parseGenerated(text, schema),
+          text,
           messages: workingMessages,
           iterations,
           stopReason: 'max_iterations',
@@ -265,6 +395,338 @@ export class AnthropicProvider implements Provider {
     }
   }
 
+  async *streamWithTools(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent> {
+    const maxIterations = options.maxIterations ?? 10
+    const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
+    const workingMessages: Message[] = [...messages]
+    const aggregated: ChatUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    }
+    let iterations = 0
+
+    const mcpServers = options.mcpServers ?? []
+    const useMcpBeta = mcpServers.length > 0
+
+    while (true) {
+      checkAborted(options.signal)
+      yield { type: 'iteration_start', iteration: iterations }
+
+      const params = this.buildParams(workingMessages, options) as Anthropic.MessageCreateParamsNonStreaming & {
+        mcp_servers?: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition[]
+      }
+      params.tools = [
+        // Server tools placed first when present (from buildParams).
+        ...((params.tools ?? []) as Anthropic.ToolUnion[]),
+        ...tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: t.inputSchema as Anthropic.Tool.InputSchema,
+        })),
+        ...mcpServers
+          .filter((s) => s.tools?.enabled !== false)
+          .map((s) => ({
+            type: 'mcp_toolset' as const,
+            mcp_server_name: s.name,
+            ...(s.tools?.allowedTools ? { allowed_tools: [...s.tools.allowedTools] } : {}),
+          })),
+      ] as unknown as Anthropic.MessageCreateParams['tools']
+
+      if (useMcpBeta) {
+        params.mcp_servers = mcpServers.map((s) => {
+          const def: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition = {
+            type: 'url',
+            name: s.name,
+            url: s.url,
+          }
+          if (s.authorizationToken !== undefined) def.authorization_token = s.authorizationToken
+          return def
+        })
+        const baseBetas = (params as { betas?: readonly string[] }).betas ?? []
+        ;(params as { betas?: string[] }).betas = baseBetas.includes('mcp-client-2025-11-20')
+          ? [...baseBetas]
+          : [...baseBetas, 'mcp-client-2025-11-20']
+      }
+
+      const stream = useMcpBeta
+        ? this.client.beta.messages.stream(
+            params as unknown as Anthropic.Beta.Messages.MessageCreateParamsStreaming,
+            reqOpts(options),
+          )
+        : this.client.messages.stream(params, reqOpts(options))
+
+      // Track tool_use content blocks by their stream index so
+      // `input_json_delta` events can be paired with the correct id.
+      // Anthropic's streaming protocol issues a `content_block_start`
+      // carrying the tool's id + name, then a sequence of
+      // `input_json_delta`s with `partial_json` chunks, then a
+      // `content_block_stop`.
+      const toolBlockIdByIndex = new Map<number, string>()
+      for await (const event of stream) {
+        if (
+          event.type === 'content_block_start' &&
+          event.content_block.type === 'tool_use'
+        ) {
+          toolBlockIdByIndex.set(event.index, event.content_block.id)
+          yield {
+            type: 'tool_use_start',
+            id: event.content_block.id,
+            name: event.content_block.name,
+          }
+        } else if (event.type === 'content_block_delta') {
+          if (event.delta.type === 'text_delta' && event.delta.text.length > 0) {
+            yield { type: 'text', delta: event.delta.text }
+          } else if (event.delta.type === 'input_json_delta') {
+            const id = toolBlockIdByIndex.get(event.index)
+            if (id !== undefined && event.delta.partial_json.length > 0) {
+              yield { type: 'tool_use_delta', id, argsDelta: event.delta.partial_json }
+            }
+          }
+        }
+      }
+      const final = (await stream.finalMessage()) as unknown as Anthropic.Message
+      addUsage(aggregated, final.usage)
+      const finishReason: string | null = final.stop_reason ?? null
+
+      yield { type: 'iteration_end', iteration: iterations, stopReason: finishReason }
+
+      workingMessages.push({
+        role: 'assistant',
+        content: fromAnthropicContent(final.content),
+      })
+
+      if (final.stop_reason !== 'tool_use') {
+        yield {
+          type: 'stop',
+          stopReason: finishReason ?? 'end_turn',
+          iterations,
+          usage: aggregated,
+          messages: workingMessages,
+        }
+        return
+      }
+
+      const toolUseBlocks = final.content.filter(
+        (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use',
+      )
+      const resultBlocks: ContentBlock[] = []
+      for (const block of toolUseBlocks) {
+        yield { type: 'tool_use', id: block.id, name: block.name, input: block.input }
+        const { content, isError } = await runToolWithRecovery(
+          toolMap.get(block.name),
+          block.name,
+          block.id,
+          block.input,
+          options,
+        )
+        resultBlocks.push({
+          type: 'tool_result',
+          toolUseId: block.id,
+          content,
+          ...(isError ? { isError: true } : {}),
+        } satisfies ToolResultBlock)
+        yield {
+          type: 'tool_result',
+          id: block.id,
+          name: block.name,
+          content,
+          isError,
+        }
+      }
+      workingMessages.push({ role: 'user', content: resultBlocks })
+
+      iterations++
+      if (iterations >= maxIterations) {
+        yield {
+          type: 'stop',
+          stopReason: 'max_iterations',
+          iterations,
+          usage: aggregated,
+          messages: workingMessages,
+        }
+        return
+      }
+    }
+  }
+
+  async *streamWithToolsAndSchema<T>(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    schema: OutputSchema<T>,
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent<T>> {
+    const maxIterations = options.maxIterations ?? 10
+    const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
+    const workingMessages: Message[] = [...messages]
+    const aggregated: ChatUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    }
+    let iterations = 0
+
+    const mcpServers = options.mcpServers ?? []
+    const useMcpBeta = mcpServers.length > 0
+
+    while (true) {
+      checkAborted(options.signal)
+      yield { type: 'iteration_start', iteration: iterations }
+
+      const params = this.buildParams(workingMessages, options) as Anthropic.MessageCreateParamsNonStreaming & {
+        mcp_servers?: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition[]
+      }
+      params.tools = [
+        // Server tools placed first when present (from buildParams).
+        ...((params.tools ?? []) as Anthropic.ToolUnion[]),
+        ...tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: t.inputSchema as Anthropic.Tool.InputSchema,
+        })),
+        ...mcpServers
+          .filter((s) => s.tools?.enabled !== false)
+          .map((s) => ({
+            type: 'mcp_toolset' as const,
+            mcp_server_name: s.name,
+            ...(s.tools?.allowedTools ? { allowed_tools: [...s.tools.allowedTools] } : {}),
+          })),
+      ] as unknown as Anthropic.MessageCreateParams['tools']
+      params.output_config = {
+        ...(params.output_config ?? {}),
+        format: { type: 'json_schema', schema: schema.jsonSchema },
+      }
+
+      if (useMcpBeta) {
+        params.mcp_servers = mcpServers.map((s) => {
+          const def: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition = {
+            type: 'url',
+            name: s.name,
+            url: s.url,
+          }
+          if (s.authorizationToken !== undefined) def.authorization_token = s.authorizationToken
+          return def
+        })
+        const baseBetas = (params as { betas?: readonly string[] }).betas ?? []
+        ;(params as { betas?: string[] }).betas = baseBetas.includes('mcp-client-2025-11-20')
+          ? [...baseBetas]
+          : [...baseBetas, 'mcp-client-2025-11-20']
+      }
+
+      const stream = useMcpBeta
+        ? this.client.beta.messages.stream(
+            params as unknown as Anthropic.Beta.Messages.MessageCreateParamsStreaming,
+            reqOpts(options),
+          )
+        : this.client.messages.stream(params, reqOpts(options))
+
+      // Track tool_use content blocks by their stream index so
+      // `input_json_delta` events can be paired with the correct id.
+      // Anthropic's streaming protocol issues a `content_block_start`
+      // carrying the tool's id + name, then a sequence of
+      // `input_json_delta`s with `partial_json` chunks, then a
+      // `content_block_stop`.
+      const toolBlockIdByIndex = new Map<number, string>()
+      for await (const event of stream) {
+        if (
+          event.type === 'content_block_start' &&
+          event.content_block.type === 'tool_use'
+        ) {
+          toolBlockIdByIndex.set(event.index, event.content_block.id)
+          yield {
+            type: 'tool_use_start',
+            id: event.content_block.id,
+            name: event.content_block.name,
+          }
+        } else if (event.type === 'content_block_delta') {
+          if (event.delta.type === 'text_delta' && event.delta.text.length > 0) {
+            yield { type: 'text', delta: event.delta.text }
+          } else if (event.delta.type === 'input_json_delta') {
+            const id = toolBlockIdByIndex.get(event.index)
+            if (id !== undefined && event.delta.partial_json.length > 0) {
+              yield { type: 'tool_use_delta', id, argsDelta: event.delta.partial_json }
+            }
+          }
+        }
+      }
+      const final = (await stream.finalMessage()) as unknown as Anthropic.Message
+      addUsage(aggregated, final.usage)
+      const finishReason: string | null = final.stop_reason ?? null
+      yield { type: 'iteration_end', iteration: iterations, stopReason: finishReason }
+
+      workingMessages.push({
+        role: 'assistant',
+        content: fromAnthropicContent(final.content),
+      })
+
+      if (final.stop_reason !== 'tool_use') {
+        const text = collectText(final.content)
+        const value = parseGenerated(text, schema)
+        yield {
+          type: 'stop',
+          stopReason: finishReason ?? 'end_turn',
+          iterations,
+          usage: aggregated,
+          messages: workingMessages,
+          value,
+          text,
+        } as AgentStreamEvent<T>
+        return
+      }
+
+      const toolUseBlocks = final.content.filter(
+        (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use',
+      )
+      const resultBlocks: ContentBlock[] = []
+      for (const block of toolUseBlocks) {
+        yield { type: 'tool_use', id: block.id, name: block.name, input: block.input }
+        const { content, isError } = await runToolWithRecovery(
+          toolMap.get(block.name),
+          block.name,
+          block.id,
+          block.input,
+          options,
+        )
+        resultBlocks.push({
+          type: 'tool_result',
+          toolUseId: block.id,
+          content,
+          ...(isError ? { isError: true } : {}),
+        } satisfies ToolResultBlock)
+        yield {
+          type: 'tool_result',
+          id: block.id,
+          name: block.name,
+          content,
+          isError,
+        }
+      }
+      workingMessages.push({ role: 'user', content: resultBlocks })
+
+      iterations++
+      if (iterations >= maxIterations) {
+        const text = collectText(final.content)
+        const value = parseGenerated(text, schema)
+        yield {
+          type: 'stop',
+          stopReason: 'max_iterations',
+          iterations,
+          usage: aggregated,
+          messages: workingMessages,
+          value,
+          text,
+        } as AgentStreamEvent<T>
+        return
+      }
+    }
+  }
+
   async generate<T>(
     messages: readonly Message[],
     schema: OutputSchema<T>,
@@ -275,7 +737,7 @@ export class AnthropicProvider implements Provider {
       ...(params.output_config ?? {}),
       format: { type: 'json_schema', schema: schema.jsonSchema },
     }
-    const response = await this.client.messages.create(params)
+    const response = await this.client.messages.create(params, reqOpts(options))
     const text = collectText(response.content)
     const value = parseGenerated(text, schema)
     return {
@@ -325,6 +787,10 @@ export class AnthropicProvider implements Provider {
       ;(params as { betas?: readonly string[] }).betas = betas
     }
 
+    if (options.serverTools && options.serverTools.length > 0) {
+      params.tools = anthropicServerTools(options.serverTools)
+    }
+
     return params
   }
 
@@ -345,6 +811,18 @@ export class AnthropicProvider implements Provider {
 
 // ─── Shape converters ─────────────────────────────────────────────────────
 
+/** Build the request-options bag forwarded to the SDK. Only `signal` for now. */
+function reqOpts(options: { signal?: AbortSignal }): { signal?: AbortSignal } | undefined {
+  return options.signal !== undefined ? { signal: options.signal } : undefined
+}
+
+/** Throw a DOMException-shaped abort error if the signal has fired. */
+function checkAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('Aborted', 'AbortError')
+  }
+}
+
 function toUsage(u: Anthropic.Usage): ChatUsage {
   return {
     inputTokens: u.input_tokens,
@@ -392,6 +870,41 @@ function toMessageParam(message: Message): Anthropic.MessageParam {
           if (block.isError) param.is_error = true
           return param
         }
+        if (block.type === 'image') {
+          return {
+            type: 'image',
+            source:
+              block.source.type === 'base64'
+                ? {
+                    type: 'base64',
+                    media_type:
+                      block.source.mediaType as Anthropic.Base64ImageSource['media_type'],
+                    data: block.source.data,
+                  }
+                : { type: 'url', url: block.source.url },
+          } satisfies Anthropic.ImageBlockParam
+        }
+        if (block.type === 'document') {
+          const documentParam: Anthropic.DocumentBlockParam = {
+            type: 'document',
+            source:
+              block.source.type === 'base64'
+                ? {
+                    type: 'base64',
+                    media_type: 'application/pdf',
+                    data: block.source.data,
+                  }
+                : { type: 'url', url: block.source.url },
+          }
+          if (block.title !== undefined) documentParam.title = block.title
+          return documentParam
+        }
+        if (block.type === 'audio') {
+          throw new BrainError(
+            "AnthropicProvider: audio blocks are not supported. Anthropic's SDK does not expose an audio block type for chat messages. Route audio workloads to Gemini, or transcribe upstream and pass the text.",
+            { context: { provider: 'anthropic' } },
+          )
+        }
         const text: Anthropic.TextBlockParam = { type: 'text', text: block.text }
         if (block.cache) text.cache_control = EPHEMERAL_CACHE
         return text
@@ -416,6 +929,61 @@ function toSystemParam(
   return [param]
 }
 
+/**
+ * Translate framework `ServerTool[]` into Anthropic's typed
+ * server-tool entries. Uses the latest SDK-known versions; the
+ * Anthropic backend is backward-compatible to older clients
+ * pinning earlier dates, but we standardize on current. Web fetch
+ * is Anthropic-only; `url_context` is rejected (Gemini-only).
+ */
+function anthropicServerTools(serverTools: readonly ServerTool[]): Anthropic.ToolUnion[] {
+  const out: Anthropic.ToolUnion[] = []
+  for (const t of serverTools) {
+    if (t.type === 'web_search') {
+      const tool: Anthropic.WebSearchTool20260209 = {
+        type: 'web_search_20260209',
+        name: 'web_search',
+      }
+      if (t.maxUses !== undefined) {
+        ;(tool as { max_uses?: number }).max_uses = t.maxUses
+      }
+      if (t.allowedDomains !== undefined) {
+        tool.allowed_domains = [...t.allowedDomains]
+      }
+      if (t.blockedDomains !== undefined) {
+        tool.blocked_domains = [...t.blockedDomains]
+      }
+      out.push(tool)
+    } else if (t.type === 'code_execution') {
+      out.push({
+        type: 'code_execution_20260120',
+        name: 'code_execution',
+      } satisfies Anthropic.CodeExecutionTool20260120)
+    } else if (t.type === 'web_fetch') {
+      const tool: Anthropic.WebFetchTool20260309 = {
+        type: 'web_fetch_20260309',
+        name: 'web_fetch',
+      }
+      if (t.maxUses !== undefined) {
+        ;(tool as { max_uses?: number }).max_uses = t.maxUses
+      }
+      if (t.allowedDomains !== undefined) {
+        tool.allowed_domains = [...t.allowedDomains]
+      }
+      if (t.blockedDomains !== undefined) {
+        tool.blocked_domains = [...t.blockedDomains]
+      }
+      out.push(tool)
+    } else if (t.type === 'url_context') {
+      throw new BrainError(
+        'AnthropicProvider: server tool `url_context` is Gemini-only. Use `web_fetch` for Anthropic or route the call to Gemini.',
+        { context: { provider: 'anthropic' } },
+      )
+    }
+  }
+  return out
+}
+
 function mergeBetas(
   providerBetas: readonly string[],
   callBetas: readonly string[] | undefined,