@strav/brain 1.0.0-alpha.22 → 1.0.0-alpha.25

package/src/providers/anthropic_provider.ts

@@ -1,1194 +0,0 @@
-/**
- * `AnthropicProvider` — implementation of `Provider` backed by the
- * official `@anthropic-ai/sdk`.
- *
- * Responsibilities:
- *   1. Hold a singleton `Anthropic` client instance for the
- *      configured API key + base URL.
- *   2. Translate the framework's `ChatOptions` / `Message` shapes
- *      into Anthropic's `MessageCreateParams` (system as `TextBlock[]`
- *      with `cache_control` when requested; messages with per-block
- *      cache flags translated likewise; `thinking` mapped to
- *      `ThinkingConfigParam`; `effort` placed under `output_config`).
- *   3. Translate the response back to `ChatResult` — flatten the
- *      content blocks into a single `text` string, surface usage with
- *      cache-hit counters, and pass the raw `Message` through on `.raw`.
- *   4. Stream via `client.messages.stream()` and yield the framework
- *      `StreamEvent` union — `text` deltas plus a terminal `stop`
- *      event with usage + stop reason.
- *
- * Errors from the SDK propagate; apps that want provider-specific
- * recovery can `instanceof Anthropic.RateLimitError` etc. The brain
- * facade wraps the call site in `BrainError` only for invariants the
- * facade owns (e.g. "no provider configured").
- */
-
-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,
-  RunWithToolsOptionsWithSuspend,
-} from '../provider.ts'
-import type { SuspendedRun } from '../suspended_run.ts'
-import type { Tool } from '../tool.ts'
-import type {
-  ChatOptions,
-  ChatResult,
-  ChatUsage,
-  CompactionBlock,
-  ContentBlock,
-  GenerateResult,
-  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
-
-export class AnthropicProvider implements Provider {
-  readonly name: string
-  private readonly client: Anthropic
-  private readonly defaultModel: string
-  private readonly defaultMaxTokens: number
-  private readonly betas: readonly string[]
-
-  constructor(
-    name: string,
-    config: AnthropicProviderConfig,
-    options: { client?: Anthropic } = {},
-  ) {
-    this.name = name
-    this.defaultModel = config.defaultModel ?? DEFAULT_MODEL
-    this.defaultMaxTokens = config.defaultMaxTokens ?? 4096
-    this.betas = config.betas ?? []
-    // `client` injection point — tests pass a stub; apps that want a
-    // pre-configured SDK instance (custom retry, fetch transport, etc.)
-    // build their own and hand it over here.
-    this.client =
-      options.client ??
-      new Anthropic({
-        apiKey: config.apiKey,
-        ...(config.baseUrl !== undefined ? { baseURL: config.baseUrl } : {}),
-      })
-  }
-
-  async chat(messages: readonly Message[], options: ChatOptions = {}): Promise<ChatResult> {
-    const params = this.buildParams(messages, options)
-    const useBeta = needsBetaRouting(params)
-    const response = useBeta
-      ? ((await this.client.beta.messages.create(
-          params as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming,
-          reqOpts(options),
-        )) as unknown as Anthropic.Message)
-      : await this.client.messages.create(params, reqOpts(options))
-    return this.toChatResult(response)
-  }
-
-  async *stream(
-    messages: readonly Message[],
-    options: ChatOptions = {},
-  ): AsyncIterable<StreamEvent> {
-    const params = this.buildParams(messages, options)
-    const stream = needsBetaRouting(params)
-      ? this.client.beta.messages.stream(
-          params as unknown as Anthropic.Beta.Messages.MessageCreateParamsStreaming,
-          reqOpts(options),
-        )
-      : this.client.messages.stream(params, reqOpts(options))
-    for await (const event of stream) {
-      if (
-        event.type === 'content_block_delta' &&
-        event.delta.type === 'text_delta'
-      ) {
-        yield { type: 'text', delta: event.delta.text }
-      }
-    }
-    const final = await stream.finalMessage()
-    yield {
-      type: 'stop',
-      stopReason: final.stop_reason,
-      usage: toUsage(final.usage),
-    }
-  }
-
-  async countTokens(
-    messages: readonly Message[],
-    options: ChatOptions = {},
-  ): Promise<number> {
-    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 } : {}),
-      },
-      reqOpts(options),
-    )
-    return result.input_tokens
-  }
-
-  /**
-   * Agentic loop. Send → detect tool_use blocks → execute → append
-   * tool_result → re-send, until the model returns `end_turn` or
-   * the iteration ceiling is hit.
-   *
-   * Tools are passed once on every call — Anthropic doesn't carry
-   * tool state across requests; the model rediscovers them from the
-   * `tools` array each turn. Apps that care about cache hits keep
-   * the tool list stable across runs.
-   */
-  runWithTools(
-    messages: readonly Message[],
-    tools: readonly Tool[],
-    options: RunWithToolsOptionsWithSuspend,
-  ): Promise<AgentResult | SuspendedRun>
-  runWithTools(
-    messages: readonly Message[],
-    tools: readonly Tool[],
-    options?: RunWithToolsOptions,
-  ): Promise<AgentResult>
-  async runWithTools(
-    messages: readonly Message[],
-    tools: readonly Tool[],
-    options: RunWithToolsOptions = {},
-  ): Promise<AgentResult | SuspendedRun> {
-    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,
-        })),
-        // MCP toolsets — one per declared server. The model sees the
-        // server's tools via Anthropic's connector, not via our local
-        // `tools` list.
-        ...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']
-
-      // Declare MCP servers + flip to the beta surface when in use.
-      // Anthropic's MCP connector requires `mcp-client-2025-11-20`.
-      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']
-      }
-      // Route via beta when either MCP servers OR compaction are in
-      // play — both live on the beta surface.
-      const response: Anthropic.Message = needsBetaRouting(params)
-        ? ((await this.client.beta.messages.create(
-            params as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming,
-            reqOpts(options),
-          )) as unknown as Anthropic.Message)
-        : await this.client.messages.create(params, reqOpts(options))
-      addUsage(aggregated, response.usage)
-      lastStopReason = response.stop_reason ?? null
-
-      // Append the assistant turn verbatim from the SDK shape so
-      // tool_use blocks survive to the next request unchanged.
-      workingMessages.push({
-        role: 'assistant',
-        content: fromAnthropicContent(response.content),
-      })
-
-      if (response.stop_reason !== 'tool_use') {
-        return {
-          text: collectText(response.content),
-          messages: workingMessages,
-          iterations,
-          stopReason: lastStopReason ?? 'end_turn',
-          usage: aggregated,
-        }
-      }
-
-      // Execute every tool_use block in the response and append the
-      // results in a single user-role turn. The SDK's API expects all
-      // tool_result blocks for a given assistant turn to land in the
-      // same user message.
-      const toolUseBlocks = response.content.filter(
-        (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use',
-      )
-      const resultBlocks: ContentBlock[] = []
-      for (let i = 0; i < toolUseBlocks.length; i++) {
-        const block = toolUseBlocks[i]!
-        if (options.shouldSuspend) {
-          const frameworkCall: ToolUseBlock = {
-            type: 'tool_use',
-            id: block.id,
-            name: block.name,
-            input: block.input as Record<string, unknown>,
-          }
-          if (await options.shouldSuspend(frameworkCall, options.context)) {
-            return {
-              status: 'suspended',
-              pendingToolCalls: toolUseBlocks.slice(i).map((b) => ({
-                type: 'tool_use',
-                id: b.id,
-                name: b.name,
-                input: b.input as Record<string, unknown>,
-              })),
-              state: { messages: workingMessages, iterations, usage: aggregated },
-            }
-          }
-        }
-        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,
-        }
-      }
-    }
-  }
-
-  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 },
-      }
-
-      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 response: Anthropic.Message = needsBetaRouting(params)
-        ? ((await this.client.beta.messages.create(
-            params as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming,
-            reqOpts(options),
-          )) as unknown as Anthropic.Message)
-        : 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,
-          ...(isError ? { isError: true } : {}),
-        }
-        resultBlocks.push(resultBlock)
-      }
-      workingMessages.push({ role: 'user', content: resultBlocks })
-
-      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 {
-          value: parseGenerated(text, schema),
-          text,
-          messages: workingMessages,
-          iterations,
-          stopReason: 'max_iterations',
-          usage: aggregated,
-        }
-      }
-    }
-  }
-
-  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 = needsBetaRouting(params)
-        ? 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 = needsBetaRouting(params)
-        ? 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>,
-    options: ChatOptions = {},
-  ): Promise<GenerateResult<T>> {
-    const params = this.buildParams(messages, options) as Anthropic.MessageCreateParamsNonStreaming
-    params.output_config = {
-      ...(params.output_config ?? {}),
-      format: { type: 'json_schema', schema: schema.jsonSchema },
-    }
-    const response = await this.client.messages.create(params, reqOpts(options))
-    const text = collectText(response.content)
-    const value = parseGenerated(text, schema)
-    return {
-      value,
-      text,
-      model: response.model,
-      stopReason: response.stop_reason,
-      usage: toUsage(response.usage),
-      raw: response,
-    }
-  }
-
-  // ─── Param translation ──────────────────────────────────────────────────
-
-  private buildParams(
-    messages: readonly Message[],
-    options: ChatOptions,
-  ): Anthropic.MessageCreateParamsNonStreaming {
-    const model = options.model ?? this.defaultModel
-    const params: Anthropic.MessageCreateParamsNonStreaming = {
-      model,
-      max_tokens: options.maxTokens ?? this.defaultMaxTokens,
-      messages: messages.map(toMessageParam),
-    }
-
-    const system = toSystemParam(options.system)
-    if (system !== undefined) params.system = system
-
-    if (options.thinking === 'adaptive') {
-      params.thinking = { type: 'adaptive' }
-    } else if (options.thinking === 'disabled') {
-      params.thinking = { type: 'disabled' }
-    }
-
-    if (options.effort !== undefined) {
-      params.output_config = { effort: options.effort }
-    }
-
-    if (options.cache === true) {
-      // Top-level auto-cache the last cacheable block. Maps to the
-      // SDK's `cache_control` shorthand on the request body.
-      ;(params as { cache_control?: { type: 'ephemeral' } }).cache_control = EPHEMERAL_CACHE
-    }
-
-    // Compaction — emits the beta `edits` entry + flips the
-    // `compact-2026-01-12` beta header so the request goes through
-    // the SDK's beta surface (same routing as MCP).
-    const baseBetas = mergeBetas(this.betas, options.betas)
-    const betas = options.compact !== undefined
-      ? mergeBetas(baseBetas, [COMPACT_BETA])
-      : baseBetas
-    if (options.compact !== undefined) {
-      const edit: Record<string, unknown> = { type: COMPACT_EDIT_TYPE }
-      if (options.compact.trigger !== undefined) {
-        edit.trigger = { type: 'input_tokens', value: options.compact.trigger }
-      }
-      if (options.compact.instructions !== undefined) {
-        edit.instructions = options.compact.instructions
-      }
-      if (options.compact.pauseAfterCompaction !== undefined) {
-        edit.pause_after_compaction = options.compact.pauseAfterCompaction
-      }
-      ;(params as { edits?: unknown[] }).edits = [edit]
-    }
-    if (betas.length > 0) {
-      ;(params as { betas?: readonly string[] }).betas = betas
-    }
-
-    if (options.serverTools && options.serverTools.length > 0) {
-      params.tools = anthropicServerTools(options.serverTools)
-    }
-
-    return params
-  }
-
-  private toChatResult(message: Anthropic.Message): ChatResult<Anthropic.Message> {
-    const text = message.content
-      .filter((b): b is Anthropic.TextBlock => b.type === 'text')
-      .map((b) => b.text)
-      .join('')
-    const result: ChatResult<Anthropic.Message> = {
-      text,
-      model: message.model,
-      stopReason: message.stop_reason,
-      usage: toUsage(message.usage),
-      raw: message,
-    }
-    // Surface structured content when the turn carries blocks
-    // beyond plain text (compaction today; reasoning blocks in a
-    // future slice). Apps that persist conversations push this
-    // onto the message history so round-trippable blocks survive
-    // subsequent requests.
-    const blocks = fromAnthropicContent(message.content)
-    if (blocks.some((b) => b.type !== 'text')) {
-      result.content = blocks
-    }
-    return result
-  }
-}
-
-// ─── Shape converters ─────────────────────────────────────────────────────
-
-/** Compaction beta — required header + `edits[].type` for `compact-2026-01-12`. */
-const COMPACT_BETA = 'compact-2026-01-12'
-const COMPACT_EDIT_TYPE = 'compact_20260112'
-
-/**
- * Whether the request needs to flow through `client.beta.messages.create`
- * instead of the stable surface. Triggered by:
- *
- *   - `edits[]` (compaction).
- *   - `mcp_servers[]` (server-side MCP).
- *
- * Tests typically stub `client.messages.create`; the beta path uses the
- * stub that lives at `client.beta.messages.create`.
- */
-function needsBetaRouting(params: Anthropic.MessageCreateParamsNonStreaming): boolean {
-  const p = params as { edits?: unknown[]; mcp_servers?: unknown[] }
-  return (p.edits !== undefined && p.edits.length > 0)
-    || (p.mcp_servers !== undefined && p.mcp_servers.length > 0)
-}
-
-/** 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,
-    outputTokens: u.output_tokens,
-    cacheReadTokens: u.cache_read_input_tokens ?? 0,
-    cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
-  }
-}
-
-function toMessageParam(message: Message): Anthropic.MessageParam {
-  if (typeof message.content === 'string') {
-    return { role: message.role, content: message.content }
-  }
-  return {
-    role: message.role,
-    content: message.content
-      // MCP blocks are inbound-only — Anthropic produces them, we
-      // surface them on `result.messages` for observability, but we
-      // never echo them back to the model. The backend tracks MCP
-      // tool state on its side.
-      .filter(
-        (b): b is Exclude<ContentBlock, MCPToolUseBlock | MCPToolResultBlock> =>
-          b.type !== 'mcp_tool_use' && b.type !== 'mcp_tool_result',
-      )
-      .map((block): Anthropic.ContentBlockParam => {
-        if (block.type === 'tool_use') {
-          return {
-            type: 'tool_use',
-            id: block.id,
-            name: block.name,
-            input: block.input as Record<string, unknown>,
-          }
-        }
-        if (block.type === 'tool_result') {
-          const param: Anthropic.ToolResultBlockParam = {
-            type: 'tool_result',
-            tool_use_id: block.toolUseId,
-            content:
-              typeof block.content === 'string'
-                ? block.content
-                : block.content.map(
-                    (b) => ({ type: 'text', text: b.text }) as Anthropic.TextBlockParam,
-                  ),
-          }
-          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' } },
-          )
-        }
-        if (block.type === 'compaction') {
-          // Round-trip the compaction block verbatim — the server uses
-          // the opaque `encrypted_content` to stitch prior compactions
-          // together; mutating either field would invalidate the
-          // history. Untyped on the stable SDK surface; cast through
-          // the beta type shape.
-          const param: Record<string, unknown> = { type: 'compaction' }
-          if (block.content !== null) param.content = block.content
-          if (block.encryptedContent !== null) {
-            param.encrypted_content = block.encryptedContent
-          }
-          return param as unknown as Anthropic.ContentBlockParam
-        }
-        const text: Anthropic.TextBlockParam = { type: 'text', text: block.text }
-        if (block.cache) text.cache_control = EPHEMERAL_CACHE
-        return text
-      }),
-  }
-}
-
-function toSystemParam(
-  system: SystemPrompt | undefined,
-): string | Anthropic.TextBlockParam[] | undefined {
-  if (system === undefined) return undefined
-  if (typeof system === 'string') return system
-  if (Array.isArray(system)) {
-    return system.map((block) => {
-      const param: Anthropic.TextBlockParam = { type: 'text', text: block.text }
-      if (block.cache) param.cache_control = EPHEMERAL_CACHE
-      return param
-    })
-  }
-  const param: Anthropic.TextBlockParam = { type: 'text', text: system.text }
-  if (system.cache) param.cache_control = EPHEMERAL_CACHE
-  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,
-): readonly string[] {
-  if (!callBetas || callBetas.length === 0) return providerBetas
-  const seen = new Set<string>()
-  const out: string[] = []
-  for (const b of providerBetas) {
-    if (seen.has(b)) continue
-    seen.add(b)
-    out.push(b)
-  }
-  for (const b of callBetas) {
-    if (seen.has(b)) continue
-    seen.add(b)
-    out.push(b)
-  }
-  return out
-}
-
-function addUsage(acc: ChatUsage, u: Anthropic.Usage): void {
-  acc.inputTokens += u.input_tokens
-  acc.outputTokens += u.output_tokens
-  acc.cacheReadTokens += u.cache_read_input_tokens ?? 0
-  acc.cacheCreationTokens += u.cache_creation_input_tokens ?? 0
-}
-
-function collectText(content: Anthropic.ContentBlock[]): string {
-  return content
-    .filter((b): b is Anthropic.TextBlock => b.type === 'text')
-    .map((b) => b.text)
-    .join('')
-}
-
-/**
- * Translate the SDK's response content blocks back into framework
- * `ContentBlock`s for storage in `workingMessages`. We preserve
- * `text` and `tool_use` blocks verbatim; other server-side block
- * types (thinking, server tool blocks) are dropped — V1 doesn't
- * surface them, and re-sending them as part of the assistant turn
- * could confuse the model.
- */
-function fromAnthropicContent(
-  content: ReadonlyArray<Anthropic.ContentBlock | { type: string; [k: string]: unknown }>,
-): ContentBlock[] {
-  const out: ContentBlock[] = []
-  for (const block of content) {
-    if (block.type === 'text') {
-      out.push({ type: 'text', text: (block as { text: string }).text } satisfies TextBlock)
-    } else if (block.type === 'tool_use') {
-      const u = block as { id: string; name: string; input: unknown }
-      out.push({
-        type: 'tool_use',
-        id: u.id,
-        name: u.name,
-        input: u.input,
-      } satisfies ToolUseBlock)
-    } else if (block.type === 'mcp_tool_use') {
-      const m = block as unknown as {
-        id: string
-        server_name: string
-        name: string
-        input: unknown
-      }
-      out.push({
-        type: 'mcp_tool_use',
-        id: m.id,
-        serverName: m.server_name,
-        name: m.name,
-        input: m.input,
-      } satisfies MCPToolUseBlock)
-    } else if (block.type === 'mcp_tool_result') {
-      const r = block as unknown as {
-        tool_use_id: string
-        content: string | Array<{ type: 'text'; text: string }>
-        is_error?: boolean
-      }
-      const result: MCPToolResultBlock = {
-        type: 'mcp_tool_result',
-        toolUseId: r.tool_use_id,
-        content:
-          typeof r.content === 'string'
-            ? r.content
-            : r.content.map((c) => ({ type: 'text', text: c.text }) satisfies TextBlock),
-      }
-      if (r.is_error) result.isError = true
-      out.push(result)
-    } else if (block.type === 'compaction') {
-      const c = block as { content?: string | null; encrypted_content?: string | null }
-      out.push({
-        type: 'compaction',
-        content: c.content ?? null,
-        encryptedContent: c.encrypted_content ?? null,
-      } satisfies CompactionBlock)
-    }
-  }
-  return out
-}