@strav/brain 1.0.0-alpha.15 → 1.0.0-alpha.17

package/src/mcp/oauth.ts

@@ -0,0 +1,227 @@
+/**
+ * OAuth support for the local MCP client.
+ *
+ * Most real-world MCP servers (Linear, Notion, GitHub, Asana,
+ * Atlassian) are OAuth-protected. The local client at
+ * `@strav/brain/mcp` already supports static bearer tokens via
+ * `MCPServer.authorizationToken` — fine for self-hosted servers,
+ * useless against any commercial server. This module closes the
+ * gap.
+ *
+ * The flow apps see:
+ *
+ * ```ts
+ * const store = new MemoryOAuthStore()
+ * const linear: MCPServer = {
+ *   name: 'linear',
+ *   url: 'https://mcp.linear.app',
+ *   oauth: {
+ *     redirectUri: 'https://myapp.com/mcp/linear/callback',
+ *     scope: 'read',
+ *     store,
+ *   },
+ * }
+ *
+ * try {
+ *   const client = new MCPClient(linear)
+ *   await client.connect()
+ * } catch (err) {
+ *   if (err instanceof MCPAuthRequiredError) {
+ *     // Redirect the user to err.authorizationUrl and remember
+ *     // who they were (so the callback handler can rebuild the
+ *     // store with the right per-user state).
+ *   }
+ * }
+ *
+ * // Later, in the callback handler:
+ * const client = new MCPClient(linear)
+ * await client.completeAuthorization(req.query.code)
+ * // The store now has tokens; subsequent connect()s succeed.
+ * ```
+ *
+ * The framework is server-side and headless — it can't redirect
+ * the user inline. So instead of blocking on `connect()`, we
+ * surface `MCPAuthRequiredError` carrying the authorization URL.
+ * Apps redirect the user themselves, then call
+ * `MCPClient.completeAuthorization(code)` from their callback
+ * route.
+ *
+ * Multi-tenancy: build a fresh `MCPOAuthStore` per `(user, server)`
+ * with the user id baked into the storage keys. The store
+ * interface is intentionally per-server (no `userId` arg) so apps
+ * pick the boundary that matches their data model.
+ */
+
+import type {
+  OAuthClientInformation,
+  OAuthClientInformationFull,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from '@modelcontextprotocol/sdk/shared/auth.js'
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
+import { BrainError } from '../brain_error.ts'
+
+/**
+ * Persistence contract for one MCP server's OAuth state.
+ *
+ * Methods may be sync or async — implementations are free to call
+ * a DB, a Redis cache, a file, or hold the state in memory. The
+ * framework awaits whichever shape returns.
+ *
+ * Per-(server) only by design — apps that need per-(user, server)
+ * scoping construct a fresh store per request with the user id
+ * baked into the underlying storage keys.
+ */
+export interface MCPOAuthStore {
+  /** Load the dynamic-client-registration record, or undefined if not registered. */
+  clientInformation():
+    | OAuthClientInformation
+    | undefined
+    | Promise<OAuthClientInformation | undefined>
+  /** Persist the dynamic-client-registration record after registration succeeds. */
+  saveClientInformation(info: OAuthClientInformationFull): void | Promise<void>
+  /** Load the active token set, or undefined if the user hasn't authorized. */
+  tokens(): OAuthTokens | undefined | Promise<OAuthTokens | undefined>
+  /** Persist tokens after authorization completes or a refresh succeeds. */
+  saveTokens(tokens: OAuthTokens): void | Promise<void>
+  /** Load the PKCE code verifier saved during the authorize step. */
+  codeVerifier(): string | Promise<string>
+  /** Persist the PKCE code verifier before redirecting to authorize. */
+  saveCodeVerifier(verifier: string): void | Promise<void>
+}
+
+/** Per-server OAuth configuration on `MCPServer.oauth`. */
+export interface MCPOAuthConfig {
+  /** Where the user comes back after authorizing. Must match a registered redirect URI on the OAuth server. */
+  redirectUri: string
+  /** Optional OAuth scopes to request. Some servers require specific scopes. */
+  scope?: string
+  /** Per-server token + client-info storage. */
+  store: MCPOAuthStore
+  /** Optional client metadata for dynamic client registration. Defaults to a minimal sane shape. */
+  clientMetadata?: Partial<OAuthClientMetadata>
+}
+
+/**
+ * `MemoryOAuthStore` — in-memory `MCPOAuthStore` implementation.
+ *
+ * Fine for tests and single-process dev. Production apps with
+ * multiple processes or restarts persist to a DB / Redis / KV.
+ */
+export class MemoryOAuthStore implements MCPOAuthStore {
+  private _clientInfo: OAuthClientInformationFull | undefined
+  private _tokens: OAuthTokens | undefined
+  private _verifier: string | undefined
+
+  clientInformation(): OAuthClientInformation | undefined {
+    return this._clientInfo
+  }
+  saveClientInformation(info: OAuthClientInformationFull): void {
+    this._clientInfo = info
+  }
+  tokens(): OAuthTokens | undefined {
+    return this._tokens
+  }
+  saveTokens(tokens: OAuthTokens): void {
+    this._tokens = tokens
+  }
+  codeVerifier(): string {
+    if (this._verifier === undefined) {
+      throw new BrainError(
+        'MemoryOAuthStore.codeVerifier(): no PKCE verifier saved. The authorization flow must call saveCodeVerifier before requesting the verifier.',
+      )
+    }
+    return this._verifier
+  }
+  saveCodeVerifier(verifier: string): void {
+    this._verifier = verifier
+  }
+}
+
+/**
+ * Thrown when an MCP server requires the user to authorize before
+ * the framework can connect. Apps catch this on `MCPClient.connect()`,
+ * redirect the user to `authorizationUrl`, and on the OAuth callback
+ * route call `MCPClient.completeAuthorization(code)` to finish the
+ * flow.
+ *
+ * `BrainError` subclass so the typed-exception handler renders it
+ * cleanly through the standard pathway.
+ */
+export class MCPAuthRequiredError extends BrainError {
+  /** URL the user should be redirected to in order to authorize. */
+  readonly authorizationUrl: string
+
+  constructor(serverName: string, authorizationUrl: string) {
+    super(
+      `MCPClient(${serverName}): authorization required. Redirect the user to authorizationUrl and call completeAuthorization(code) from your callback route.`,
+      {
+        context: { server: serverName, authorizationUrl },
+      },
+    )
+    this.authorizationUrl = authorizationUrl
+  }
+}
+
+/**
+ * Default client metadata used when dynamic client registration
+ * fires. Apps override per-server via
+ * `MCPOAuthConfig.clientMetadata`.
+ */
+function defaultClientMetadata(redirectUri: string): OAuthClientMetadata {
+  return {
+    redirect_uris: [redirectUri],
+    token_endpoint_auth_method: 'none',
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+    client_name: 'strav-brain',
+  }
+}
+
+/**
+ * Internal — implements the SDK's `OAuthClientProvider` against an
+ * `MCPOAuthStore`. Holds the auth URL captured from the SDK so
+ * `MCPClient.connect()` can surface it on `MCPAuthRequiredError`.
+ */
+export class StoreBackedOAuthProvider implements OAuthClientProvider {
+  /** Captured auth URL — populated by the SDK when authorization is needed. */
+  capturedAuthorizationUrl: URL | undefined
+
+  constructor(
+    private readonly config: MCPOAuthConfig,
+  ) {}
+
+  get redirectUrl(): string {
+    return this.config.redirectUri
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      ...defaultClientMetadata(this.config.redirectUri),
+      ...(this.config.scope !== undefined ? { scope: this.config.scope } : {}),
+      ...(this.config.clientMetadata ?? {}),
+    }
+  }
+
+  async clientInformation(): Promise<OAuthClientInformation | undefined> {
+    return await this.config.store.clientInformation()
+  }
+  async saveClientInformation(info: OAuthClientInformationFull): Promise<void> {
+    await this.config.store.saveClientInformation(info)
+  }
+  async tokens(): Promise<OAuthTokens | undefined> {
+    return await this.config.store.tokens()
+  }
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    await this.config.store.saveTokens(tokens)
+  }
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    this.capturedAuthorizationUrl = authorizationUrl
+  }
+  async saveCodeVerifier(verifier: string): Promise<void> {
+    await this.config.store.saveCodeVerifier(verifier)
+  }
+  async codeVerifier(): Promise<string> {
+    return await this.config.store.codeVerifier()
+  }
+}

