@strav/brain 1.0.0-alpha.8 → 1.0.1

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.8",
-  "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching. Anthropic provider in V1; OpenAI / Gemini / DeepSeek follow.",
+  "version": "1.0.1",
+  "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",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./mcp": "./src/mcp/index.ts",
+    "./persistence": "./src/persistence/index.ts",
+    "./translate": "./src/translate/index.ts",
+    "./zod": "./src/zod/index.ts"
   },
   "files": [
     "src",
@@ -19,11 +23,23 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.8",
-    "@anthropic-ai/sdk": "^0.100.0"
+    "@anthropic-ai/sdk": "^0.100.0",
+    "@google/genai": "^2.7.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@strav/database": "1.0.1",
+    "@strav/kernel": "1.0.1",
+    "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@types/bun": ">=1.3.14"
+    "@types/bun": ">=1.3.14",
+    "zod": "^4.0.0"
   },
-  "devDependencies": null
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "zod": "^4.4.3"
+  }
 }

package/src/agent.ts

@@ -0,0 +1,97 @@
+/**
+ * `Agent` — declarative base class for AI agents.
+ *
+ * Apps subclass and set the static-ish properties: which model to
+ * use, what the agent's persona is, which tools it has access to,
+ * and an optional iteration ceiling. The `BrainManager.agent(Class)`
+ * call resolves an instance via the container, builds an
+ * `AgentRunner`, and lets the app stream input + context into it.
+ *
+ * ```ts
+ * @inject()
+ * class ResearchAgent extends Agent {
+ *   override readonly instructions = 'You are a meticulous research assistant.'
+ *   override readonly tools = [searchTool, summarizeTool]
+ *   override readonly tier: ModelTier = 'powerful'
+ * }
+ *
+ * const result = await brain.agent(ResearchAgent)
+ *   .input('What is the current state of bun.sql?')
+ *   .context({ userId: '01ABC...' })
+ *   .run()
+ * ```
+ *
+ * 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<T = never> {
+  /** System prompt — the persona / instructions Claude sees on every turn. */
+  abstract readonly instructions: string
+
+  /** Tools the agent can call. Empty array → the model answers without tools. */
+  readonly tools: readonly Tool[] = []
+
+  /**
+   * MCP servers exposed to the agent. Anthropic's backend connects
+   * to them and surfaces their tools to the model alongside any
+   * locally-registered `tools`. Empty array (or omitted) → no MCP
+   * servers; the agent runs with just `tools` (or no tools at all).
+   */
+  readonly mcpServers: readonly MCPServer[] = []
+
+  /** Override the configured default provider. Default = brain's default provider. */
+  readonly provider?: string
+
+  /** Explicit model ID. Wins over `tier`. */
+  readonly model?: string
+
+  /** Tier sugar. Default `'powerful'` for agentic work. */
+  readonly tier: ModelTier = 'powerful'
+
+  /**
+   * Safety ceiling on the agentic loop. Default `10`. Hitting it
+   * returns a result with `stopReason: 'max_iterations'`; the loop
+   * doesn't throw because partial progress (assistant messages, tool
+   * results) is usually still useful to surface.
+   */
+  readonly maxIterations: number = 10
+
+  /** 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,32 @@
+/**
+ * `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
+  /** See `ChatResult.responseId`. */
+  responseId?: string
+}

package/src/agent_result.ts

@@ -0,0 +1,39 @@
+/**
+ * `AgentResult` — what an agentic loop returns when it ends. Combines
+ * the final assistant `text`, the full message history (including
+ * tool calls + results so apps can render the trace), the total
+ * iteration count (how many tool-use round-trips the loop made),
+ * and aggregated token usage across every model call inside the
+ * loop.
+ *
+ * `stopReason` is the provider's terminal stop reason (typically
+ * `'end_turn'`). When the loop exits because it hit `maxIterations`,
+ * `stopReason` is `'max_iterations'` — distinct from the provider
+ * value so apps can detect "the model would have kept going."
+ */
+
+import type { ChatUsage, Message } from './types.ts'
+
+export interface AgentResult {
+  /** Concatenated text from the final assistant turn. */
+  text: string
+  /** Full message history of the loop, including tool_use / tool_result blocks. */
+  messages: Message[]
+  /** Number of tool-use rounds. `0` when the model answered without tools. */
+  iterations: number
+  /**
+   * Terminal stop reason. Either the provider's stop_reason (typically
+   * `'end_turn'`) or the framework-specific `'max_iterations'` when
+   * the loop hit its iteration ceiling.
+   */
+  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

@@ -0,0 +1,265 @@
+/**
+ * `AgentRunner` — fluent builder returned by `BrainManager.agent(Class)`.
+ *
+ * Carries the agent instance + an input message + an optional
+ * 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>
+ * ```
+ *
+ * Apps that need the full Message-array surface bypass the runner
+ * 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,
+  ToolUseBlock,
+} from './types.ts'
+import type { RunWithToolsOptions } from './brain_driver.ts'
+import type {
+  SuspendedRun,
+  SuspendedState,
+  ToolResultInput,
+} from './suspended_run.ts'
+
+/**
+ * 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>
+
+/**
+ * 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<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
+    return this
+  }
+
+  /**
+   * Attach context that every tool's `execute(input, ctx)` will see
+   * on `ctx.context`. Useful for per-request data the agent's tools
+   * need but the model shouldn't see directly (auth identity,
+   * tenant id, request-id for tracing).
+   */
+  context(data: Record<string, unknown>): this {
+    this.contextBag = { ...this.contextBag, ...data }
+    return this
+  }
+
+  /**
+   * 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 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) {
+      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
+    if (this.suspendGate !== undefined) options.shouldSuspend = this.suspendGate
+    const result = await this.brain.runTools(messages, this.agent.tools, options)
+    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 {
+    const options: ChatOptions = {
+      tier: this.agent.tier,
+      maxTokens: this.agent.maxTokens,
+      system: this.agent.instructions,
+    }
+    if (this.agent.model !== undefined) options.model = this.agent.model
+    if (this.agent.provider !== undefined) options.provider = this.agent.provider
+    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>