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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.17",
   "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",
@@ -24,7 +24,7 @@
     "@anthropic-ai/sdk": "^0.100.0",
     "@google/genai": "^2.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@strav/kernel": "1.0.0-alpha.16",
+    "@strav/kernel": "1.0.0-alpha.17",
     "openai": "^6.0.0"
   },
   "peerDependencies": {

package/src/agent.ts

@@ -21,17 +21,30 @@
  *   .run()
  * ```
  *
- * V1 makes the configuration declarative-only — apps that need
- * runtime knobs (per-request model overrides, dynamic tool sets)
- * use `BrainManager.runTools(...)` directly. Adding per-instance
- * overrides on the Agent class is a future ergonomic slice.
+ * Structured output (typed result without `.output(schema)` at the call site):
+ *
+ * ```ts
+ * class CityAgent extends Agent<CityAnswer> {
+ *   override readonly instructions = 'You only emit verified city data.'
+ *   override readonly outputSchema = citySchema  // OutputSchema<CityAnswer>
+ * }
+ *
+ * const { value } = await brain.agent(CityAgent).input('Capital of France?').run()
+ * //      ^? CityAnswer — runner is typed from the class generic
+ * ```
+ *
+ * The generic threads `T` through `BrainManager.agent(Class)` →
+ * `AgentRunner<T>` → `AgentGenerateResult<T>`. Subclasses that
+ * don't declare an output type stay `Agent<never>` and `run()`
+ * returns `AgentResult` exactly as before.
  */
 
 import type { MCPServer } from './mcp_server.ts'
+import type { OutputSchema } from './output_schema.ts'
 import type { ModelTier } from './types.ts'
 import type { Tool } from './tool.ts'
 
-export abstract class Agent {
+export abstract class Agent<T = never> {
   /** System prompt — the persona / instructions Claude sees on every turn. */
   abstract readonly instructions: string
 
@@ -65,4 +78,20 @@ export abstract class Agent {
 
   /** Hard cap on per-call response tokens. Default `4096`. */
   readonly maxTokens: number = 4096
+
+  /**
+   * Structured-output schema. Set on subclasses that extend
+   * `Agent<SomeType>` to declare the agent always returns that
+   * shape; `BrainManager.agent(Class)` then types the runner
+   * automatically so `.run()` returns `AgentGenerateResult<T>`
+   * without a per-call `.output(schema)`.
+   *
+   * Leave unset on `Agent<never>` subclasses (no structured
+   * output). The runner falls back to the standard tool-loop path
+   * and returns `AgentResult`.
+   *
+   * Apps that want a per-call override still chain
+   * `.output(otherSchema)` — that wins over the class-side value.
+   */
+  readonly outputSchema?: OutputSchema<T>
 }

package/src/agent_runner.ts

@@ -22,6 +22,7 @@
 import type { Agent } from './agent.ts'
 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 { BrainManager } from './brain_manager.ts'
 import { BrainError } from './brain_error.ts'
 import type { OutputSchema } from './output_schema.ts'
@@ -48,7 +49,7 @@ export class AgentRunner<T = never> {
 
   constructor(
     private readonly brain: BrainManager,
-    private readonly agent: Agent,
+    private readonly agent: Agent<unknown>,
   ) {}
 
   /** Set the user input. Required before `run()`. */
@@ -88,6 +89,44 @@ export class AgentRunner<T = never> {
     return this as unknown as AgentRunner<U>
   }
 
+  /**
+   * Streaming variant of `run()`. Returns an
+   * `AsyncIterable<AgentStreamEvent<T>>` — yields text deltas,
+   * tool-use/result boundaries, and a terminal `stop` event with
+   * the full trace.
+   *
+   * Default (no `.output(schema)` set): the terminal `stop` has the
+   * plain shape and `T` defaults to `never`.
+   *
+   * With `.output(schema)`: the terminal `stop` event carries the
+   * parsed `value: T` + raw `text` alongside the loop bookkeeping,
+   * and the runner delegates to
+   * `BrainManager.streamGenerateWithTools`.
+   */
+  stream(): AsyncIterable<AgentStreamEvent<T>> {
+    if (this.prompt === undefined) {
+      throw new BrainError('AgentRunner.stream: input() must be called before stream().')
+    }
+    const messages: Message[] = [{ role: 'user', content: this.prompt }]
+    const options: RunWithToolsOptions = {
+      ...this.buildChatOptions(),
+      maxIterations: this.agent.maxIterations,
+      context: this.contextBag,
+    }
+    if (this.agent.mcpServers.length > 0) options.mcpServers = this.agent.mcpServers
+    if (this.schema !== undefined) {
+      return this.brain.streamGenerateWithTools<T>(
+        messages,
+        this.schema,
+        this.agent.tools,
+        options,
+      )
+    }
+    return this.brain.streamTools(messages, this.agent.tools, options) as AsyncIterable<
+      AgentStreamEvent<T>
+    >
+  }
+
   async run(): Promise<AgentRunResult<T>> {
     if (this.prompt === undefined) {
       throw new BrainError('AgentRunner.run: input() must be called before run().')
@@ -95,17 +134,21 @@ export class AgentRunner<T = never> {
     const messages: Message[] = [{ role: 'user', content: this.prompt }]
 
     if (this.schema !== undefined) {
-      if (this.agent.tools.length > 0 || this.agent.mcpServers.length > 0) {
-        throw new BrainError(
-          'AgentRunner.output() does not yet support tool use. The agent declares tools or mcpServers — drop them on the agent, or run runTools(...) and generate(...) as two separate calls. Combined tool + schema lands in a later slice.',
-          {
-            context: {
-              agent: this.agent.constructor.name,
-              tools: this.agent.tools.length,
-              mcpServers: this.agent.mcpServers.length,
-            },
-          },
+      const hasTools = this.agent.tools.length > 0 || this.agent.mcpServers.length > 0
+      if (hasTools) {
+        const toolOptions: RunWithToolsOptions = {
+          ...this.buildChatOptions(),
+          maxIterations: this.agent.maxIterations,
+          context: this.contextBag,
+        }
+        if (this.agent.mcpServers.length > 0) toolOptions.mcpServers = this.agent.mcpServers
+        const result = await this.brain.generateWithTools<T>(
+          messages,
+          this.schema,
+          this.agent.tools,
+          toolOptions,
         )
+        return result as AgentRunResult<T>
       }
       const generateOptions = this.buildChatOptions()
       const result = await this.brain.generate<T>(messages, this.schema, generateOptions)

package/src/agent_stream_event.ts

@@ -0,0 +1,100 @@
+/**
+ * `AgentStreamEvent<T>` — the union yielded by streaming agentic
+ * runs (`Provider.streamWithTools` / `BrainManager.streamTools` /
+ * `AgentRunner.stream`).
+ *
+ * The generic `T` carries the structured-output type when the run
+ * was schema-constrained:
+ *   - With the default `T = never`, the terminal `stop` event is the
+ *     plain shape: `{ stopReason, iterations, usage, messages }`.
+ *   - With `T` set (via `BrainManager.streamGenerateWithTools` or
+ *     `AgentRunner.stream()` after `.output(schema)`), the `stop`
+ *     event additionally carries `{ value: T; text: string }` — the
+ *     parsed JSON shaped to the schema and the raw text the model
+ *     produced.
+ *
+ * Event vocabulary:
+ *
+ *   - `iteration_start` — fired before each model call. `iteration`
+ *     starts at `0` and increments per round.
+ *   - `text` — a text delta from the assistant turn currently in
+ *     flight. Same shape as `StreamEvent.text` so apps can reuse
+ *     UI code.
+ *   - `tool_use_start` — a tool call has begun streaming. Fires
+ *     as soon as the model emits the call's `id` + `name`,
+ *     before the arguments finish streaming. Apps that render
+ *     "(calling X with …)" indicators show the tool name here.
+ *     Anthropic + OpenAI emit this from streaming chunks; Gemini
+ *     doesn't stream tool arguments (parts arrive complete) and
+ *     skips both `tool_use_start` and `tool_use_delta`.
+ *   - `tool_use_delta` — a chunk of the tool-call's argument JSON.
+ *     Apps that render the model composing the call (e.g. typing
+ *     `search(q='current state of bun.sql ...`) accumulate
+ *     `argsDelta` per `id` and re-render. The argument JSON is
+ *     partial / possibly malformed mid-stream — only the final
+ *     `tool_use` event carries the parsed input.
+ *   - `tool_use` — the assistant turn finished and the framework
+ *     parsed a tool call. Emitted with the parsed `input` before
+ *     the framework runs the tool. Source-of-truth for tool calls;
+ *     cross-provider consumers can rely on this even when the
+ *     start/delta events aren't fired.
+ *   - `tool_result` — the framework executed the tool and is about
+ *     to feed the result back to the model. `isError` reflects
+ *     whether the tool reported a failure (V1: only false today —
+ *     thrown executions abort the loop with `ToolExecutionError`;
+ *     graceful tool-error recovery is a later slice).
+ *   - `iteration_end` — the assistant turn fully drained, including
+ *     its `stopReason`. Apps that render per-iteration boundaries
+ *     use this.
+ *   - `stop` — terminal event. Carries the full `messages` trace,
+ *     iteration count, aggregated usage, and the framework
+ *     stop reason (`'end_turn'`, `'max_iterations'`, etc.). When the
+ *     run was schema-constrained, also carries `value` (parsed JSON)
+ *     and `text` (the raw JSON the model emitted).
+ *
+ * What's NOT in V1:
+ *   - `error` events. Failures throw out of the iterator (the
+ *     consumer's `for await` rejects). Apps that want resilient
+ *     loops catch around the consumer.
+ */
+
+import type { ChatUsage, Message } from './types.ts'
+
+interface BaseStopEvent {
+  type: 'stop'
+  stopReason: string
+  iterations: number
+  usage: ChatUsage
+  messages: Message[]
+}
+
+interface ValueStopEvent<T> extends BaseStopEvent {
+  /** Parsed JSON shaped to the supplied `OutputSchema<T>`. */
+  value: T
+  /** Raw JSON text the model emitted on its terminal turn. */
+  text: string
+}
+
+/**
+ * The `stop` variant narrows when the stream was schema-constrained
+ * — the `[T] extends [never]` form is the standard "is this still
+ * the default never?" check (a bare `T extends never` would
+ * distribute over union types and break).
+ */
+type StopEvent<T> = [T] extends [never] ? BaseStopEvent : ValueStopEvent<T>
+
+export type AgentStreamEvent<T = never> =
+  | { type: 'iteration_start'; iteration: number }
+  | { type: 'text'; delta: string }
+  | { type: 'tool_use_start'; id: string; name: string }
+  | { type: 'tool_use_delta'; id: string; argsDelta: string }
+  | { type: 'tool_use'; id: string; name: string; input: unknown }
+  | {
+      type: 'tool_result'
+      id: string
+      name: string
+      content: string
+      isError: boolean
+    }
+  | { type: 'iteration_end'; iteration: number; stopReason: string | null }
+  | StopEvent<T>

package/src/brain_config.ts

@@ -34,6 +34,31 @@ export interface AnthropicProviderConfig {
   betas?: readonly string[]
 }
 
+/**
+ * OpenAI Responses API driver config — backed by the `openai`
+ * SDK's `client.responses.create` endpoint. Use when you need
+ * OpenAI's server-side tools (web search, code interpreter) or
+ * the Responses API's reasoning surfaces. The chat completions
+ * provider (`driver: 'openai'`) covers everything else.
+ */
+export interface OpenAIResponsesProviderConfig {
+  driver: 'openai-responses'
+  /** API key. Required. Most apps source from `env('OPENAI_API_KEY')`. */
+  apiKey: string
+  /** Optional override of the SDK's base URL. */
+  baseUrl?: string
+  /** Optional organization id. */
+  organization?: string
+  /** Default model. Defaults to `gpt-5`. */
+  defaultModel?: string
+  /** Default `max_output_tokens`. Defaults to 4096. */
+  defaultMaxTokens?: number
+  /** Default embedding model (inherited from chat completions endpoint). Defaults to `text-embedding-3-small`. */
+  defaultEmbedModel?: string
+  /** Default audio-transcription model. Defaults to `whisper-1`. */
+  defaultTranscribeModel?: string
+}
+
 /** OpenAI-specific driver config. */
 export interface OpenAIProviderConfig {
   driver: 'openai'
@@ -47,6 +72,10 @@ export interface OpenAIProviderConfig {
   defaultModel?: string
   /** Default `max_tokens` for `chat()` calls that don't specify one. */
   defaultMaxTokens?: number
+  /** Default embedding model for `brain.embed(...)`. Defaults to `text-embedding-3-small`. */
+  defaultEmbedModel?: string
+  /** Default audio-transcription model for `brain.transcribe(...)`. Defaults to `whisper-1`. */
+  defaultTranscribeModel?: string
 }
 
 /** Google (Gemini) driver config — backed by `@google/genai`. */
@@ -62,12 +91,73 @@ export interface GeminiProviderConfig {
   defaultMaxTokens?: number
   /** Optional API version pin (`v1` / `v1beta`). */
   apiVersion?: string
+  /** Default embedding model for `brain.embed(...)`. Defaults to `text-embedding-004`. */
+  defaultEmbedModel?: string
+}
+
+/** DeepSeek driver config — backed by the `openai` SDK pointed at DeepSeek's OpenAI-compatible endpoint. */
+export interface DeepSeekProviderConfig {
+  driver: 'deepseek'
+  /** API key. Required. Most apps source from `env('DEEPSEEK_API_KEY')`. */
+  apiKey: string
+  /** Optional override of the SDK's base URL. Defaults to `https://api.deepseek.com/v1`. */
+  baseUrl?: string
+  /** Default model when neither `options.model` nor `options.tier` is passed. Defaults to `deepseek-chat`. */
+  defaultModel?: string
+  /** Default `max_tokens` for `chat()` calls that don't specify one. */
+  defaultMaxTokens?: number
+}
+
+/**
+ * Ollama driver config — backed by the `openai` SDK pointed at a
+ * local Ollama server's OpenAI-compatible `/v1` endpoint. The same
+ * shape works against any OpenAI-compatible local server (LM Studio,
+ * llama.cpp's server, vLLM, …) by overriding `baseUrl`.
+ */
+export interface OllamaProviderConfig {
+  driver: 'ollama'
+  /**
+   * Required — model must be already pulled on the Ollama server
+   * (`ollama pull <model>`). No universal default exists because
+   * apps install whichever models they need. Common picks for
+   * tool-calling: `llama3.2`, `llama3.1`, `qwen2.5`, `mistral`.
+   */
+  defaultModel: string
+  /** Optional override of the SDK's base URL. Defaults to `http://localhost:11434/v1`. */
+  baseUrl?: string
+  /**
+   * Optional API key. Ollama doesn't require one — the SDK demands
+   * a non-empty string, so a placeholder is fine and the default
+   * (`'ollama'`) works. Override only when running behind a proxy
+   * that adds its own auth layer.
+   */
+  apiKey?: string
+  /** Default `max_tokens` for `chat()` calls that don't specify one. */
+  defaultMaxTokens?: number
+  /**
+   * Default embedding model for `brain.embed(...)`. No universal
+   * default — apps pull an embedding-tuned model (e.g.
+   * `nomic-embed-text`, `mxbai-embed-large`) and reference it here.
+   * Calls that omit `options.model` without this set throw.
+   */
+  defaultEmbedModel?: string
+  /**
+   * Default audio-transcription model for `brain.transcribe(...)`.
+   * No universal default — Ollama versions vary on whether they
+   * expose a Whisper-style endpoint, and apps pull whatever
+   * model their build supports (e.g. `whisper`). Calls that omit
+   * `options.model` without this set throw.
+   */
+  defaultTranscribeModel?: string
 }
 
 export type ProviderConfig =
   | AnthropicProviderConfig
   | OpenAIProviderConfig
-  | GeminiProviderConfig // | DeepSeekProviderConfig (later slice)
+  | OpenAIResponsesProviderConfig
+  | GeminiProviderConfig
+  | DeepSeekProviderConfig
+  | OllamaProviderConfig
 
 /** Cache-shape defaults applied when `ChatOptions.cache` is omitted. */
 export interface BrainCacheConfig {

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