@strav/brain 1.0.0-alpha.9 → 1.0.1

package/src/drivers/openrouter/index.ts

@@ -0,0 +1 @@
+export { OpenRouterBrainDriver } from './openrouter_brain_driver.ts'

package/src/drivers/openrouter/openrouter_brain_driver.ts

@@ -0,0 +1,137 @@
+/**
+ * `OpenRouterBrainDriver` — `OpenAICompatBrainDriver` pointed at
+ * OpenRouter's OpenAI-compatible endpoint at
+ * `https://openrouter.ai/api/v1`.
+ *
+ * OpenRouter multiplexes 300+ hosted models (Anthropic, OpenAI,
+ * Google, Meta, Mistral, DeepSeek, Qwen, ...) behind one
+ * Chat-Completions-shaped API. The driver does NOT try to predict
+ * which model supports what — capabilities vary per slug. The
+ * supported approach is:
+ *
+ *   - Pin an explicit model slug per call (e.g.
+ *     `anthropic/claude-sonnet-4`, `meta-llama/llama-3.3-70b`).
+ *   - If the chosen model doesn't support a primitive (tools,
+ *     JSON mode, schema-forcing), the upstream OpenRouter error
+ *     bubbles up as a `BrainError` from the inherited helpers.
+ *   - Consult `https://openrouter.ai/api/v1/models` and filter on
+ *     the `supported_parameters` field to pick a model that
+ *     handles the feature you need.
+ *
+ * Two OpenRouter-specific niceties:
+ *
+ *   - Optional `appUrl` (→ `HTTP-Referer`) and `appTitle`
+ *     (→ `X-Title`) forwarded as default headers on every request.
+ *     OpenRouter uses these to attribute traffic on their public
+ *     leaderboard / rankings.
+ *
+ *   - No `defaultModel` default — OpenRouter has no canonical pick.
+ *     Apps must set one, or pass `options.model` per call. The
+ *     inherited OpenAI default `gpt-5` would silently route through
+ *     OpenAI's slug namespace and surprise users.
+ *
+ * Inherits all OpenAI-compat overrides: `buildParams` strips
+ * `reasoning_effort` (re-add it in a subclass / per-call `extraBody`
+ * for models that take it), `generate` uses `json_object`-mode +
+ * schema-in-system-prompt, `runWithToolsAndSchema` /
+ * `streamWithToolsAndSchema` use the tool-forcing pattern.
+ *
+ * `embed` / `transcribe` are not exposed via OpenRouter — replaced
+ * with explicit `BrainError`s.
+ */
+
+import OpenAI from 'openai'
+import type { OpenRouterProviderConfig } from '../../brain_config.ts'
+import { BrainError } from '../../brain_error.ts'
+import type { ResolveMcpToolsOptions } from '../../mcp/resolve_mcp_tools.ts'
+import type {
+  AudioSource,
+  EmbedOptions,
+  EmbedResult,
+  TranscribeOptions,
+  TranscribeResult,
+} from '../../types.ts'
+import { OpenAICompatBrainDriver } from '../openai_compat/openai_compat_brain_driver.ts'
+
+const DEFAULT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1'
+/**
+ * Fallback when neither `config.defaultModel` nor a per-call
+ * `options.model` is supplied. Picked as a broad-purpose,
+ * tool-capable, well-priced default; apps that want something else
+ * just pass `defaultModel`.
+ */
+const DEFAULT_OPENROUTER_MODEL = 'openai/gpt-4o-mini'
+
+export interface OpenRouterProviderOptions {
+  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 OpenRouterBrainDriver extends OpenAICompatBrainDriver {
+  constructor(
+    name: string,
+    config: OpenRouterProviderConfig,
+    options: OpenRouterProviderOptions = {},
+  ) {
+    const baseURL = config.baseUrl ?? DEFAULT_OPENROUTER_BASE_URL
+    const defaultHeaders = buildOpenRouterHeaders(config)
+    // Construct the OpenAI client locally so we can carry OpenRouter's
+    // attribution headers (HTTP-Referer / X-Title). The base
+    // OpenAIBrainDriver only exposes apiKey / baseUrl / organization,
+    // so we hand a fully-built client through `options.client`.
+    const client =
+      options.client ??
+      new OpenAI({
+        apiKey: config.apiKey,
+        baseURL,
+        ...(defaultHeaders ? { defaultHeaders } : {}),
+      })
+    super(
+      name,
+      {
+        driver: 'openai',
+        apiKey: config.apiKey,
+        baseUrl: baseURL,
+        defaultModel: config.defaultModel ?? DEFAULT_OPENROUTER_MODEL,
+        ...(config.defaultMaxTokens !== undefined
+          ? { defaultMaxTokens: config.defaultMaxTokens }
+          : {}),
+      },
+      { ...options, client },
+    )
+  }
+
+  override async embed(
+    _texts: readonly string[],
+    _options?: EmbedOptions,
+  ): Promise<EmbedResult<OpenAI.CreateEmbeddingResponse>> {
+    throw new BrainError(
+      `OpenRouterBrainDriver.embed: OpenRouter's API does not expose embeddings. Route embed calls to a provider with native support — OpenAI / Gemini / Ollama.`,
+      { context: { provider: this.name } },
+    )
+  }
+
+  override async transcribe(
+    _audio: AudioSource,
+    _options?: TranscribeOptions,
+  ): Promise<TranscribeResult<OpenAI.Audio.TranscriptionCreateResponse>> {
+    throw new BrainError(
+      "OpenRouterBrainDriver.transcribe: OpenRouter's API does not expose audio transcription. Route transcribe calls to a provider with native support — OpenAI / Ollama / Gemini.",
+      { context: { provider: this.name } },
+    )
+  }
+}
+
+function buildOpenRouterHeaders(
+  config: OpenRouterProviderConfig,
+): Record<string, string> | undefined {
+  const headers: Record<string, string> = {}
+  if (config.appUrl !== undefined) headers['HTTP-Referer'] = config.appUrl
+  if (config.appTitle !== undefined) headers['X-Title'] = config.appTitle
+  return Object.keys(headers).length > 0 ? headers : undefined
+}

package/src/drivers/qwen/index.ts

@@ -0,0 +1 @@
+export { QwenBrainDriver } from './qwen_brain_driver.ts'

package/src/drivers/qwen/qwen_brain_driver.ts

@@ -0,0 +1,103 @@
+/**
+ * `QwenBrainDriver` — `OpenAICompatBrainDriver` pointed at Alibaba
+ * DashScope's OpenAI-compatible `/compatible-mode/v1` endpoint.
+ *
+ * Why ship Qwen: deep coverage of Chinese + SEA languages, with the
+ * `qwen-plus` / `qwen-max` line punching at the frontier on those
+ * locales. Fits Strav's SEA-first positioning.
+ *
+ * Inherits the OpenAI-compat overrides (strip `reasoning_effort`,
+ * `json_object`-mode generate with schema-in-system-prompt,
+ * tool-forcing pattern for combined tools + schema) from the base
+ * class. Only adds:
+ *
+ *   - Constructor with DashScope defaults — base URL
+ *     `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` (the
+ *     Singapore endpoint), default model `qwen-plus`.
+ *
+ *   - `mapUsage` override — Qwen reports prompt-cache hits on
+ *     OpenAI's standard `prompt_tokens_details.cached_tokens`
+ *     field; the inherited mapping is already correct. Kept the
+ *     hook here for vendor-specific extension fields if they
+ *     surface later.
+ *
+ * `embed` / `transcribe` are not implemented for V1 — DashScope
+ * exposes both via separate endpoints, but the framework's seam
+ * is per-driver and we'd rather route those calls to a provider
+ * with first-class support. Override the inherited stubs to throw
+ * with a clear message instead of letting the SDK 404.
+ */
+
+import type OpenAI from 'openai'
+import type { QwenProviderConfig } from '../../brain_config.ts'
+import { BrainError } from '../../brain_error.ts'
+import type { ResolveMcpToolsOptions } from '../../mcp/resolve_mcp_tools.ts'
+import type {
+  AudioSource,
+  EmbedOptions,
+  EmbedResult,
+  TranscribeOptions,
+  TranscribeResult,
+} from '../../types.ts'
+import { OpenAICompatBrainDriver } from '../openai_compat/openai_compat_brain_driver.ts'
+
+const DEFAULT_QWEN_MODEL = 'qwen-plus'
+const DEFAULT_QWEN_BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
+
+export interface QwenProviderOptions {
+  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 QwenBrainDriver extends OpenAICompatBrainDriver {
+  constructor(name: string, config: QwenProviderConfig, options: QwenProviderOptions = {}) {
+    super(
+      name,
+      {
+        driver: 'openai',
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl ?? DEFAULT_QWEN_BASE_URL,
+        defaultModel: config.defaultModel ?? DEFAULT_QWEN_MODEL,
+        ...(config.defaultMaxTokens !== undefined
+          ? { defaultMaxTokens: config.defaultMaxTokens }
+          : {}),
+      },
+      options,
+    )
+  }
+
+  /**
+   * DashScope's compatibility endpoint does not expose embeddings
+   * via `/compatible-mode/v1/embeddings`. Override the inherited
+   * `embed` to throw clearly rather than 404 at the wire.
+   */
+  override async embed(
+    _texts: readonly string[],
+    _options?: EmbedOptions,
+  ): Promise<EmbedResult<OpenAI.CreateEmbeddingResponse>> {
+    throw new BrainError(
+      `QwenBrainDriver.embed: Qwen's OpenAI-compatibility endpoint does not expose embeddings. Route embed calls to a provider with native support — OpenAI / Gemini / Ollama.`,
+      { context: { provider: this.name } },
+    )
+  }
+
+  /**
+   * DashScope's compatibility endpoint does not expose audio
+   * transcription. Override the inherited `transcribe` to throw
+   * clearly.
+   */
+  override async transcribe(
+    _audio: AudioSource,
+    _options?: TranscribeOptions,
+  ): Promise<TranscribeResult<OpenAI.Audio.TranscriptionCreateResponse>> {
+    throw new BrainError(
+      "QwenBrainDriver.transcribe: Qwen's OpenAI-compatibility endpoint does not expose audio transcription. Route transcribe calls to a provider with native support — OpenAI / Ollama / Gemini.",
+      { context: { provider: this.name } },
+    )
+  }
+}

package/src/index.ts

@@ -1,46 +1,110 @@
 // Public API of @strav/brain.
 //
-// V1: Provider interface + AnthropicProvider, BrainManager, Thread,
-// BrainProvider service-wiring, prompt caching.
-// V2 (this slice): tools + agents — defineTool, Agent base + AgentRunner,
-// BrainManager.runTools / .agent(Class), Provider.runWithTools.
-// Still deferred: MCP, embeddings, streaming agent loops, server-side
-// tools, structured outputs, other providers.
+// Shipped:
+//   - `BrainDriver` contract + concrete drivers — Anthropic, OpenAI
+//     (Chat + Responses), Gemini, DeepSeek, Ollama, Qwen, MiniMax,
+//     OpenRouter, openai-compat.
+//   - `BrainManager` + `Thread` (persisted history, compaction) + the
+//     `BrainProvider` service wiring + prompt-cache plumbing.
+//   - Tools — `defineTool`, `Agent` base + `AgentRunner`,
+//     `runWithTools` + `streamWithTools` (agentic + streaming loops).
+//   - Structured outputs — `generate`, `runWithToolsAndSchema`,
+//     `streamWithToolsAndSchema` (JSON-Schema constrained replies).
+//   - MCP — server-side (Anthropic) + local client (`@strav/brain/mcp`).
+//   - Embeddings (`embed`), audio transcription (`transcribe`),
+//     human-in-the-loop suspend/resume.
 
 export { Agent } from './agent.ts'
+export type { AgentGenerateResult } from './agent_generate_result.ts'
 export type { AgentResult } from './agent_result.ts'
-export { AgentRunner } from './agent_runner.ts'
+export {
+  type AgentRunMaybeSuspended,
+  AgentRunner,
+  type AgentRunResult,
+} from './agent_runner.ts'
+export type { AgentStreamEvent } from './agent_stream_event.ts'
 export {
   type AnthropicProviderConfig,
   type BrainCacheConfig,
   type BrainConfigShape,
   DEFAULT_MODEL,
   DEFAULT_TIERS,
+  type DeepSeekProviderConfig,
+  type GeminiProviderConfig,
+  type MiniMaxProviderConfig,
+  type OllamaProviderConfig,
+  type OpenAIProviderConfig,
+  type OpenAIResponsesProviderConfig,
+  type OpenRouterProviderConfig,
   type ProviderConfig,
+  type QwenProviderConfig,
 } from './brain_config.ts'
-export { BrainError } from './brain_error.ts'
+export type {
+  BrainDriver,
+  RunWithToolsOptions,
+  RunWithToolsOptionsWithSuspend,
+} from './brain_driver.ts'
+export {
+  BrainConfigError,
+  BrainError,
+  BrainProviderError,
+  BrainUsageError,
+  UnknownProviderError,
+} from './brain_error.ts'
 export {
   type AgentResolver,
   BrainManager,
   type BrainManagerOptions,
 } from './brain_manager.ts'
 export { BrainProvider } from './brain_provider.ts'
-export { defineTool, type DefineToolSpec } from './define_tool.ts'
-export { AnthropicProvider } from './providers/anthropic_provider.ts'
-export type { Provider, RunWithToolsOptions } from './provider.ts'
+export { type DefineToolSpec, defineTool } from './define_tool.ts'
+export { AnthropicBrainDriver } from './drivers/anthropic/anthropic_brain_driver.ts'
+export { DeepSeekBrainDriver } from './drivers/deepseek/deepseek_brain_driver.ts'
+export { GeminiBrainDriver } from './drivers/gemini/gemini_brain_driver.ts'
+export { MiniMaxBrainDriver } from './drivers/minimax/minimax_brain_driver.ts'
+export { OllamaBrainDriver } from './drivers/ollama/ollama_brain_driver.ts'
+export { OpenAIBrainDriver } from './drivers/openai/openai_brain_driver.ts'
+export { OpenAICompatBrainDriver } from './drivers/openai_compat/openai_compat_brain_driver.ts'
+export { OpenAIResponsesBrainDriver } from './drivers/openai_responses/openai_responses_brain_driver.ts'
+export { OpenRouterBrainDriver } from './drivers/openrouter/openrouter_brain_driver.ts'
+export { QwenBrainDriver } from './drivers/qwen/qwen_brain_driver.ts'
+export { type MCPClientFactory, MCPClientPool } from './mcp/pool.ts'
+export type { MCPServer, MCPServerToolConfig } from './mcp_server.ts'
+export type { OutputSchema } from './output_schema.ts'
+export {
+  appendResumeResults,
+  isSuspended,
+  type SuspendedRun,
+  type SuspendedState,
+  type ToolResultInput,
+} from './suspended_run.ts'
 export { Thread, type ThreadOptions, type ThreadState } from './thread.ts'
 export type { Tool, ToolContext } from './tool.ts'
 export { ToolExecutionError } from './tool_execution_error.ts'
 export type {
+  AudioBlock,
+  AudioSource,
   ChatOptions,
   ChatResult,
   ChatUsage,
+  CompactConfig,
+  CompactionBlock,
   ContentBlock,
+  DocumentBlock,
+  EmbedOptions,
+  EmbedResult,
+  GenerateResult,
+  ImageBlock,
+  MCPToolResultBlock,
+  MCPToolUseBlock,
   Message,
   ModelTier,
+  ServerTool,
   StreamEvent,
   SystemPrompt,
   TextBlock,
   ToolResultBlock,
   ToolUseBlock,
+  TranscribeOptions,
+  TranscribeResult,
 } from './types.ts'

package/src/mcp/client.ts

@@ -0,0 +1,243 @@
+/**
+ * `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` → static bearer; fine for
+ *     self-hosted servers where the app controls the token.
+ *   - `MCPServer.oauth` → drives the authorization-code-with-PKCE
+ *     flow against the server's OAuth endpoints. On
+ *     `connect()` against an un-authorized server,
+ *     `MCPAuthRequiredError` is thrown carrying the URL the user
+ *     should be redirected to. After the user authorizes and is
+ *     redirected back, the app's callback handler calls
+ *     `completeAuthorization(code)` to finish the exchange.
+ *   The two are mutually exclusive — passing both throws.
+ *
+ * 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 { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js'
+import { BrainError } from '../brain_error.ts'
+import type { MCPServer } from '../mcp_server.ts'
+import { MCPAuthRequiredError, StoreBackedOAuthProvider } from './oauth.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
+  /**
+   * In-flight connect promise — set on the first concurrent
+   * `connect()` and cleared on settle. Subsequent callers that
+   * race against the first one await the same promise instead of
+   * each kicking off their own transport handshake. Necessary for
+   * pooled clients: a fresh `borrow()` followed by parallel
+   * `listTools()` + `callTool()` calls both hit the same connect.
+   */
+  private _connecting: Promise<void> | undefined
+  private _transport: StreamableHTTPClientTransport | undefined
+  private _authProvider: StoreBackedOAuthProvider | undefined
+
+  constructor(server: MCPServer, options: MCPClientOptions = {}) {
+    if (server.authorizationToken !== undefined && server.oauth !== undefined) {
+      throw new BrainError(
+        `MCPClient(${server.name}): \`authorizationToken\` and \`oauth\` are mutually exclusive — set one.`,
+        { context: { server: server.name } },
+      )
+    }
+    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
+    if (this._connecting) return this._connecting
+    this._connecting = this._doConnect().finally(() => {
+      this._connecting = undefined
+    })
+    return this._connecting
+  }
+
+  private async _doConnect(): Promise<void> {
+    const transport = this._buildTransport()
+    this._transport = transport
+    try {
+      await this._client.connect(transport)
+      this._connected = true
+    } catch (cause) {
+      if (cause instanceof UnauthorizedError && this._authProvider?.capturedAuthorizationUrl) {
+        throw new MCPAuthRequiredError(
+          this.server.name,
+          this._authProvider.capturedAuthorizationUrl.toString(),
+        )
+      }
+      throw new BrainError(
+        `MCPClient(${this.server.name}): failed to connect to ${this.server.url}.`,
+        { context: { server: this.server.name, url: this.server.url }, cause },
+      )
+    }
+  }
+
+  /**
+   * Finish the OAuth authorization-code flow after the user
+   * authorized and was redirected back to the app's callback URL.
+   * Exchanges `code` for tokens, persists them via the configured
+   * `MCPOAuthStore`, then connects.
+   *
+   * Throws `BrainError` when called on a server without OAuth
+   * configured.
+   */
+  async completeAuthorization(code: string): Promise<void> {
+    if (this.server.oauth === undefined) {
+      throw new BrainError(
+        `MCPClient(${this.server.name}): completeAuthorization() called on a server without \`oauth\` configured.`,
+        { context: { server: this.server.name } },
+      )
+    }
+    if (this._transport === undefined) {
+      // A previous `connect()` attempt builds the transport + captures
+      // the auth URL on the provider. Apps that lost the transport
+      // reference (typical for stateless callback handlers) can
+      // construct a fresh transport here — the store carries every
+      // bit of state the exchange needs.
+      this._transport = this._buildTransport()
+    }
+    await this._transport.finishAuth(code)
+    // Now that tokens are saved, re-attempt the connection.
+    this._connected = false
+    await this.connect()
+  }
+
+  async listTools(opts: { signal?: AbortSignal } = {}): Promise<MCPToolDescriptor[]> {
+    await this.connect()
+    let response: Awaited<ReturnType<Client['listTools']>>
+    try {
+      response = await this._client.listTools(
+        undefined,
+        opts.signal !== undefined ? { signal: opts.signal } : undefined,
+      )
+    } 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,
+    opts: { signal?: AbortSignal } = {},
+  ): Promise<MCPCallToolResult> {
+    await this.connect()
+    let response: Awaited<ReturnType<Client['callTool']>>
+    try {
+      response = await this._client.callTool(
+        {
+          name,
+          arguments: (input ?? {}) as Record<string, unknown>,
+        },
+        undefined,
+        opts.signal !== undefined ? { signal: opts.signal } : undefined,
+      )
+    } 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}`
+    }
+    const transportOpts: ConstructorParameters<typeof StreamableHTTPClientTransport>[1] = {
+      requestInit: { headers },
+    }
+    if (this.server.oauth !== undefined) {
+      this._authProvider = new StoreBackedOAuthProvider(this.server.oauth)
+      transportOpts.authProvider = this._authProvider
+    }
+    return new StreamableHTTPClientTransport(new URL(this.server.url), transportOpts)
+  }
+}
+
+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,23 @@
+// 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 {
+  MCPAuthRequiredError,
+  type MCPOAuthConfig,
+  type MCPOAuthStore,
+  MemoryOAuthStore,
+} from './oauth.ts'
+export { MCPClientPool, type MCPClientFactory } from './pool.ts'
+export {
+  resolveMcpTools,
+  type ResolveMcpToolsOptions,
+  type ResolvedMcpTools,
+} from './resolve_mcp_tools.ts'