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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.15",
+  "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.15",
+    "@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_generate_result.ts

@@ -0,0 +1,30 @@
+/**
+ * `AgentGenerateResult<T>` — what an Agent run returns when the
+ * runner was switched into structured-output mode via
+ * `.output(schema)`.
+ *
+ * Combines the structured-output payload (`value` + raw `text`) with
+ * the agent-loop bookkeeping (`messages`, `iterations`, `stopReason`,
+ * `usage`) so apps can still render the trace + report token spend
+ * the same way they do for `AgentResult`. `iterations` is always `0`
+ * in V1 because the structured-output path doesn't engage the
+ * tool-use loop — see the docs for the (deferred) "tools + schema"
+ * combined slice.
+ */
+
+import type { ChatUsage, Message } from './types.ts'
+
+export interface AgentGenerateResult<T = unknown> {
+  /** Parsed structured value matching the supplied `OutputSchema<T>`. */
+  value: T
+  /** Raw JSON text the model produced — handy for logging when `parse` rejects. */
+  text: string
+  /** Full message history of the run (single user → assistant turn in V1). */
+  messages: Message[]
+  /** Always `0` in V1 — the schema path doesn't engage the tool-use loop. */
+  iterations: number
+  /** Provider-reported terminal stop reason. */
+  stopReason: string
+  /** Token usage from the single underlying `generate` call. */
+  usage: ChatUsage
+}

package/src/agent_runner.ts

@@ -2,28 +2,54 @@
  * `AgentRunner` — fluent builder returned by `BrainManager.agent(Class)`.
  *
  * Carries the agent instance + an input message + an optional
- * per-run context bag. `run()` translates the agent's declarative
- * configuration into a `runWithTools` call and returns the
- * `AgentResult`.
+ * per-run context bag + an optional structured-output schema.
+ * `run()` translates the agent's declarative configuration into
+ * either a `runWithTools` call (default) or a `generate` call (when
+ * `.output(schema)` was used) and returns the matching result type.
+ *
+ * Designed to chain:
+ *
+ * ```ts
+ * brain.agent(R).input(text).context({...}).run()
+ * brain.agent(R).input(text).output(schema).run()  // → AgentGenerateResult<T>
+ * ```
  *
- * Designed to chain: `brain.agent(R).input(text).context({...}).run()`.
  * Apps that need the full Message-array surface bypass the runner
- * and call `BrainManager.runTools(messages, tools, options)` directly.
+ * and call `BrainManager.runTools(messages, tools, options)` or
+ * `BrainManager.generate(input, schema, options)` directly.
  */
 
 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'
+import type { ChatOptions, Message } from './types.ts'
 import type { RunWithToolsOptions } from './provider.ts'
-import type { Message } from './types.ts'
 
-export class AgentRunner {
+/**
+ * Conditional return shape for `AgentRunner.run()`. With the default
+ * generic (`T = never`), `run()` returns `AgentResult` — the
+ * tool-loop shape. When the runner has been switched into
+ * structured-output mode via `.output(schema)`, `T` carries the
+ * inferred type and `run()` returns `AgentGenerateResult<T>`.
+ *
+ * The `[T] extends [never]` form is the standard "is this still the
+ * default never?" check — `T extends never` would distribute over
+ * union types and break.
+ */
+export type AgentRunResult<T> = [T] extends [never] ? AgentResult : AgentGenerateResult<T>
+
+export class AgentRunner<T = never> {
   private prompt: string | undefined
   private contextBag: Record<string, unknown> = {}
+  private schema: OutputSchema<T> | undefined
 
   constructor(
     private readonly brain: BrainManager,
-    private readonly agent: Agent,
+    private readonly agent: Agent<unknown>,
   ) {}
 
   /** Set the user input. Required before `run()`. */
@@ -43,21 +69,121 @@ export class AgentRunner {
     return this
   }
 
-  async run(): Promise<AgentResult> {
+  /**
+   * Switch the runner into structured-output mode. `run()` then
+   * delegates to `BrainManager.generate(...)` and returns an
+   * `AgentGenerateResult<U>` shaped to the supplied schema.
+   *
+   * V1 caveat: structured output and tool use can't be combined yet.
+   * Agents that declare `tools` or `mcpServers` AND call `.output()`
+   * throw a `BrainError` at `run()` with a clear "this combination is
+   * deferred" message. Apps that need both today run them in two
+   * steps — `runTools(...)` for the loop, then `generate(...)` for
+   * the structured summary.
+   */
+  output<U>(schema: OutputSchema<U>): AgentRunner<U> {
+    // Mutate in place + cast — the runtime state is a single object;
+    // the generic narrows only the static return type. This avoids
+    // cloning the prompt + contextBag fields.
+    this.schema = schema as unknown as OutputSchema<T>
+    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 Error('AgentRunner.run: input() must be called before run().')
+      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().')
+    }
+    const messages: Message[] = [{ role: 'user', content: this.prompt }]
+
+    if (this.schema !== undefined) {
+      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)
+      const generateResult: AgentGenerateResult<T> = {
+        value: result.value,
+        text: result.text,
+        messages: [
+          ...messages,
+          { role: 'assistant', content: result.text },
+        ],
+        iterations: 0,
+        stopReason: result.stopReason ?? 'stop',
+        usage: result.usage,
+      }
+      return generateResult as AgentRunResult<T>
+    }
+
+    const options: RunWithToolsOptions = {
+      ...this.buildChatOptions(),
+      maxIterations: this.agent.maxIterations,
+      context: this.contextBag,
+    }
+    if (this.agent.mcpServers.length > 0) options.mcpServers = this.agent.mcpServers
+    const result = await this.brain.runTools(messages, this.agent.tools, options)
+    return result as AgentRunResult<T>
+  }
+
+  private buildChatOptions(): ChatOptions {
+    const options: ChatOptions = {
       tier: this.agent.tier,
       maxTokens: this.agent.maxTokens,
       system: this.agent.instructions,
-      maxIterations: this.agent.maxIterations,
-      context: this.contextBag,
     }
     if (this.agent.model !== undefined) options.model = this.agent.model
     if (this.agent.provider !== undefined) options.provider = this.agent.provider
-    if (this.agent.mcpServers.length > 0) options.mcpServers = this.agent.mcpServers
-    return this.brain.runTools(messages, this.agent.tools, options)
+    return options
   }
 }

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 {