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

package/src/brain_manager.ts

@@ -21,24 +21,36 @@
 
 import type { Agent } from './agent.ts'
 import type { AgentResult } from './agent_result.ts'
+import type { AgentStreamEvent } from './agent_stream_event.ts'
 import type { MCPServer } from './mcp_server.ts'
+import type { AgentGenerateResult } from './agent_generate_result.ts'
 import type { OutputSchema } from './output_schema.ts'
 import { AgentRunner } from './agent_runner.ts'
 import { BrainError } from './brain_error.ts'
 import type { ModelTier } from './types.ts'
 import type {
+  AudioSource,
   ChatOptions,
   ChatResult,
+  EmbedOptions,
+  EmbedResult,
   GenerateResult,
   Message,
   StreamEvent,
+  TranscribeOptions,
+  TranscribeResult,
 } from './types.ts'
-import type { Provider, RunWithToolsOptions } from './provider.ts'
+import type {
+  Provider,
+  RunWithToolsOptions,
+  RunWithToolsOptionsWithSuspend,
+} from './provider.ts'
+import { appendResumeResults, type SuspendedRun, type SuspendedState, type ToolResultInput } from './suspended_run.ts'
 import type { Tool } from './tool.ts'
 import { DEFAULT_TIERS } from './brain_config.ts'
 
 /** Container-aware Agent constructor resolver — `BrainProvider` installs one wired to `app.resolve(...)`. */
