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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.15",
+  "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",
@@ -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.16",
     "openai": "^6.0.0"
   },
   "peerDependencies": {

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,