package/src/mcp/resolve_mcp_tools.ts

@@ -75,8 +75,12 @@ function buildTool(
     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)
+    async execute(input: unknown, ctx: ToolContext): Promise<string> {
+      const result = await client.callTool(
+        descriptor.name,
+        input,
+        ctx.signal !== undefined ? { signal: ctx.signal } : {},
+      )
       if (result.isError) {
         return `MCP tool error: ${result.content}`
       }

package/src/mcp_server.ts

@@ -40,8 +40,24 @@ export interface MCPServer {
    * Optional bearer token. Apps source from env vars / secrets
    * managers — never hardcode. The framework forwards this verbatim
    * to the provider's `authorization_token` field.
+   *
+   * Mutually exclusive with `oauth`. Use `authorizationToken` for
+   * self-hosted servers where you control the token; use `oauth`
+   * for commercial servers (Linear, Notion, GitHub, ...).
    */
   authorizationToken?: string
+  /**
+   * OAuth configuration for servers that require it. When set, the
+   * local MCP client (`@strav/brain/mcp`) drives the
+   * authorization-code-with-PKCE flow against the server's OAuth
+   * endpoints, storing tokens via the supplied `store`. The
+   * Anthropic server-side path doesn't use this — Anthropic's
+   * connector handles its own auth.
+   *
+   * Mutually exclusive with `authorizationToken`. See the OAuth
+   * section of `docs/brain/guides/mcp.md`.
+   */
+  oauth?: import('./mcp/oauth.ts').MCPOAuthConfig
   /** Per-server tool config (allowlist / enable flag). */
   tools?: MCPServerToolConfig
 }

package/src/provider.ts

@@ -12,16 +12,24 @@
  * subclassing.
  */
 
+import type { AgentGenerateResult } from './agent_generate_result.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 { OutputSchema } from './output_schema.ts'
 import type { Tool } from './tool.ts'
+import type { ToolExecutionError } from './tool_execution_error.ts'
 import type {
+  AudioSource,
   ChatOptions,
   ChatResult,
+  EmbedOptions,
+  EmbedResult,
   GenerateResult,
   Message,
   StreamEvent,
+  TranscribeOptions,
+  TranscribeResult,
 } from './types.ts'
 
 export interface RunWithToolsOptions extends ChatOptions {
@@ -37,6 +45,30 @@ export interface RunWithToolsOptions extends ChatOptions {
    * resulting `mcp_tool_use` / `mcp_tool_result` blocks.
    */
   mcpServers?: readonly MCPServer[]
+  /**
+   * Tool-error recovery hook. Called when a tool's `execute` throws
+   * — OR when the model called a tool that isn't registered. Two
+   * outcomes:
+   *
+   *   - Return a string → the loop continues. The string lands as
+   *     `tool_result.content` with `isError: true`, the model sees
+   *     the error and can adapt (try a different approach, ask the
+   *     user, give up). Recommended for production agents that
+   *     should survive transient failures.
+   *
+   *   - Return `undefined` (the default when this option is unset)
+   *     → the framework throws `ToolExecutionError` and the loop
+   *     aborts. Same behavior as before this option existed.
+   *
+   * The hook may inspect `error.cause` to filter — e.g., feed back
+   * transient HTTP errors but rethrow programmer errors:
+   *
+   * ```ts
+   * onToolError: (err) =>
+   *   err.cause instanceof TransientError ? err.cause.message : undefined
+   * ```
+   */
+  onToolError?(error: ToolExecutionError): string | undefined
 }
 
 export interface Provider {
@@ -99,4 +131,81 @@ export interface Provider {
     schema: OutputSchema<T>,
     options?: ChatOptions,
   ): Promise<GenerateResult<T>>
+
+  /**
+   * Tool-loop + structured output combined. Runs the agentic loop
+   * with the same tool-handling as `runWithTools`, but pins a
+   * JSON-Schema constraint on every turn — so when the model
+   * finally answers without calling a tool, its text is JSON
+   * matching the schema. Returns the parsed value alongside the
+   * loop bookkeeping.
+   *
+   * Optional on the interface; `BrainManager.generateWithTools`
+   * throws `BrainError` when the configured provider lacks it.
+   */
+  runWithToolsAndSchema?<T>(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    schema: OutputSchema<T>,
+    options?: RunWithToolsOptions,
+  ): Promise<AgentGenerateResult<T>>
+
+  /**
+   * Streaming variant of `runWithToolsAndSchema`. Same agentic loop,
+   * same schema constraint on every turn — yielded as
+   * `AgentStreamEvent<T>`s. The terminal `stop` event carries the
+   * parsed `value` + raw `text` alongside the loop bookkeeping.
+   *
+   * Optional; `BrainManager.streamGenerateWithTools` throws
+   * `BrainError` when the chosen provider doesn't implement it.
+   */
+  streamWithToolsAndSchema?<T>(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    schema: OutputSchema<T>,
+    options?: RunWithToolsOptions,
+  ): AsyncIterable<AgentStreamEvent<T>>
+
+  /**
+   * Streaming variant of `runWithTools`. Yields `AgentStreamEvent`s
+   * as the 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.
+   *
+   * Optional — providers without a streaming tool-loop implementation
+   * can omit it; `BrainManager.streamTools` throws `BrainError` in
+   * that case.
+   */
+  streamWithTools?(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options?: RunWithToolsOptions,
+  ): AsyncIterable<AgentStreamEvent>
+
+  /**
+   * Embeddings — turn one or more text inputs into vectors for
+   * similarity search / RAG / clustering. Optional because not
+   * every provider exposes an embeddings endpoint (V1: Anthropic
+   * and DeepSeek don't; OpenAI, Gemini, Ollama do).
+   */
+  embed?(
+    texts: readonly string[],
+    options?: EmbedOptions,
+  ): Promise<EmbedResult>
+
+  /**
+   * Audio transcription — convert an audio clip to text.
+   * Complements `AudioBlock` (which sends audio + text together
+   * to a multimodal chat model) by exposing the dedicated
+   * transcription endpoint where the provider has one. V1:
+   * OpenAI (Whisper / gpt-4o-transcribe), Ollama (inherits via
+   * OpenAI-compat), Gemini (chat-wrap fallback — internally
+   * sends an AudioBlock with a "transcribe verbatim" prompt).
+   * Anthropic + DeepSeek throw — no transcription API.
+   */
+  transcribe?(
+    audio: AudioSource,
+    options?: TranscribeOptions,
+  ): Promise<TranscribeResult>
 }