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

package/src/brain_manager.ts

@@ -21,24 +21,31 @@
 
 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 { 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`. */
@@ -168,6 +175,96 @@ export class BrainManager {
     return provider.runWithTools(messages, tools, resolved)
   }
 
+  /**
+   * 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>> {
+    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>> {
+    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> {
+    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 +291,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

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

@@ -8,16 +8,21 @@
 // tools, structured outputs, other providers.
 
 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 { AgentRunner, 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'
@@ -31,8 +36,12 @@ export { defineTool, type DefineToolSpec } from './define_tool.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 { OpenAIResponsesProvider } from './providers/openai_responses_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'
@@ -42,14 +51,23 @@ export type {
   ChatResult,
   ChatUsage,
   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,16 @@ export class MCPClient {
   readonly server: MCPServer
   private readonly _client: Client
   private _connected = false
+  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 ??
@@ -72,10 +88,17 @@ export class MCPClient {
   async connect(): Promise<void> {
     if (this._connected) return
     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 +106,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 +157,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 +199,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,12 @@ export {
   type MCPClientOptions,
   type MCPToolDescriptor,
 } from './client.ts'
+export {
+  MCPAuthRequiredError,
+  type MCPOAuthConfig,
+  type MCPOAuthStore,
+  MemoryOAuthStore,
+} from './oauth.ts'
 export {
   resolveMcpTools,
   type ResolveMcpToolsOptions,