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

package/src/drivers/anthropic/anthropic_message_builder.ts

@@ -0,0 +1,258 @@
+/**
+ * Pure-function builders for the Anthropic messages-create request
+ * payload. Separated from `AnthropicBrainDriver` so the wire-shape
+ * translation can be unit-tested without instantiating an SDK
+ * client.
+ */
+
+import type Anthropic from '@anthropic-ai/sdk'
+import { BrainError } from '../../brain_error.ts'
+import type { ChatOptions } from '../../types.ts'
+import type {
+  ContentBlock,
+  MCPToolResultBlock,
+  MCPToolUseBlock,
+  Message,
+  ServerTool,
+  SystemPrompt,
+} from '../../types.ts'
+import { mergeBetas } from './anthropic_helpers.ts'
+
+/** Compaction beta — required header + `edits[].type` for `compact-2026-01-12`. */
+export const COMPACT_BETA = 'compact-2026-01-12'
+export const COMPACT_EDIT_TYPE = 'compact_20260112'
+
+const EPHEMERAL_CACHE = { type: 'ephemeral' } as const
+
+/** Defaults the driver injects when the call site omits them. */
+export interface AnthropicBuildDefaults {
+  defaultModel: string
+  defaultMaxTokens: number
+  betas: readonly string[]
+}
+
+export 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(
+            "AnthropicBrainDriver: 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
+      }),
+  }
+}
+
+export 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).
+ */
+export 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(
+        'AnthropicBrainDriver: server tool `url_context` is Gemini-only. Use `web_fetch` for Anthropic or route the call to Gemini.',
+        { context: { provider: 'anthropic' } },
+      )
+    }
+  }
+  return out
+}
+
+export function buildAnthropicMessageParams(
+  messages: readonly Message[],
+  options: ChatOptions,
+  defaults: AnthropicBuildDefaults,
+): Anthropic.MessageCreateParamsNonStreaming {
+  const model = options.model ?? defaults.defaultModel
+  const params: Anthropic.MessageCreateParamsNonStreaming = {
+    model,
+    max_tokens: options.maxTokens ?? defaults.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(defaults.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
+}

package/src/drivers/anthropic/anthropic_response_mapper.ts

@@ -0,0 +1,123 @@
+/**
+ * Pure-function mappers for Anthropic message responses back into
+ * framework shapes (`ContentBlock[]`, `ChatUsage`, `ChatResult`).
+ * Extracted from `AnthropicBrainDriver` so the response-shape
+ * translation can be unit-tested in isolation.
+ */
+
+import type Anthropic from '@anthropic-ai/sdk'
+import type {
+  ChatResult,
+  ChatUsage,
+  CompactionBlock,
+  ContentBlock,
+  MCPToolResultBlock,
+  MCPToolUseBlock,
+  TextBlock,
+  ToolUseBlock,
+} from '../../types.ts'
+import { collectText } from './anthropic_helpers.ts'
+
+export function toAnthropicUsage(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,
+  }
+}
+
+export function addAnthropicUsage(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
+}
+
+export function toAnthropicChatResult(
+  message: Anthropic.Message,
+): ChatResult<Anthropic.Message> {
+  const text = collectText(message.content)
+  const result: ChatResult<Anthropic.Message> = {
+    text,
+    model: message.model,
+    stopReason: message.stop_reason,
+    usage: toAnthropicUsage(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
+}
+
+/**
+ * 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.
+ */
+export 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
+}

package/src/drivers/anthropic/anthropic_tool_loop.ts

@@ -0,0 +1,246 @@
+/**
+ * Shared non-streaming tool-loop iteration for Anthropic.
+ *
+ * Mirrors `openai_tool_loop.ts` — extracts the per-iteration body
+ * so `runWithTools` and `runWithToolsAndSchema` become thin
+ * orchestrators that only encode their own terminal return shape
+ * (`AgentResult | SuspendedRun` vs `AgentGenerateResult<T>`).
+ *
+ * Also exports `injectToolsAndMCP`, the local-tools + MCP-toolset +
+ * beta-header injection block that both runners apply after
+ * `buildParams`. Anthropic's MCP connector requires the
+ * `mcp-client-2025-11-20` beta header; the injector flips it
+ * automatically when MCP servers are declared.
+ *
+ * Streaming variants are not unified here — same rationale as
+ * OpenAI: yielding events mid-iteration requires an async-generator
+ * wrapper with reader-complexity cost that outweighs the LOC win.
+ */
+
+import type Anthropic from '@anthropic-ai/sdk'
+import type { RunWithToolsOptions } from '../../brain_driver.ts'
+import type { MCPServer } from '../../mcp_server.ts'
+import type { Tool } from '../../tool.ts'
+import { runToolWithRecovery } from '../../tool_runner.ts'
+import type {
+  ChatUsage,
+  ContentBlock,
+  Message,
+  ToolResultBlock,
+  ToolUseBlock,
+} from '../../types.ts'
+import {
+  checkAborted,
+  collectText,
+  needsBetaRouting,
+  reqOpts,
+} from './anthropic_helpers.ts'
+import {
+  addAnthropicUsage,
+  fromAnthropicContent,
+} from './anthropic_response_mapper.ts'
+
+const MCP_BETA = 'mcp-client-2025-11-20'
+
+/** Params shape with the optional MCP-beta field surfaced for inline mutation. */
+type ParamsWithMcp = Anthropic.MessageCreateParamsNonStreaming & {
+  mcp_servers?: Anthropic.Beta.Messages.BetaRequestMCPServerURLDefinition[]
+}
+
+/**
+ * Inject local tools + MCP toolsets into `params.tools`, declare MCP
+ * servers, and flip the `mcp-client-2025-11-20` beta header when MCP
+ * is in play. Mutates `params` in place; returns the same reference
+ * for chaining.
+ *
+ * Both runners call this once per iteration after `buildParams` and
+ * after any runner-specific augmentation (e.g. `output_config.format`
+ * for the schema variant).
+ */
+export function injectToolsAndMCP(
+  params: Anthropic.MessageCreateParamsNonStreaming,
+  args: { tools: readonly Tool[]; mcpServers: readonly MCPServer[] },
+): ParamsWithMcp {
+  const p = params as ParamsWithMcp
+  p.tools = [
+    // Server tools placed first when present (from buildParams).
+    ...((p.tools ?? []) as Anthropic.ToolUnion[]),
+    ...args.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.
+    ...args.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 (args.mcpServers.length > 0) {
+    p.mcp_servers = args.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 = (p as { betas?: readonly string[] }).betas ?? []
+    ;(p as { betas?: string[] }).betas = baseBetas.includes(MCP_BETA)
+      ? [...baseBetas]
+      : [...baseBetas, MCP_BETA]
+  }
+  return p
+}
+
+/** Per-iteration mutable state. The helper mutates this in place. */
+export interface NonStreamLoopState {
+  workingMessages: Message[]
+  aggregated: ChatUsage
+  iterations: number
+  lastStopReason: string | null
+}
+
+export function createNonStreamLoopState(messages: readonly Message[]): NonStreamLoopState {
+  return {
+    workingMessages: [...messages],
+    aggregated: {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    },
+    iterations: 0,
+    lastStopReason: null,
+  }
+}
+
+/**
+ * Per-iteration outcome the orchestrator branches on. `assistantText`
+ * is `collectText(response.content)` — the schema variant feeds it
+ * through `parseGenerated`; the plain variant returns it as-is.
+ */
+export type NonStreamIterationOutcome =
+  | { kind: 'continue' }
+  | { kind: 'stop'; assistantText: string; stopReason: string }
+  | { kind: 'max_iterations'; assistantText: string }
+  | { kind: 'suspended'; pendingToolCalls: ToolUseBlock[] }
+
+export interface NonStreamIterationArgs {
+  state: NonStreamLoopState
+  toolMap: Map<string, Tool>
+  maxIterations: number
+  client: Anthropic
+  /**
+   * Built per iteration because `workingMessages` grows each round.
+   * Schema variant's closure adds `output_config.format: json_schema`
+   * after the driver's base `buildParams` runs. Caller is responsible
+   * for the `injectToolsAndMCP` step.
+   */
+  buildParams: (msgs: readonly Message[]) => Anthropic.MessageCreateParamsNonStreaming
+  options: RunWithToolsOptions
+  /**
+   * Human-in-the-loop gate. Pass `options.shouldSuspend` to enable;
+   * pass `undefined` to disable (schema callers don't support
+   * suspension).
+   */
+  suspendCheck: NonNullable<RunWithToolsOptions['shouldSuspend']> | undefined
+}
+
+/**
+ * One round-trip of the Anthropic agentic loop. Routes through the
+ * beta surface when MCP servers or compaction are in play; otherwise
+ * stays on the stable `client.messages.create`. Returns a
+ * discriminated outcome the orchestrator branches on; `state` is
+ * mutated in place.
+ */
+export async function runAnthropicNonStreamIteration(
+  args: NonStreamIterationArgs,
+): Promise<NonStreamIterationOutcome> {
+  const { state, toolMap, maxIterations, client, buildParams, options, suspendCheck } = args
+  checkAborted(options.signal)
+  const params = buildParams(state.workingMessages)
+
+  // Route via beta when MCP servers OR compaction are in play.
+  const response: Anthropic.Message = needsBetaRouting(params)
+    ? ((await client.beta.messages.create(
+        params as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming,
+        reqOpts(options),
+      )) as unknown as Anthropic.Message)
+    : await client.messages.create(params, reqOpts(options))
+  addAnthropicUsage(state.aggregated, response.usage)
+  state.lastStopReason = response.stop_reason ?? null
+
+  // Append the assistant turn verbatim from the SDK shape so tool_use
+  // blocks survive to the next request unchanged.
+  state.workingMessages.push({
+    role: 'assistant',
+    content: fromAnthropicContent(response.content),
+  })
+
+  const assistantText = collectText(response.content)
+
+  if (response.stop_reason !== 'tool_use') {
+    return {
+      kind: 'stop',
+      assistantText,
+      stopReason: state.lastStopReason ?? 'end_turn',
+    }
+  }
+
+  // Execute every tool_use block; all results land in one user turn
+  // per the SDK contract.
+  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 (suspendCheck) {
+      const frameworkCall: ToolUseBlock = {
+        type: 'tool_use',
+        id: block.id,
+        name: block.name,
+        input: block.input as Record<string, unknown>,
+      }
+      if (await suspendCheck(frameworkCall, options.context)) {
+        return {
+          kind: 'suspended',
+          pendingToolCalls: toolUseBlocks.slice(i).map((b) => ({
+            type: 'tool_use',
+            id: b.id,
+            name: b.name,
+            input: b.input as Record<string, unknown>,
+          })),
+        }
+      }
+    }
+    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)
+  }
+  state.workingMessages.push({ role: 'user', content: resultBlocks })
+
+  state.iterations++
+  if (state.iterations >= maxIterations) {
+    return { kind: 'max_iterations', assistantText }
+  }
+  return { kind: 'continue' }
+}

package/src/drivers/anthropic/index.ts

@@ -0,0 +1 @@
+export { AnthropicBrainDriver } from './anthropic_brain_driver.ts'

package/src/{providers/deepseek_provider.ts → drivers/deepseek/deepseek_brain_driver.ts}

@@ -1,5 +1,5 @@
 /**
- * `DeepSeekProvider` — `OpenAICompatProvider` pointed at DeepSeek's
+ * `DeepSeekBrainDriver` — `OpenAICompatBrainDriver` pointed at DeepSeek's
  * OpenAI-compatible `/v1/chat/completions` endpoint.
  *
  * Inherits the OpenAI-compat overrides (strip `reasoning_effort`,
@@ -18,9 +18,9 @@
  */
 
 import type OpenAI from 'openai'
-import { BrainError } from '../brain_error.ts'
-import type { DeepSeekProviderConfig } from '../brain_config.ts'
-import type { ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
+import { BrainError } from '../../brain_error.ts'
+import type { DeepSeekProviderConfig } from '../../brain_config.ts'
+import type { ResolveMcpToolsOptions } from '../../mcp/resolve_mcp_tools.ts'
 import type {
   AudioSource,
   ChatUsage,
@@ -28,8 +28,8 @@ import type {
   EmbedResult,
   TranscribeOptions,
   TranscribeResult,
-} from '../types.ts'
-import { OpenAICompatProvider } from './openai_compat_provider.ts'
+} from '../../types.ts'
+import { OpenAICompatBrainDriver } from '../openai_compat/openai_compat_brain_driver.ts'
 
 const DEFAULT_DEEPSEEK_MODEL = 'deepseek-chat'
 const DEFAULT_DEEPSEEK_BASE_URL = 'https://api.deepseek.com/v1'
@@ -44,7 +44,7 @@ export interface DeepSeekProviderOptions {
   mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
 }
 
-export class DeepSeekProvider extends OpenAICompatProvider {
+export class DeepSeekBrainDriver extends OpenAICompatBrainDriver {
   constructor(
     name: string,
     config: DeepSeekProviderConfig,
@@ -67,7 +67,7 @@ export class DeepSeekProvider extends OpenAICompatProvider {
 
   /**
    * DeepSeek doesn't expose an audio transcription endpoint.
-   * Override the inherited `transcribe` (from OpenAIProvider) to
+   * Override the inherited `transcribe` (from OpenAIBrainDriver) to
    * throw clearly rather than 404 at the wire.
    */
   override async transcribe(
@@ -75,7 +75,7 @@ export class DeepSeekProvider extends OpenAICompatProvider {
     _options?: TranscribeOptions,
   ): Promise<TranscribeResult<OpenAI.Audio.TranscriptionCreateResponse>> {
     throw new BrainError(
-      "DeepSeekProvider.transcribe: DeepSeek's API does not expose audio transcription. Route transcribe calls to a provider with native support — OpenAI / Ollama / Gemini.",
+      "DeepSeekBrainDriver.transcribe: DeepSeek's API does not expose audio transcription. Route transcribe calls to a provider with native support — OpenAI / Ollama / Gemini.",
       { context: { provider: this.name } },
     )
   }
@@ -91,7 +91,7 @@ export class DeepSeekProvider extends OpenAICompatProvider {
     _options?: EmbedOptions,
   ): Promise<EmbedResult<OpenAI.CreateEmbeddingResponse>> {
     throw new BrainError(
-      `DeepSeekProvider.embed: DeepSeek's API does not expose embeddings. Route embed calls to a provider with native support — OpenAI / Gemini / Ollama.`,
+      `DeepSeekBrainDriver.embed: DeepSeek's API does not expose embeddings. Route embed calls to a provider with native support — OpenAI / Gemini / Ollama.`,
       { context: { provider: this.name } },
     )
   }

package/src/drivers/deepseek/index.ts

@@ -0,0 +1 @@
+export { DeepSeekBrainDriver } from './deepseek_brain_driver.ts'