@strav/brain 1.0.0-alpha.10 → 1.0.0-alpha.12

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.10",
-  "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching. Anthropic provider in V1; OpenAI / Gemini / DeepSeek follow.",
+  "version": "1.0.0-alpha.12",
+  "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching, tools / agents / MCP. Anthropic + OpenAI providers; Gemini / DeepSeek follow.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./mcp": "./src/mcp/index.ts"
   },
   "files": [
     "src",
@@ -19,8 +20,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.10",
-    "@anthropic-ai/sdk": "^0.100.0"
+    "@anthropic-ai/sdk": "^0.100.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@strav/kernel": "1.0.0-alpha.12",
+    "openai": "^6.0.0"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/brain_config.ts

@@ -34,7 +34,22 @@ export interface AnthropicProviderConfig {
   betas?: readonly string[]
 }
 
-export type ProviderConfig = AnthropicProviderConfig // | OpenAIProviderConfig | … (later slices)
+/** OpenAI-specific driver config. */
+export interface OpenAIProviderConfig {
+  driver: 'openai'
+  /** API key. Required. Most apps source from `env('OPENAI_API_KEY')`. */
+  apiKey: string
+  /** Optional override of the SDK's base URL — useful for proxies, Azure OpenAI, or test doubles. */
+  baseUrl?: string
+  /** Optional organization id. */
+  organization?: string
+  /** Default model when neither `options.model` nor `options.tier` is passed. Defaults to `gpt-5`. */
+  defaultModel?: string
+  /** Default `max_tokens` for `chat()` calls that don't specify one. */
+  defaultMaxTokens?: number
+}
+
+export type ProviderConfig = AnthropicProviderConfig | OpenAIProviderConfig // | GoogleProviderConfig | DeepSeekProviderConfig (later slices)
 
 /** Cache-shape defaults applied when `ChatOptions.cache` is omitted. */
 export interface BrainCacheConfig {

package/src/brain_provider.ts

@@ -28,6 +28,7 @@ import { type Application, ConfigError, ConfigRepository, ServiceProvider } from
 import { BrainManager } from './brain_manager.ts'
 import type { BrainConfigShape, ProviderConfig } from './brain_config.ts'
 import { AnthropicProvider } from './providers/anthropic_provider.ts'
+import { OpenAIProvider } from './providers/openai_provider.ts'
 import type { Provider } from './provider.ts'
 
 export class BrainProvider extends ServiceProvider {
@@ -93,9 +94,21 @@ function buildProvider(name: string, config: ProviderConfig): Provider {
         )
       }
       return new AnthropicProvider(name, config)
-    default:
+    case 'openai':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openai provider "${name}" is missing apiKey. Source from env('OPENAI_API_KEY').`,
+        )
+      }
+      return new OpenAIProvider(name, config)
+    default: {
+      const exhaustiveCheck: never = config
       throw new ConfigError(
-        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic.`,
+        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic, openai.`,
       )
+      // (unreachable — kept for the exhaustive check to fire when a new driver lands)
+      // biome-ignore lint/correctness/noUnreachable: kept for the exhaustive-check above
+      return exhaustiveCheck
+    }
   }
 }

package/src/index.ts

@@ -16,6 +16,7 @@ export {
   type BrainConfigShape,
   DEFAULT_MODEL,
   DEFAULT_TIERS,
+  type OpenAIProviderConfig,
   type ProviderConfig,
 } from './brain_config.ts'
 export { BrainError } from './brain_error.ts'
@@ -28,6 +29,7 @@ export { BrainProvider } from './brain_provider.ts'
 export { defineTool, type DefineToolSpec } from './define_tool.ts'
 export type { MCPServer, MCPServerToolConfig } from './mcp_server.ts'
 export { AnthropicProvider } from './providers/anthropic_provider.ts'
+export { OpenAIProvider } from './providers/openai_provider.ts'
 export type { Provider, RunWithToolsOptions } from './provider.ts'
 export { Thread, type ThreadOptions, type ThreadState } from './thread.ts'
 export type { Tool, ToolContext } from './tool.ts'

package/src/mcp/client.ts

@@ -0,0 +1,157 @@
+/**
+ * `MCPClient` — local MCP client for providers that lack server-side
+ * MCP support (OpenAI, Gemini, DeepSeek, …).
+ *
+ * Wraps the official `@modelcontextprotocol/sdk` client. Connects to a
+ * single MCP server over Streamable HTTP, lists its tools, and invokes
+ * them. The agentic loop sees these as ordinary `Tool`s — translation
+ * happens in `resolveMcpTools`.
+ *
+ * Lifecycle:
+ *
+ *   const client = new MCPClient(serverConfig)
+ *   await client.connect()
+ *   const tools = await client.listTools()
+ *   const result = await client.callTool('name', {...})
+ *   await client.close()
+ *
+ * Authentication:
+ *   `MCPServer.authorizationToken` is forwarded as
+ *   `Authorization: Bearer <token>`. OAuth-flow servers need
+ *   out-of-band token exchange — same constraint as the server-side
+ *   path. Full OAuth handshake is a later slice.
+ *
+ * Transport:
+ *   V1 only does Streamable HTTP — the current MCP transport. Legacy
+ *   SSE-only endpoints aren't supported; if a server URL ends with
+ *   `/sse` and only speaks the legacy protocol, the connection will
+ *   fail and apps should run against a Streamable-HTTP endpoint
+ *   instead.
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { BrainError } from '../brain_error.ts'
+import type { MCPServer } from '../mcp_server.ts'
+
+/** Result of a single MCP tool invocation, as returned by `tools/call`. */
+export interface MCPCallToolResult {
+  /** Stringified content — text blocks concatenated; image / resource blocks JSON-serialized. */
+  content: string
+  /** `true` when the MCP server reports the tool execution failed. */
+  isError: boolean
+}
+
+/** Tool descriptor surfaced by `tools/list`. */
+export interface MCPToolDescriptor {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+export interface MCPClientOptions {
+  /** Override the transport used to dial the server. Tests inject a mock here. */
+  client?: Client
+}
+
+export class MCPClient {
+  readonly server: MCPServer
+  private readonly _client: Client
+  private _connected = false
+
+  constructor(server: MCPServer, options: MCPClientOptions = {}) {
+    this.server = server
+    this._client =
+      options.client ??
+      new Client(
+        { name: `@strav/brain:${server.name}`, version: '1.0.0' },
+        { capabilities: {} },
+      )
+  }
+
+  async connect(): Promise<void> {
+    if (this._connected) return
+    const transport = this._buildTransport()
+    try {
+      await this._client.connect(transport)
+      this._connected = true
+    } catch (cause) {
+      throw new BrainError(
+        `MCPClient(${this.server.name}): failed to connect to ${this.server.url}.`,
+        { context: { server: this.server.name, url: this.server.url }, cause },
+      )
+    }
+  }
+
+  async listTools(): Promise<MCPToolDescriptor[]> {
+    await this.connect()
+    let response: Awaited<ReturnType<Client['listTools']>>
+    try {
+      response = await this._client.listTools()
+    } catch (cause) {
+      throw new BrainError(
+        `MCPClient(${this.server.name}): tools/list failed.`,
+        { context: { server: this.server.name }, cause },
+      )
+    }
+    return response.tools.map((t) => ({
+      name: t.name,
+      description: t.description ?? '',
+      inputSchema: (t.inputSchema ?? { type: 'object' }) as Record<string, unknown>,
+    }))
+  }
+
+  async callTool(name: string, input: unknown): Promise<MCPCallToolResult> {
+    await this.connect()
+    let response: Awaited<ReturnType<Client['callTool']>>
+    try {
+      response = await this._client.callTool({
+        name,
+        arguments: (input ?? {}) as Record<string, unknown>,
+      })
+    } catch (cause) {
+      throw new BrainError(
+        `MCPClient(${this.server.name}): tools/call ${name} failed.`,
+        { context: { server: this.server.name, tool: name }, cause },
+      )
+    }
+    return {
+      content: flattenContent(response.content),
+      isError: Boolean(response.isError),
+    }
+  }
+
+  async close(): Promise<void> {
+    if (!this._connected) return
+    try {
+      await this._client.close()
+    } finally {
+      this._connected = false
+    }
+  }
+
+  private _buildTransport(): StreamableHTTPClientTransport {
+    const headers: Record<string, string> = {}
+    if (this.server.authorizationToken !== undefined) {
+      headers.Authorization = `Bearer ${this.server.authorizationToken}`
+    }
+    return new StreamableHTTPClientTransport(new URL(this.server.url), {
+      requestInit: { headers },
+    })
+  }
+}
+
+function flattenContent(
+  content: Awaited<ReturnType<Client['callTool']>>['content'],
+): string {
+  if (!Array.isArray(content)) return ''
+  const parts: string[] = []
+  for (const block of content) {
+    if (block.type === 'text') {
+      parts.push(block.text)
+    } else {
+      parts.push(JSON.stringify(block))
+    }
+  }
+  return parts.join('')
+}

package/src/mcp/index.ts

@@ -0,0 +1,16 @@
+// Public API of `@strav/brain/mcp` — local MCP client for providers
+// without server-side MCP support (OpenAI, Gemini, DeepSeek). The
+// Anthropic provider continues to use server-side MCP via the
+// top-level `MCPServer` config; nothing here is needed for that path.
+
+export {
+  MCPClient,
+  type MCPCallToolResult,
+  type MCPClientOptions,
+  type MCPToolDescriptor,
+} from './client.ts'
+export {
+  resolveMcpTools,
+  type ResolveMcpToolsOptions,
+  type ResolvedMcpTools,
+} from './resolve_mcp_tools.ts'

package/src/mcp/resolve_mcp_tools.ts

@@ -0,0 +1,86 @@
+/**
+ * `resolveMcpTools` — connects to each `MCPServer`, discovers its
+ * tools, and surfaces them as framework `Tool`s the standard agentic
+ * loop already knows how to invoke.
+ *
+ * Honors the per-server config in `MCPServer.tools`:
+ *   - `enabled: false` → server is skipped entirely.
+ *   - `allowedTools` → only those tool names are exposed.
+ *
+ * Naming: discovered tools are namespaced as `<server>__<tool>` to
+ * keep names unique when multiple servers expose overlapping names.
+ * The `Tool.execute` then routes back to the correct server. The
+ * underscore separator (not `.` or `/`) is chosen because OpenAI's
+ * tool-name regex rejects `.` and `/`.
+ *
+ * Lifecycle: this helper returns `{ tools, close }`. `close` runs all
+ * client `close()` calls in parallel — providers must call it in a
+ * `finally` to avoid leaking transports.
+ */
+
+import type { MCPServer } from '../mcp_server.ts'
+import type { Tool, ToolContext } from '../tool.ts'
+import { MCPClient } from './client.ts'
+
+export interface ResolvedMcpTools {
+  tools: Tool[]
+  close(): Promise<void>
+}
+
+export interface ResolveMcpToolsOptions {
+  /** Override the client factory — tests inject mock clients per server here. */
+  clientFactory?(server: MCPServer): MCPClient
+}
+
+const NAME_SEPARATOR = '__'
+
+export async function resolveMcpTools(
+  servers: readonly MCPServer[],
+  options: ResolveMcpToolsOptions = {},
+): Promise<ResolvedMcpTools> {
+  const clients: MCPClient[] = []
+  const tools: Tool[] = []
+
+  for (const server of servers) {
+    if (server.tools?.enabled === false) continue
+    const client = options.clientFactory
+      ? options.clientFactory(server)
+      : new MCPClient(server)
+    clients.push(client)
+
+    const allowed = server.tools?.allowedTools
+    const allowedSet = allowed ? new Set(allowed) : null
+
+    const descriptors = await client.listTools()
+    for (const descriptor of descriptors) {
+      if (allowedSet && !allowedSet.has(descriptor.name)) continue
+      tools.push(buildTool(server.name, client, descriptor))
+    }
+  }
+
+  return {
+    tools,
+    close: async () => {
+      await Promise.all(clients.map((c) => c.close()))
+    },
+  }
+}
+
+function buildTool(
+  serverName: string,
+  client: MCPClient,
+  descriptor: { name: string; description: string; inputSchema: Record<string, unknown> },
+): Tool {
+  return {
+    name: `${serverName}${NAME_SEPARATOR}${descriptor.name}`,
+    description: descriptor.description,
+    inputSchema: descriptor.inputSchema,
+    async execute(input: unknown, _ctx: ToolContext): Promise<string> {
+      const result = await client.callTool(descriptor.name, input)
+      if (result.isError) {
+        return `MCP tool error: ${result.content}`
+      }
+      return result.content
+    },
+  }
+}

package/src/providers/openai_provider.ts

@@ -0,0 +1,446 @@
+/**
+ * `OpenAIProvider` — implementation of `Provider` backed by the
+ * official `openai` SDK (chat completions API).
+ *
+ * Maps framework shapes to OpenAI's wire format:
+ *
+ *   - `system` becomes the first message with `role: 'system'`.
+ *     (OpenAI doesn't have a separate system field on chat
+ *     completions; o1/o3 reasoning models accept `developer` as
+ *     a synonym but `system` still works.)
+ *
+ *   - `Message` with string content → `{role, content: string}`.
+ *     `Message` with `ContentBlock[]`: text blocks concatenate into
+ *     a single content string; `ToolUseBlock`s on assistant turns
+ *     translate to `tool_calls`; `ToolResultBlock`s in user turns
+ *     each become their own `{role: 'tool', tool_call_id, content}`
+ *     message (OpenAI requires this layout, not a single user turn
+ *     with mixed content like Anthropic's).
+ *
+ *   - `Tool[]` → `[{type: 'function', function: {name, description,
+ *     parameters: tool.inputSchema}}]`. OpenAI wraps every tool in
+ *     a `function` namespace where Anthropic uses flat tool
+ *     definitions.
+ *
+ *   - `MCPServer[]` → resolved via the local MCP client
+ *     (`@strav/brain/mcp`). Each server is dialed, its tools are
+ *     discovered, and they're merged with locally-defined tools.
+ *     The agentic loop then treats them uniformly. Tool names are
+ *     namespaced `<server>__<tool>` to avoid collisions. Transports
+ *     are closed in a `finally` once the loop exits.
+ *
+ *   - `cache: true` is a no-op. OpenAI auto-caches; there's no
+ *     per-block cache_control to set. The framework flag is
+ *     accepted (so config that targets both providers still
+ *     works) but doesn't emit anything to the wire.
+ *
+ *   - `thinking: 'adaptive'` maps to `reasoning_effort: 'medium'`
+ *     on reasoning models (o1, o3, o5, etc.); `'disabled'` maps
+ *     to `reasoning_effort: 'minimal'`. Non-reasoning models
+ *     silently ignore the field.
+ *
+ *   - `effort` (when set) maps directly to `reasoning_effort`
+ *     when supported by the model.
+ *
+ *   - `countTokens` is NOT implemented — OpenAI has no dedicated
+ *     count endpoint. `BrainManager.countTokens` returns `null`
+ *     when the configured provider doesn't expose the method.
+ */
+
+import OpenAI from 'openai'
+import type { AgentResult } from '../agent_result.ts'
+import { BrainError } from '../brain_error.ts'
+import type { OpenAIProviderConfig } from '../brain_config.ts'
+import type { MCPServer } from '../mcp_server.ts'
+import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
+import type { Provider, RunWithToolsOptions } from '../provider.ts'
+import type { Tool } from '../tool.ts'
+import { ToolExecutionError } from '../tool_execution_error.ts'
+import type {
+  ChatOptions,
+  ChatResult,
+  ChatUsage,
+  ContentBlock,
+  Message,
+  StreamEvent,
+  SystemPrompt,
+  TextBlock,
+  ToolResultBlock,
+  ToolUseBlock,
+} from '../types.ts'
+
+const DEFAULT_OPENAI_MODEL = 'gpt-5'
+
+export interface OpenAIProviderOptions {
+  client?: OpenAI
+  /**
+   * Internal seam — tests inject a stub MCP client factory so MCP
+   * tool resolution doesn't dial the network. Real apps leave it
+   * unset; the provider uses the default `MCPClient`.
+   */
+  mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
+}
+
+export class OpenAIProvider implements Provider {
+  readonly name: string
+  private readonly client: OpenAI
+  private readonly defaultModel: string
+  private readonly defaultMaxTokens: number
+  private readonly mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
+
+  constructor(
+    name: string,
+    config: OpenAIProviderConfig,
+    options: OpenAIProviderOptions = {},
+  ) {
+    this.name = name
+    this.defaultModel = config.defaultModel ?? DEFAULT_OPENAI_MODEL
+    this.defaultMaxTokens = config.defaultMaxTokens ?? 4096
+    this.mcpClientFactory = options.mcpClientFactory
+    this.client =
+      options.client ??
+      new OpenAI({
+        apiKey: config.apiKey,
+        ...(config.baseUrl !== undefined ? { baseURL: config.baseUrl } : {}),
+        ...(config.organization !== undefined ? { organization: config.organization } : {}),
+      })
+  }
+
+  async chat(messages: readonly Message[], options: ChatOptions = {}): Promise<ChatResult> {
+    const params = this.buildParams(messages, options, [])
+    const response = await this.client.chat.completions.create(params)
+    return this.toChatResult(response)
+  }
+
+  async *stream(
+    messages: readonly Message[],
+    options: ChatOptions = {},
+  ): AsyncIterable<StreamEvent> {
+    const params: OpenAI.Chat.ChatCompletionCreateParamsStreaming = {
+      ...this.buildParams(messages, options, []),
+      stream: true,
+      stream_options: { include_usage: true },
+    }
+    const stream = await this.client.chat.completions.create(params)
+    let aggregatedUsage: OpenAI.CompletionUsage | undefined
+    let finishReason: string | null = null
+    for await (const chunk of stream) {
+      const delta = chunk.choices[0]?.delta?.content
+      if (typeof delta === 'string' && delta.length > 0) {
+        yield { type: 'text', delta }
+      }
+      if (chunk.choices[0]?.finish_reason) {
+        finishReason = chunk.choices[0].finish_reason
+      }
+      if (chunk.usage) aggregatedUsage = chunk.usage
+    }
+    yield {
+      type: 'stop',
+      stopReason: finishReason,
+      usage: toUsage(aggregatedUsage),
+    }
+  }
+
+  async runWithTools(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentResult> {
+    const mcpServers: readonly MCPServer[] = options.mcpServers ?? []
+    const resolved =
+      mcpServers.length > 0
+        ? await resolveMcpTools(mcpServers, {
+            ...(this.mcpClientFactory ? { clientFactory: this.mcpClientFactory } : {}),
+          })
+        : { tools: [] as Tool[], close: async () => {} }
+    try {
+      return await this._runLoop(messages, [...tools, ...resolved.tools], options)
+    } finally {
+      await resolved.close()
+    }
+  }
+
+  private async _runLoop(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions,
+  ): Promise<AgentResult> {
+    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
+
+    while (true) {
+      const params = this.buildParams(workingMessages, options, tools)
+      const response = await this.client.chat.completions.create(params)
+      addUsage(aggregated, response.usage)
+
+      const choice = response.choices[0]
+      if (!choice) {
+        throw new BrainError('OpenAIProvider: response had no choices.')
+      }
+      const assistantMessage = choice.message
+
+      // Append assistant turn to working messages so we send it back
+      // verbatim on the next round-trip.
+      workingMessages.push({
+        role: 'assistant',
+        content: fromOpenAIAssistantMessage(assistantMessage),
+      })
+
+      const toolCalls = assistantMessage.tool_calls ?? []
+      if (toolCalls.length === 0 || choice.finish_reason !== 'tool_calls') {
+        return {
+          text: assistantMessage.content ?? '',
+          messages: workingMessages,
+          iterations,
+          stopReason: choice.finish_reason ?? 'stop',
+          usage: aggregated,
+        }
+      }
+
+      const resultBlocks: ContentBlock[] = []
+      for (const call of toolCalls) {
+        if (call.type !== 'function') continue
+        const tool = toolMap.get(call.function.name)
+        if (!tool) {
+          throw new ToolExecutionError(
+            call.function.name,
+            call.id,
+            new Error(`Tool "${call.function.name}" is not registered.`),
+          )
+        }
+        let parsedInput: unknown
+        try {
+          parsedInput = call.function.arguments ? JSON.parse(call.function.arguments) : {}
+        } catch (err) {
+          throw new ToolExecutionError(
+            call.function.name,
+            call.id,
+            new Error(`Failed to parse tool input JSON: ${(err as Error).message}`),
+          )
+        }
+        let output: unknown
+        try {
+          output = await tool.execute(parsedInput, {
+            callId: call.id,
+            context: options.context ?? {},
+          })
+        } catch (cause) {
+          throw new ToolExecutionError(call.function.name, call.id, cause)
+        }
+        const resultBlock: ToolResultBlock = {
+          type: 'tool_result',
+          toolUseId: call.id,
+          content: typeof output === 'string' ? output : JSON.stringify(output),
+        }
+        resultBlocks.push(resultBlock)
+      }
+      workingMessages.push({ role: 'user', content: resultBlocks })
+
+      iterations++
+      if (iterations >= maxIterations) {
+        return {
+          text: assistantMessage.content ?? '',
+          messages: workingMessages,
+          iterations,
+          stopReason: 'max_iterations',
+          usage: aggregated,
+        }
+      }
+    }
+  }
+
+  // ─── Param translation ──────────────────────────────────────────────────
+
+  private buildParams(
+    messages: readonly Message[],
+    options: ChatOptions,
+    tools: readonly Tool[],
+  ): OpenAI.Chat.ChatCompletionCreateParamsNonStreaming {
+    const model = options.model ?? this.defaultModel
+    const params: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming = {
+      model,
+      max_completion_tokens: options.maxTokens ?? this.defaultMaxTokens,
+      messages: this.toMessages(options.system, messages),
+    }
+
+    if (tools.length > 0) {
+      params.tools = tools.map((t) => ({
+        type: 'function',
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.inputSchema as Record<string, unknown>,
+        },
+      }))
+    }
+
+    // Reasoning controls — only emitted when explicitly set so
+    // non-reasoning models don't get rejected.
+    if (options.effort !== undefined) {
+      params.reasoning_effort = options.effort as OpenAI.ReasoningEffort
+    } else if (options.thinking === 'adaptive') {
+      params.reasoning_effort = 'medium' as OpenAI.ReasoningEffort
+    } else if (options.thinking === 'disabled') {
+      params.reasoning_effort = 'minimal' as OpenAI.ReasoningEffort
+    }
+
+    // `cache` is a no-op on OpenAI — prompt caching is automatic.
+    // We accept the flag silently so apps that target both providers
+    // with the same options object don't have to special-case.
+
+    return params
+  }
+
+  private toMessages(
+    system: SystemPrompt | undefined,
+    messages: readonly Message[],
+  ): OpenAI.Chat.ChatCompletionMessageParam[] {
+    const out: OpenAI.Chat.ChatCompletionMessageParam[] = []
+    const systemText = systemPromptText(system)
+    if (systemText.length > 0) {
+      out.push({ role: 'system', content: systemText })
+    }
+    for (const message of messages) {
+      // User-role messages with tool results in their content fan
+      // out into one `tool`-role message per result — OpenAI's
+      // contract is "one tool_call_id per tool message," not a
+      // single user message carrying multiple results.
+      if (
+        message.role === 'user' &&
+        Array.isArray(message.content) &&
+        message.content.some((b) => b.type === 'tool_result')
+      ) {
+        const remainingText: string[] = []
+        for (const block of message.content) {
+          if (block.type === 'tool_result') {
+            out.push({
+              role: 'tool',
+              tool_call_id: block.toolUseId,
+              content: typeof block.content === 'string'
+                ? block.content
+                : block.content.map((t) => t.text).join(''),
+            })
+          } else if (block.type === 'text') {
+            remainingText.push(block.text)
+          }
+        }
+        if (remainingText.length > 0) {
+          out.push({ role: 'user', content: remainingText.join('') })
+        }
+        continue
+      }
+      out.push(toOpenAIMessage(message))
+    }
+    return out
+  }
+
+  private toChatResult(
+    response: OpenAI.Chat.ChatCompletion,
+  ): ChatResult<OpenAI.Chat.ChatCompletion> {
+    const choice = response.choices[0]
+    return {
+      text: choice?.message?.content ?? '',
+      model: response.model,
+      stopReason: choice?.finish_reason ?? null,
+      usage: toUsage(response.usage),
+      raw: response,
+    }
+  }
+}
+
+// ─── Shape converters ─────────────────────────────────────────────────────
+
+function systemPromptText(system: SystemPrompt | undefined): string {
+  if (system === undefined) return ''
+  if (typeof system === 'string') return system
+  if (Array.isArray(system)) return system.map((b) => b.text).join('\n')
+  return system.text
+}
+
+function toOpenAIMessage(message: Message): OpenAI.Chat.ChatCompletionMessageParam {
+  if (typeof message.content === 'string') {
+    return { role: message.role, content: message.content } as OpenAI.Chat.ChatCompletionMessageParam
+  }
+
+  // Assistant turns may contain text + tool_use blocks; we need to
+  // split tool_use blocks into the `tool_calls` field and put the
+  // remaining text into `content`.
+  if (message.role === 'assistant') {
+    const text = message.content
+      .filter((b): b is TextBlock => b.type === 'text')
+      .map((b) => b.text)
+      .join('')
+    const toolUses = message.content.filter((b): b is ToolUseBlock => b.type === 'tool_use')
+    const param: OpenAI.Chat.ChatCompletionAssistantMessageParam = { role: 'assistant' }
+    if (text.length > 0) param.content = text
+    if (toolUses.length > 0) {
+      param.tool_calls = toolUses.map((b) => ({
+        id: b.id,
+        type: 'function',
+        function: {
+          name: b.name,
+          arguments: JSON.stringify(b.input ?? {}),
+        },
+      }))
+    }
+    return param
+  }
+
+  // User-role multi-block content — flatten text. MCP blocks (which
+  // are read-only and Anthropic-specific) are silently dropped.
+  const text = message.content
+    .filter((b): b is TextBlock => b.type === 'text')
+    .map((b) => b.text)
+    .join('')
+  return { role: 'user', content: text }
+}
+
+function fromOpenAIAssistantMessage(
+  msg: OpenAI.Chat.ChatCompletionMessage,
+): string | ContentBlock[] {
+  const blocks: ContentBlock[] = []
+  if (msg.content) blocks.push({ type: 'text', text: msg.content })
+  if (msg.tool_calls) {
+    for (const call of msg.tool_calls) {
+      if (call.type !== 'function') continue
+      let parsedInput: unknown = {}
+      try {
+        parsedInput = call.function.arguments ? JSON.parse(call.function.arguments) : {}
+      } catch {
+        parsedInput = call.function.arguments ?? {}
+      }
+      blocks.push({
+        type: 'tool_use',
+        id: call.id,
+        name: call.function.name,
+        input: parsedInput,
+      } satisfies ToolUseBlock)
+    }
+  }
+  if (blocks.length === 1 && blocks[0]?.type === 'text') return blocks[0].text
+  return blocks
+}
+
+function toUsage(u: OpenAI.CompletionUsage | undefined): ChatUsage {
+  return {
+    inputTokens: u?.prompt_tokens ?? 0,
+    outputTokens: u?.completion_tokens ?? 0,
+    cacheReadTokens: u?.prompt_tokens_details?.cached_tokens ?? 0,
+    cacheCreationTokens: 0,
+  }
+}
+
+function addUsage(acc: ChatUsage, u: OpenAI.CompletionUsage | undefined): void {
+  if (!u) return
+  acc.inputTokens += u.prompt_tokens
+  acc.outputTokens += u.completion_tokens
+  acc.cacheReadTokens += u.prompt_tokens_details?.cached_tokens ?? 0
+}