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

package/src/providers/anthropic_provider.ts

@@ -27,25 +27,35 @@ 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 type { Provider, RunWithToolsOptions } from '../provider.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 { ToolExecutionError } from '../tool_execution_error.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
 
@@ -78,7 +88,13 @@ 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 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)
   }
 
@@ -87,7 +103,12 @@ export class AnthropicProvider implements Provider {
     options: ChatOptions = {},
   ): AsyncIterable<StreamEvent> {
     const params = this.buildParams(messages, options)
-    const stream = this.client.messages.stream(params)
+    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' &&
@@ -111,12 +132,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
   }
 
@@ -130,11 +154,21 @@ export class AnthropicProvider implements Provider {
    * `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> {
+  ): Promise<AgentResult | SuspendedRun> {
     const maxIterations = options.maxIterations ?? 10
     const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
     const workingMessages: Message[] = [...messages]
@@ -151,10 +185,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,
@@ -176,7 +213,6 @@ export class AnthropicProvider implements Provider {
 
       // Declare MCP servers + flip to the beta surface when in use.
       // Anthropic's MCP connector requires `mcp-client-2025-11-20`.
-      let response: Anthropic.Message
       if (useMcpBeta) {
         params.mcp_servers = mcpServers.map((s) => {
           const def: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition = {
@@ -191,12 +227,15 @@ export class AnthropicProvider implements Provider {
         ;(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,
-        )) as unknown as Anthropic.Message
-      } else {
-        response = await this.client.messages.create(params)
       }
+      // 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
 
@@ -225,28 +264,40 @@ export class AnthropicProvider implements Provider {
         (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use',
       )
       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.`),
-          )
-        }
-        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)
+      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: typeof output === 'string' ? output : JSON.stringify(output),
+          content,
+          ...(isError ? { isError: true } : {}),
         }
         resultBlocks.push(resultBlock)
       }
@@ -265,6 +316,465 @@ export class AnthropicProvider implements Provider {
     }
   }
 
+  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>,
@@ -275,7 +785,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 {
@@ -320,11 +830,34 @@ export class AnthropicProvider implements Provider {
       ;(params as { cache_control?: { type: 'ephemeral' } }).cache_control = EPHEMERAL_CACHE
     }
 
-    const betas = mergeBetas(this.betas, options.betas)
+    // 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
   }
 
@@ -333,18 +866,60 @@ export class AnthropicProvider implements Provider {
       .filter((b): b is Anthropic.TextBlock => b.type === 'text')
       .map((b) => b.text)
       .join('')
-    return {
+    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,
@@ -392,6 +967,54 @@ 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' } },
+          )
+        }
+        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
@@ -416,6 +1039,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,
@@ -503,6 +1181,13 @@ function fromAnthropicContent(
       }
       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