-export type AgentResolver = <A extends Agent>(cls: new (...args: never[]) => A) => A
+export type AgentResolver = <A extends Agent<unknown>>(cls: new (...args: never[]) => A) => A
 
 export interface BrainManagerOptions {
   /** Name of the default provider — must exist in `providers`. */
@@ -145,11 +157,21 @@ export class BrainManager {
    * implement `runWithTools` (V1: OpenAI / Gemini / DeepSeek providers
    * don't yet — only `AnthropicProvider`).
    */
+  runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptionsWithSuspend,
+  ): Promise<AgentResult | SuspendedRun>
+  runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options?: RunWithToolsOptions,
+  ): Promise<AgentResult>
   async runTools(
     input: string | readonly Message[],
     tools: readonly Tool[],
     options: RunWithToolsOptions = {},
-  ): Promise<AgentResult> {
+  ): Promise<AgentResult | SuspendedRun> {
     const provider = this.provider(options.provider)
     if (!provider.runWithTools) {
       throw new BrainError(
@@ -168,6 +190,135 @@ export class BrainManager {
     return provider.runWithTools(messages, tools, resolved)
   }
 
+  /**
+   * Resume a previously-suspended tool-use loop. Takes the
+   * `SuspendedRun.state` snapshot plus the results the integrator
+   * gathered for each `pendingToolCalls` entry; appends a `tool_result`
+   * block per entry; re-enters `runTools` so the model can continue
+   * (potentially suspending again on the next tool).
+   *
+   * Mid-batch invariant: every pending call MUST get a result —
+   * otherwise the provider rejects the next request because the
+   * assistant turn's `tool_use` blocks are no longer balanced.
+   * `resumeTools` throws `BrainError` when results are missing.
+   *
+   * The `previousResponseId` carried on the snapshot (when the
+   * provider supports stateful conversations) is threaded back via
+   * `options.previousResponseId` automatically — per-call
+   * `options.previousResponseId` wins if supplied explicitly.
+   */
+  async resumeTools(
+    state: SuspendedState,
+    results: readonly ToolResultInput[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentResult | SuspendedRun> {
+    const resumed = appendResumeResults(state, results)
+    const merged: RunWithToolsOptions = { ...options }
+    if (merged.previousResponseId === undefined && state.responseId !== undefined) {
+      merged.previousResponseId = state.responseId
+    }
+    const out = await this.runTools(
+      resumed,
+      tools,
+      merged as RunWithToolsOptionsWithSuspend,
+    )
+    return mergeResumeCounters(out, state)
+  }
+
+  /**
+   * Streaming variant of `generateWithTools`. Yields
+   * `AgentStreamEvent<T>`s as the loop progresses; the terminal
+   * `stop` event carries the parsed value + raw JSON text. Throws
+   * `BrainError` when the provider lacks
+   * `streamWithToolsAndSchema` (V1: all three providers
+   * implement it).
+   */
+  streamGenerateWithTools<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent<T>> {
+    rejectShouldSuspend(options, 'streamGenerateWithTools')
+    const provider = this.provider(options.provider)
+    if (!provider.streamWithToolsAndSchema) {
+      throw new BrainError(
+        `BrainManager.streamGenerateWithTools: provider "${provider.name}" does not implement streamWithToolsAndSchema.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.streamWithToolsAndSchema<T>(messages, tools, schema, resolved)
+  }
+
+  /**
+   * Tool-loop + structured output combined. Runs the agentic loop
+   * with the supplied `tools` while pinning the output to `schema`
+   * on every turn; returns the parsed value when the model finally
+   * answers without calling a tool. MCP defaults + tier resolution
+   * + provider routing match `runTools` / `generate`.
+   *
+   * Throws `BrainError` when the chosen provider doesn't implement
+   * `runWithToolsAndSchema`. V1: all three providers do.
+   */
+  async generateWithTools<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentGenerateResult<T>> {
+    rejectShouldSuspend(options, 'generateWithTools')
+    const provider = this.provider(options.provider)
+    if (!provider.runWithToolsAndSchema) {
+      throw new BrainError(
+        `BrainManager.generateWithTools: provider "${provider.name}" does not implement runWithToolsAndSchema.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.runWithToolsAndSchema<T>(messages, tools, schema, resolved)
+  }
+
+  /**
+   * Streaming variant of `runTools`. Yields `AgentStreamEvent`s
+   * as the agentic loop progresses — text deltas during model
+   * turns, `tool_use` / `tool_result` boundaries around tool
+   * execution, `iteration_start` / `iteration_end` per round, a
+   * terminal `stop` with the full trace + usage.
+   *
+   * Throws `BrainError` when the configured provider doesn't
+   * implement `streamWithTools`.
+   */
+  streamTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent> {
+    rejectShouldSuspend(options, 'streamTools')
+    const provider = this.provider(options.provider)
+    if (!provider.streamWithTools) {
+      throw new BrainError(
+        `BrainManager.streamTools: provider "${provider.name}" does not implement streamWithTools.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.streamWithTools(messages, tools, resolved)
+  }
+
   /**
    * Structured output. Sends `input` to the configured (or
    * `options.provider`-overridden) provider with the JSON-Schema
@@ -194,21 +345,88 @@ export class BrainManager {
     return provider.generate<T>(messages, schema, resolved)
   }
 
+  /**
+   * Turn one or more text inputs into embedding vectors. Accepts
+   * either a single string (returns one vector) or an array
+   * (batch — returns one vector per input in the same order).
+   *
+   * Throws `BrainError` when the configured (or
+   * `options.provider`-overridden) provider doesn't implement
+   * `embed`. V1: OpenAI, Gemini, Ollama support it; Anthropic +
+   * DeepSeek throw with a clear "route to a different provider"
+   * message.
+   */
+  async embed(
+    input: string | readonly string[],
+    options: EmbedOptions = {},
+  ): Promise<EmbedResult> {
+    const provider = this.provider(options.provider)
+    if (!provider.embed) {
+      throw new BrainError(
+        `BrainManager.embed: provider "${provider.name}" does not implement embed. Route to a provider with an embeddings API (V1: OpenAI / Gemini / Ollama).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const texts = typeof input === 'string' ? [input] : input
+    return provider.embed(texts, options)
+  }
+
+  /**
+   * Transcribe one audio clip to text. Complements `AudioBlock`
+   * (which sends audio + a text prompt together to a multimodal
+   * chat model) by exposing the dedicated transcription endpoint
+   * where the provider has one. Apps that already have an
+   * `AudioBlock` can pass its `source` directly.
+   *
+   * Throws `BrainError` when the configured (or
+   * `options.provider`-overridden) provider doesn't implement
+   * `transcribe`. V1: OpenAI / Ollama (Whisper / gpt-4o-transcribe
+   * / local) and Gemini (chat-wrap fallback); Anthropic +
+   * DeepSeek throw.
+   */
+  async transcribe(
+    audio: AudioSource,
+    options: TranscribeOptions = {},
+  ): Promise<TranscribeResult> {
+    const provider = this.provider(options.provider)
+    if (!provider.transcribe) {
+      throw new BrainError(
+        `BrainManager.transcribe: provider "${provider.name}" does not implement transcribe. Route to a provider with audio support (V1: OpenAI / Ollama / Gemini).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    return provider.transcribe(audio, options)
+  }
+
   /**
    * Resolve an `Agent` subclass from the container and return an
    * `AgentRunner` ready to receive `input(...)` and `run()`. Apps
    * `@inject()`-decorate their Agent subclass so constructor
    * injection of dependencies (Repositories, services, etc.) flows
    * through normally.
+   *
+   * When the agent subclass extends `Agent<T>` for some `T` and
+   * declares `outputSchema`, the returned runner is typed as
+   * `AgentRunner<T>` and the schema is pre-applied — `.run()`
+   * returns `AgentGenerateResult<T>` without a per-call
+   * `.output(schema)`. Apps can still chain `.output(otherSchema)`
+   * to override.
    */
-  agent<A extends Agent>(AgentClass: new (...args: never[]) => A, instance?: A): AgentRunner {
+  agent<T = never>(
+    AgentClass: new (...args: never[]) => Agent<T>,
+    instance?: Agent<T>,
+  ): AgentRunner<T> {
     const agent = instance ?? this.resolveAgent(AgentClass)
-    return new AgentRunner(this, agent)
+    const runner = new AgentRunner<T>(this, agent)
+    if (agent.outputSchema !== undefined) {
+      return runner.output(agent.outputSchema)
+    }
+    return runner
   }
 
   // ─── Internal ────────────────────────────────────────────────────────────
 
-  private resolveAgent<A extends Agent>(AgentClass: new (...args: never[]) => A): A {
+  private resolveAgent<A extends Agent<unknown>>(AgentClass: new (...args: never[]) => A): A {
     if (this.agentResolver) return this.agentResolver(AgentClass)
     // Fallback: assume the Agent class is constructible without args.
     // Apps that need DI on the agent register a resolver via
@@ -247,3 +465,66 @@ function normalizeInput(input: string | readonly Message[]): readonly Message[]
   }
   return input
 }
+
+/**
+ * V1 scope guard. `shouldSuspend` is wired only into the non-
+ * streaming `runWithTools` loop; the streaming and schema variants
+ * don't yet model pause / resume, so silently ignoring would be
+ * worse than throwing. Apps that need both should run tools first
+ * (suspending as needed), then call `generate` for the structured
+ * summary in a separate step.
+ */
+/**
+ * Carry forward the pre-suspension iteration count + token usage so
+ * `result.iterations` / `result.usage` reflect the full run, not
+ * just the post-resume portion. When the resumed call suspends
+ * again, the new state's iterations + usage also get the carry-
+ * forward so apps see a running total across an arbitrary number
+ * of suspension cycles.
+ */
+function mergeResumeCounters(
+  out: AgentResult | SuspendedRun,
+  state: SuspendedState,
+): AgentResult | SuspendedRun {
+  // +1 accounts for the suspended round itself — at suspension time
+  // the loop hadn't yet incremented `iterations` (we paused mid-
+  // batch, before tool execution). Supplying results to resume
+  // effectively completes that round.
+  const carryIter = state.iterations + 1
+  if ('status' in out) {
+    return {
+      ...out,
+      state: {
+        ...out.state,
+        iterations: out.state.iterations + carryIter,
+        usage: addUsage(out.state.usage, state.usage),
+      },
+    }
+  }
+  return {
+    ...out,
+    iterations: out.iterations + carryIter,
+    usage: addUsage(out.usage, state.usage),
+  }
+}
+
+function addUsage(
+  a: SuspendedState['usage'],
+  b: SuspendedState['usage'],
+): SuspendedState['usage'] {
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+  }
+}
+
+function rejectShouldSuspend(options: RunWithToolsOptions, entry: string): void {
+  if (options.shouldSuspend !== undefined) {
+    throw new BrainError(
+      `BrainManager.${entry}: \`shouldSuspend\` is only supported on \`runTools\` (the non-streaming + no-schema entrypoint) in V1. Run tools first with suspension, then call \`generate\` for the structured summary as a separate step.`,
+      { context: { entry } },
+    )
+  }
+}

package/src/brain_provider.ts

@@ -28,8 +28,11 @@ 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 { DeepSeekProvider } from './providers/deepseek_provider.ts'
 import { GeminiProvider } from './providers/gemini_provider.ts'
+import { OllamaProvider } from './providers/ollama_provider.ts'
 import { OpenAIProvider } from './providers/openai_provider.ts'
+import { OpenAIResponsesProvider } from './providers/openai_responses_provider.ts'
 import type { Provider } from './provider.ts'
 
 export class BrainProvider extends ServiceProvider {
@@ -102,6 +105,13 @@ function buildProvider(name: string, config: ProviderConfig): Provider {
         )
       }
       return new OpenAIProvider(name, config)
+    case 'openai-responses':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openai-responses provider "${name}" is missing apiKey. Source from env('OPENAI_API_KEY').`,
+        )
+      }
+      return new OpenAIResponsesProvider(name, config)
     case 'google':
       if (!config.apiKey) {
         throw new ConfigError(
@@ -109,10 +119,24 @@ function buildProvider(name: string, config: ProviderConfig): Provider {
         )
       }
       return new GeminiProvider(name, config)
+    case 'deepseek':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: deepseek provider "${name}" is missing apiKey. Source from env('DEEPSEEK_API_KEY').`,
+        )
+      }
+      return new DeepSeekProvider(name, config)
+    case 'ollama':
+      if (!config.defaultModel) {
+        throw new ConfigError(
+          `BrainProvider: ollama provider "${name}" is missing defaultModel. Ollama models are user-installed — pick one you've pulled (e.g. 'llama3.2').`,
+        )
+      }
+      return new OllamaProvider(name, config)
     default: {
       const exhaustiveCheck: never = config
       throw new ConfigError(
-        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic, openai, google.`,
+        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic, openai, openai-responses, google, deepseek, ollama.`,
       )
       // (unreachable — kept for the exhaustive check to fire when a new driver lands)
       // biome-ignore lint/correctness/noUnreachable: kept for the exhaustive-check above

package/src/index.ts

@@ -10,15 +10,23 @@
 export { Agent } from './agent.ts'
 export type { AgentGenerateResult } from './agent_generate_result.ts'
 export type { AgentResult } from './agent_result.ts'
-export { AgentRunner, type AgentRunResult } from './agent_runner.ts'
+export {
+  AgentRunner,
+  type AgentRunMaybeSuspended,
+  type AgentRunResult,
+} from './agent_runner.ts'
+export type { AgentStreamEvent } from './agent_stream_event.ts'
 export {
   type AnthropicProviderConfig,
   type BrainCacheConfig,
   type BrainConfigShape,
+  type DeepSeekProviderConfig,
   DEFAULT_MODEL,
   DEFAULT_TIERS,
   type GeminiProviderConfig,
+  type OllamaProviderConfig,
   type OpenAIProviderConfig,
+  type OpenAIResponsesProviderConfig,
   type ProviderConfig,
 } from './brain_config.ts'
 export { BrainError } from './brain_error.ts'
@@ -29,12 +37,28 @@ export {
 } from './brain_manager.ts'
 export { BrainProvider } from './brain_provider.ts'
 export { defineTool, type DefineToolSpec } from './define_tool.ts'
+export { MCPClientPool, type MCPClientFactory } from './mcp/pool.ts'
 export type { MCPServer, MCPServerToolConfig } from './mcp_server.ts'
 export type { OutputSchema } from './output_schema.ts'
 export { AnthropicProvider } from './providers/anthropic_provider.ts'
+export { DeepSeekProvider } from './providers/deepseek_provider.ts'
 export { GeminiProvider } from './providers/gemini_provider.ts'
+export { OllamaProvider } from './providers/ollama_provider.ts'
+export { OpenAICompatProvider } from './providers/openai_compat_provider.ts'
 export { OpenAIProvider } from './providers/openai_provider.ts'
-export type { Provider, RunWithToolsOptions } from './provider.ts'
+export { OpenAIResponsesProvider } from './providers/openai_responses_provider.ts'
+export type {
+  Provider,
+  RunWithToolsOptions,
+  RunWithToolsOptionsWithSuspend,
+} from './provider.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'
@@ -42,15 +66,26 @@ export type {
   ChatOptions,
   ChatResult,
   ChatUsage,
+  CompactConfig,
+  CompactionBlock,
   ContentBlock,
+  AudioBlock,
+  AudioSource,
+  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

@@ -16,10 +16,16 @@
  *   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.
+ *   - `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
@@ -31,8 +37,10 @@
 
 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 {
@@ -58,8 +66,25 @@ 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 ??
@@ -71,11 +96,26 @@ export class MCPClient {
 
   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 },
@@ -83,11 +123,44 @@ export class MCPClient {
     }
   }
 
-  async listTools(): Promise<MCPToolDescriptor[]> {
+  /**
+   * 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()
+      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.`,
@@ -101,14 +174,22 @@ export class MCPClient {
     }))
   }
 
-  async callTool(name: string, input: unknown): Promise<MCPCallToolResult> {
+  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>,
-      })
+      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.`,
@@ -135,9 +216,14 @@ export class MCPClient {
     if (this.server.authorizationToken !== undefined) {
       headers.Authorization = `Bearer ${this.server.authorizationToken}`
     }
-    return new StreamableHTTPClientTransport(new URL(this.server.url), {
+    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)
   }
 }
 

package/src/mcp/index.ts

@@ -9,6 +9,13 @@ export {
   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,