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

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.14",
+  "version": "1.0.0-alpha.16",
   "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",
-    "./mcp": "./src/mcp/index.ts"
+    "./mcp": "./src/mcp/index.ts",
+    "./zod": "./src/zod/index.ts"
   },
   "files": [
     "src",
@@ -23,11 +24,19 @@
     "@anthropic-ai/sdk": "^0.100.0",
     "@google/genai": "^2.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@strav/kernel": "1.0.0-alpha.14",
+    "@strav/kernel": "1.0.0-alpha.16",
     "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_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,24 +2,49 @@
  * `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 { 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,
@@ -43,21 +68,79 @@ 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>
+  }
+
+  async run(): Promise<AgentRunResult<T>> {
     if (this.prompt === undefined) {
-      throw new Error('AgentRunner.run: input() must be called before run().')
+      throw new BrainError('AgentRunner.run: input() must be called before run().')
     }
     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 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/index.ts

@@ -8,8 +8,9 @@
 // tools, structured outputs, other providers.
 
 export { Agent } from './agent.ts'
+export type { AgentGenerateResult } from './agent_generate_result.ts'
 export type { AgentResult } from './agent_result.ts'
-export { AgentRunner } from './agent_runner.ts'
+export { AgentRunner, type AgentRunResult } from './agent_runner.ts'
 export {
   type AnthropicProviderConfig,
   type BrainCacheConfig,

package/src/zod/index.ts

@@ -0,0 +1,121 @@
+/**
+ * `@strav/brain/zod` — Zod-flavored helpers on top of the
+ * schema-library-agnostic core.
+ *
+ * The default `@strav/brain` import deliberately doesn't depend on
+ * Zod — `Tool.inputSchema` and `OutputSchema.jsonSchema` are plain
+ * JSON Schema so apps stay free to pick Ajv, Valibot, ArkType, or
+ * nothing at all. This sub-path opt-in adds two thin wrappers for
+ * apps that already use Zod:
+ *
+ *   - `outputSchema(z, opts?)` turns a Zod schema into an
+ *     `OutputSchema<z.infer<typeof z>>` — `jsonSchema` is derived
+ *     via Zod's built-in `z.toJSONSchema`, and `parse` is wired to
+ *     `z.parse`. Apps then pass the result straight to
+ *     `BrainManager.generate(input, schema)`.
+ *
+ *   - `tool({ name, description, input, execute })` turns a Zod
+ *     schema for the tool's input into a framework `Tool` — the
+ *     wrapper validates the model's raw input through the Zod
+ *     schema before calling the app's `execute`. Apps get inferred
+ *     types on `execute(input)` for free.
+ *
+ * `zod` is an optional peer dependency. Apps that don't use Zod
+ * don't install it, don't bundle it, and never import this
+ * sub-path — they keep using `defineTool` / hand-written
+ * `OutputSchema` literals with raw JSON Schema.
+ */
+
+import { z } from 'zod'
+import type { OutputSchema } from '../output_schema.ts'
+import type { Tool, ToolContext } from '../tool.ts'
+
+/**
+ * Options for `outputSchema`. `name` defaults to `'output'` —
+ * apps that surface multiple schemas in logs or to OpenAI's wire
+ * format should pass a stable, descriptive identifier.
+ */
+export interface OutputSchemaOptions {
+  /** Identifier — defaults to `'output'`. */
+  name?: string
+  /** Optional model-facing hint. Defaults to the Zod schema's `.describe(…)` if set. */
+  description?: string
+}
+
+/**
+ * Build an `OutputSchema<T>` from a Zod schema. The returned shape
+ * is ready to pass to `BrainManager.generate(...)`.
+ *
+ * ```ts
+ * const CityZ = z.object({ city: z.string(), population: z.number().int() })
+ * const { value } = await brain.generate('Capital of France?', outputSchema(CityZ, { name: 'city_answer' }))
+ * //      ^? { city: string; population: number }
+ * ```
+ */
+export function outputSchema<T>(
+  schema: z.ZodType<T>,
+  options: OutputSchemaOptions = {},
+): OutputSchema<T> {
+  const description = options.description ?? zodDescription(schema)
+  const result: OutputSchema<T> = {
+    name: options.name ?? 'output',
+    jsonSchema: z.toJSONSchema(schema) as Record<string, unknown>,
+    parse: (value) => schema.parse(value),
+  }
+  if (description !== undefined) result.description = description
+  return result
+}
+
+/**
+ * Spec passed to `tool(...)`. `execute` receives the model's input
+ * already validated + typed against `input` — no need to call
+ * `input.parse` manually.
+ */
+export interface ZodToolSpec<TInput, TOutput> {
+  name: string
+  description: string
+  input: z.ZodType<TInput>
+  execute(input: TInput, ctx: ToolContext): Promise<TOutput>
+}
+
+/**
+ * Build a framework `Tool` from a Zod-typed spec. The wrapper
+ * derives `inputSchema` via `z.toJSONSchema` and validates the
+ * model's raw input through `input.parse` before delegating to
+ * `execute`. Validation failures propagate as `ZodError`; the
+ * agentic loop wraps that into a `ToolExecutionError`.
+ *
+ * ```ts
+ * const search = tool({
+ *   name: 'search_orders',
+ *   description: 'Look up an order by id.',
+ *   input: z.object({ orderId: z.string() }),
+ *   async execute({ orderId }, ctx) {
+ *     //         ^? { orderId: string }
+ *     return await orders.find(orderId, ctx.context)
+ *   },
+ * })
+ * ```
+ */
+export function tool<TInput, TOutput>(
+  spec: ZodToolSpec<TInput, TOutput>,
+): Tool<TInput, TOutput> {
+  const jsonSchema = z.toJSONSchema(spec.input) as Record<string, unknown>
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema: jsonSchema,
+    async execute(raw: TInput, ctx: ToolContext): Promise<TOutput> {
+      const parsed = spec.input.parse(raw)
+      return spec.execute(parsed, ctx)
+    },
+  }
+}
+
+function zodDescription(schema: z.ZodType<unknown>): string | undefined {
+  // Zod stores `.describe(…)` on the schema's `_def`; surface it
+  // as the model-facing hint when callers don't pass one
+  // explicitly.
+  const def = (schema as unknown as { description?: string }).description
+  return typeof def === 'string' && def.length > 0 ? def : undefined
+}