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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.18",
   "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",
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./mcp": "./src/mcp/index.ts",
+    "./persistence": "./src/persistence/index.ts",
     "./zod": "./src/zod/index.ts"
   },
   "files": [
@@ -24,7 +25,8 @@
     "@anthropic-ai/sdk": "^0.100.0",
     "@google/genai": "^2.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@strav/kernel": "1.0.0-alpha.16",
+    "@strav/database": "1.0.0-alpha.18",
+    "@strav/kernel": "1.0.0-alpha.18",
     "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

@@ -27,4 +27,6 @@ export interface AgentGenerateResult<T = unknown> {
   stopReason: string
   /** Token usage from the single underlying `generate` call. */
   usage: ChatUsage
+  /** See `ChatResult.responseId`. */
+  responseId?: string
 }

package/src/agent_result.ts

@@ -29,4 +29,11 @@ export interface AgentResult {
   stopReason: string
   /** Token usage summed across every model call in the loop. */
   usage: ChatUsage
+  /**
+   * Final provider response id when the provider exposes stateful
+   * conversations (OpenAI Responses API). Captured from the last
+   * model turn so apps that persist the conversation can resume
+   * via `ChatOptions.previousResponseId`. Undefined elsewhere.
+   */
+  responseId?: string
 }

package/src/agent_runner.ts

@@ -22,11 +22,21 @@
 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 {
+  ChatOptions,
+  Message,
+  ToolUseBlock,
+} from './types.ts'
 import type { RunWithToolsOptions } from './provider.ts'
+import type {
+  SuspendedRun,
+  SuspendedState,
+  ToolResultInput,
+} from './suspended_run.ts'
 
 /**
  * Conditional return shape for `AgentRunner.run()`. With the default
@@ -41,16 +51,47 @@ import type { RunWithToolsOptions } from './provider.ts'
  */
 export type AgentRunResult<T> = [T] extends [never] ? AgentResult : AgentGenerateResult<T>
 
-export class AgentRunner<T = never> {
+/**
+ * Conditional return shape that flips when the runner has opted in
+ * to suspension via `.suspend(gate)`. The phantom `S` generic on
+ * `AgentRunner<T, S>` carries the bit; `S extends true` widens the
+ * union so callers must narrow with `isSuspended(...)` before
+ * touching `result.value` / `result.text`.
+ */
+export type AgentRunMaybeSuspended<T, S extends boolean> = [S] extends [true]
+  ? AgentRunResult<T> | SuspendedRun
+  : AgentRunResult<T>
+
+export class AgentRunner<T = never, S extends boolean = false> {
   private prompt: string | undefined
   private contextBag: Record<string, unknown> = {}
   private schema: OutputSchema<T> | undefined
+  private suspendGate:
+    | ((call: ToolUseBlock, context?: Record<string, unknown>) => boolean | Promise<boolean>)
+    | undefined
 
   constructor(
     private readonly brain: BrainManager,
-    private readonly agent: Agent,
+    private readonly agent: Agent<unknown>,
   ) {}
 
+  /**
+   * Install a human-in-the-loop gate. Called before each tool
+   * execution inside the agent loop; when it returns `true`, the
+   * run pauses and `.run()` resolves with a `SuspendedRun` instead
+   * of `AgentResult`. Apps obtain results out-of-band and call
+   * `.resume(state, results)` to continue.
+   *
+   * Throws `BrainError` if the runner is also in structured-output
+   * mode (`.output(schema)`) — schema + suspend is a deferred slice.
+   */
+  suspend(
+    gate: (call: ToolUseBlock, context?: Record<string, unknown>) => boolean | Promise<boolean>,
+  ): AgentRunner<T, true> {
+    this.suspendGate = gate
+    return this as unknown as AgentRunner<T, true>
+  }
+
   /** Set the user input. Required before `run()`. */
   input(text: string): this {
     this.prompt = text
@@ -88,24 +129,71 @@ export class AgentRunner<T = never> {
     return this as unknown as AgentRunner<U>
   }
 
-  async run(): Promise<AgentRunResult<T>> {
+  /**
+   * 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<AgentRunMaybeSuspended<T, S>> {
     if (this.prompt === undefined) {
       throw new BrainError('AgentRunner.run: input() must be called before run().')
     }
+    if (this.suspendGate !== undefined && this.schema !== undefined) {
+      throw new BrainError(
+        'AgentRunner.run: `.suspend(...)` and `.output(schema)` cannot be combined in V1 — the schema variants don\'t yet model pause/resume. Run tools first with suspension, then call brain.generate(...) on the result for the structured summary.',
+      )
+    }
     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)
@@ -129,8 +217,39 @@ export class AgentRunner<T = never> {
       context: this.contextBag,
     }
     if (this.agent.mcpServers.length > 0) options.mcpServers = this.agent.mcpServers
+    if (this.suspendGate !== undefined) options.shouldSuspend = this.suspendGate
     const result = await this.brain.runTools(messages, this.agent.tools, options)
-    return result as AgentRunResult<T>
+    return result as AgentRunMaybeSuspended<T, S>
+  }
+
+  /**
+   * Resume a previously-suspended run. Takes the `SuspendedRun.state`
+   * snapshot and the results gathered for each `pendingToolCalls`
+   * entry; the loop continues from where it paused.
+   *
+   * The runner's `suspend()` gate carries over so the same
+   * approval logic applies to any further tool calls — pass a
+   * fresh gate via `suspend()` before `resume()` to change the
+   * policy.
+   */
+  async resume(
+    state: SuspendedState,
+    results: readonly ToolResultInput[],
+  ): Promise<AgentRunMaybeSuspended<T, true>> {
+    if (this.schema !== undefined) {
+      throw new BrainError(
+        'AgentRunner.resume: structured-output runners cannot be resumed in V1 — `.output(schema)` is incompatible with pause/resume.',
+      )
+    }
+    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.suspendGate !== undefined) options.shouldSuspend = this.suspendGate
+    const result = await this.brain.resumeTools(state, results, this.agent.tools, options)
+    return result as AgentRunMaybeSuspended<T, true>
   }
 
   private buildChatOptions(): ChatOptions {

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 {