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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "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",
@@ -21,8 +21,9 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.100.0",
+    "@google/genai": "^2.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@strav/kernel": "1.0.0-alpha.12",
+    "@strav/kernel": "1.0.0-alpha.14",
     "openai": "^6.0.0"
   },
   "peerDependencies": {

package/src/brain_config.ts

@@ -49,7 +49,25 @@ export interface OpenAIProviderConfig {
   defaultMaxTokens?: number
 }
 
-export type ProviderConfig = AnthropicProviderConfig | OpenAIProviderConfig // | GoogleProviderConfig | DeepSeekProviderConfig (later slices)
+/** Google (Gemini) driver config — backed by `@google/genai`. */
+export interface GeminiProviderConfig {
+  driver: 'google'
+  /** API key. Required. Most apps source from `env('GOOGLE_API_KEY')` or `env('GEMINI_API_KEY')`. */
+  apiKey: string
+  /** Optional override of the SDK's base URL — useful for proxies or test doubles. */
+  baseUrl?: string
+  /** Default model when neither `options.model` nor `options.tier` is passed. Defaults to `gemini-2.5-flash`. */
+  defaultModel?: string
+  /** Default `max_tokens` for `chat()` calls that don't specify one. */
+  defaultMaxTokens?: number
+  /** Optional API version pin (`v1` / `v1beta`). */
+  apiVersion?: string
+}
+
+export type ProviderConfig =
+  | AnthropicProviderConfig
+  | OpenAIProviderConfig
+  | GeminiProviderConfig // | DeepSeekProviderConfig (later slice)
 
 /** Cache-shape defaults applied when `ChatOptions.cache` is omitted. */
 export interface BrainCacheConfig {

package/src/brain_manager.ts

@@ -22,12 +22,14 @@
 import type { Agent } from './agent.ts'
 import type { AgentResult } from './agent_result.ts'
 import type { MCPServer } from './mcp_server.ts'
+import type { OutputSchema } from './output_schema.ts'
 import { AgentRunner } from './agent_runner.ts'
 import { BrainError } from './brain_error.ts'
 import type { ModelTier } from './types.ts'
 import type {
   ChatOptions,
   ChatResult,
+  GenerateResult,
   Message,
   StreamEvent,
 } from './types.ts'
@@ -166,6 +168,32 @@ export class BrainManager {
     return provider.runWithTools(messages, tools, resolved)
   }
 
+  /**
+   * Structured output. Sends `input` to the configured (or
+   * `options.provider`-overridden) provider with the JSON-Schema
+   * constraint described by `schema`; returns the parsed object.
+   *
+   * Throws `BrainError` when the chosen provider doesn't implement
+   * `generate`. All three V1 providers (Anthropic, OpenAI, Gemini)
+   * do.
+   */
+  async generate<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const provider = this.provider(options.provider)
+    if (!provider.generate) {
+      throw new BrainError(
+        `BrainManager.generate: provider "${provider.name}" does not implement generate.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options)
+    return provider.generate<T>(messages, schema, resolved)
+  }
+
   /**
    * Resolve an `Agent` subclass from the container and return an
    * `AgentRunner` ready to receive `input(...)` and `run()`. Apps

package/src/brain_provider.ts

@@ -28,6 +28,7 @@ import { type Application, ConfigError, ConfigRepository, ServiceProvider } from
 import { BrainManager } from './brain_manager.ts'
 import type { BrainConfigShape, ProviderConfig } from './brain_config.ts'
 import { AnthropicProvider } from './providers/anthropic_provider.ts'
+import { GeminiProvider } from './providers/gemini_provider.ts'
 import { OpenAIProvider } from './providers/openai_provider.ts'
 import type { Provider } from './provider.ts'
 
@@ -101,10 +102,17 @@ function buildProvider(name: string, config: ProviderConfig): Provider {
         )
       }
       return new OpenAIProvider(name, config)
+    case 'google':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: google provider "${name}" is missing apiKey. Source from env('GOOGLE_API_KEY').`,
+        )
+      }
+      return new GeminiProvider(name, config)
     default: {
       const exhaustiveCheck: never = config
       throw new ConfigError(
-        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic, openai.`,
+        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic, openai, google.`,
       )
       // (unreachable — kept for the exhaustive check to fire when a new driver lands)
       // biome-ignore lint/correctness/noUnreachable: kept for the exhaustive-check above

package/src/index.ts

@@ -16,6 +16,7 @@ export {
   type BrainConfigShape,
   DEFAULT_MODEL,
   DEFAULT_TIERS,
+  type GeminiProviderConfig,
   type OpenAIProviderConfig,
   type ProviderConfig,
 } from './brain_config.ts'
@@ -28,7 +29,9 @@ export {
 export { BrainProvider } from './brain_provider.ts'
 export { defineTool, type DefineToolSpec } from './define_tool.ts'
 export type { MCPServer, MCPServerToolConfig } from './mcp_server.ts'
+export type { OutputSchema } from './output_schema.ts'
 export { AnthropicProvider } from './providers/anthropic_provider.ts'
+export { GeminiProvider } from './providers/gemini_provider.ts'
 export { OpenAIProvider } from './providers/openai_provider.ts'
 export type { Provider, RunWithToolsOptions } from './provider.ts'
 export { Thread, type ThreadOptions, type ThreadState } from './thread.ts'
@@ -39,6 +42,7 @@ export type {
   ChatResult,
   ChatUsage,
   ContentBlock,
+  GenerateResult,
   MCPToolResultBlock,
   MCPToolUseBlock,
   Message,

package/src/output_schema.ts

@@ -0,0 +1,72 @@
+/**
+ * `OutputSchema<T>` — declarative description of a structured-output
+ * target. Apps pass one of these to `BrainManager.generate(...)` and
+ * get back a `GenerateResult<T>` whose `value` is the parsed JSON
+ * the model produced.
+ *
+ * Schema shape:
+ *   - `name` — short identifier; OpenAI requires it on
+ *     `response_format.json_schema.name`. Other providers ignore it
+ *     but apps should still set something stable and meaningful for
+ *     logs / telemetry.
+ *   - `description` — optional hint the model sees (some providers
+ *     surface it next to the schema; others embed it in the prompt
+ *     translation).
+ *   - `jsonSchema` — plain JSON Schema (draft 2020-12 compatible).
+ *     The framework deliberately doesn't depend on Zod; apps that
+ *     want Zod use `zod-to-json-schema` (or similar) at the call
+ *     site and feed the result here.
+ *   - `parse` — optional runtime validator/parser. When set, the
+ *     framework runs every model response through it before
+ *     returning. Apps that just want type-level inference (and
+ *     trust the model + provider validation) can omit it; the
+ *     return type is then `T` by type assertion only.
+ *
+ * Why no built-in Zod dep:
+ *   Same reason `Tool.inputSchema` is plain JSON Schema — Strav
+ *   doesn't pin apps to a schema library. A thin `@strav/brain-zod`
+ *   helper that produces `OutputSchema<T>` from a Zod schema is
+ *   straightforward to ship later without touching this file.
+ */
+
+export interface OutputSchema<T = unknown> {
+  /** Short identifier — provider-specific; some surface it, others ignore. */
+  name: string
+  /** Optional hint shown to the model alongside the schema. */
+  description?: string
+  /** JSON Schema describing the expected shape. */
+  jsonSchema: Record<string, unknown>
+  /** Optional runtime parser/validator. Apps that use Zod plug it in here. */
+  parse?(value: unknown): T
+}
+
+/**
+ * Shared helper used by every provider's `generate` implementation:
+ * parse the raw JSON response, run the optional `parse` hook, and
+ * wrap parse failures in `BrainError` with the raw text on `.context`
+ * so apps can inspect what came back when validation rejects.
+ */
+import { BrainError } from './brain_error.ts'
+
+export function parseGenerated<T>(text: string, schema: OutputSchema<T>): T {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (cause) {
+    throw new BrainError(
+      `BrainProvider.generate: response was not valid JSON for schema "${schema.name}".`,
+      { context: { schema: schema.name, text }, cause },
+    )
+  }
+  if (schema.parse) {
+    try {
+      return schema.parse(parsed)
+    } catch (cause) {
+      throw new BrainError(
+        `BrainProvider.generate: response failed schema.parse for "${schema.name}".`,
+        { context: { schema: schema.name, text }, cause },
+      )
+    }
+  }
+  return parsed as T
+}

package/src/provider.ts

@@ -14,10 +14,12 @@
 
 import type { AgentResult } from './agent_result.ts'
 import type { MCPServer } from './mcp_server.ts'
+import type { OutputSchema } from './output_schema.ts'
 import type { Tool } from './tool.ts'
 import type {
   ChatOptions,
   ChatResult,
+  GenerateResult,
   Message,
   StreamEvent,
 } from './types.ts'
@@ -80,4 +82,21 @@ export interface Provider {
     tools: readonly Tool[],
     options?: RunWithToolsOptions,
   ): Promise<AgentResult>
+
+  /**
+   * Structured output. Sends `messages` to the model with a
+   * JSON-Schema constraint and returns the parsed object. Apps that
+   * supplied `schema.parse` get a runtime-validated value; otherwise
+   * the value is `T` by type assertion (the provider does its own
+   * upstream schema enforcement, but the framework doesn't validate).
+   *
+   * Optional on the interface so providers that lack a structured-
+   * output endpoint can omit it; `BrainManager.generate` throws a
+   * `BrainError` when the configured provider doesn't expose this.
+   */
+  generate?<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options?: ChatOptions,
+  ): Promise<GenerateResult<T>>
 }

package/src/providers/anthropic_provider.ts

@@ -35,6 +35,7 @@ import type {
   ChatResult,
   ChatUsage,
   ContentBlock,
+  GenerateResult,
   MCPToolResultBlock,
   MCPToolUseBlock,
   Message,
@@ -44,6 +45,7 @@ import type {
   ToolResultBlock,
   ToolUseBlock,
 } from '../types.ts'
+import { parseGenerated, type OutputSchema } from '../output_schema.ts'
 
 const EPHEMERAL_CACHE = { type: 'ephemeral' } as const
 
@@ -263,6 +265,29 @@ export class AnthropicProvider implements Provider {
     }
   }
 
+  async generate<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const params = this.buildParams(messages, options) as Anthropic.MessageCreateParamsNonStreaming
+    params.output_config = {
+      ...(params.output_config ?? {}),
+      format: { type: 'json_schema', schema: schema.jsonSchema },
+    }
+    const response = await this.client.messages.create(params)
+    const text = collectText(response.content)
+    const value = parseGenerated(text, schema)
+    return {
+      value,
+      text,
+      model: response.model,
+      stopReason: response.stop_reason,
+      usage: toUsage(response.usage),
+      raw: response,
+    }
+  }
+
   // ─── Param translation ──────────────────────────────────────────────────
 
   private buildParams(

package/src/providers/gemini_provider.ts

@@ -0,0 +1,472 @@
+/**
+ * `GeminiProvider` — implementation of `Provider` backed by the
+ * official `@google/genai` SDK (Gemini Developer API / Vertex AI).
+ *
+ * Maps framework shapes to Gemini's wire format:
+ *
+ *   - `system` → `config.systemInstruction` (string-joined when
+ *     multi-block). Cache flags on the system prompt are ignored —
+ *     Gemini's prompt caching uses an explicit Caches API rather
+ *     than per-block flags, so `cache: true` becomes a no-op
+ *     consistent with the OpenAI provider.
+ *
+ *   - `Message[]` → `Content[]`. Framework `role: 'user' | 'assistant'`
+ *     maps to Gemini's `role: 'user' | 'model'`. String content
+ *     becomes a single `{text}` part; `ContentBlock[]` content fans
+ *     out:
+ *       - `TextBlock`         → `{text}`
+ *       - `ToolUseBlock`      → `{functionCall: {id, name, args}}`
+ *       - `ToolResultBlock`   → `{functionResponse: {id, name,
+ *                                  response: {result | error}}}`
+ *       - `MCP*` blocks       → silently dropped (Anthropic-only).
+ *
+ *   - `Tool[]` → `[{functionDeclarations: [{name, description,
+ *     parametersJsonSchema: inputSchema}]}]`. We use
+ *     `parametersJsonSchema` (not `parameters`) so JSON-Schema-shaped
+ *     tool inputs pass through verbatim without translation to
+ *     Gemini's `Schema` form.
+ *
+ *   - `MCPServer[]` → resolved via the local MCP client
+ *     (`@strav/brain/mcp`). Discovered tools are namespaced
+ *     `<server>__<tool>` and merged with caller-supplied tools.
+ *     Transports are closed in a `finally` once the loop exits.
+ *     Gemini has no first-party server-side MCP equivalent to
+ *     Anthropic's connector.
+ *
+ *   - `thinking: 'adaptive'` → `thinkingConfig: { thinkingBudget: -1 }`
+ *     (auto). `'disabled'` → `thinkingConfig: { thinkingBudget: 0 }`.
+ *     Explicit `effort` (`low`/`medium`/`high`/`xhigh`/`max`) maps to
+ *     `thinkingConfig.thinkingLevel`. Non-thinking models ignore the
+ *     field upstream — we always emit, the SDK rejects only for
+ *     models that don't support it.
+ *
+ *   - `cache: true` → no-op. Gemini's prompt cache lives behind the
+ *     `Caches` API; same accepted-silently behavior as OpenAI.
+ *
+ *   - `countTokens` IS implemented — `ai.models.countTokens` exists
+ *     and is cheap. Returns `totalTokens`.
+ */
+
+import { GoogleGenAI, ThinkingLevel } from '@google/genai'
+import type {
+  Content,
+  FunctionDeclaration,
+  GenerateContentConfig,
+  GenerateContentParameters,
+  GenerateContentResponse,
+  Part,
+} from '@google/genai'
+import type { AgentResult } from '../agent_result.ts'
+import { BrainError } from '../brain_error.ts'
+import type { GeminiProviderConfig } from '../brain_config.ts'
+import type { MCPServer } from '../mcp_server.ts'
+import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
+import { parseGenerated, type OutputSchema } from '../output_schema.ts'
+import type { Provider, RunWithToolsOptions } from '../provider.ts'
+import type { Tool } from '../tool.ts'
+import { ToolExecutionError } from '../tool_execution_error.ts'
+import type {
+  ChatOptions,
+  ChatResult,
+  ChatUsage,
+  ContentBlock,
+  GenerateResult,
+  Message,
+  StreamEvent,
+  SystemPrompt,
+  TextBlock,
+  ToolResultBlock,
+  ToolUseBlock,
+} from '../types.ts'
+
+const DEFAULT_GEMINI_MODEL = 'gemini-2.5-flash'
+
+/**
+ * The slice of `GoogleGenAI` the provider exercises. Narrowed so
+ * tests can inject a stub without satisfying the full SDK surface.
+ */
+export interface GeminiModelsClient {
+  generateContent(params: GenerateContentParameters): Promise<GenerateContentResponse>
+  generateContentStream(
+    params: GenerateContentParameters,
+  ): Promise<AsyncIterable<GenerateContentResponse>>
+  countTokens(params: { model: string; contents: Content[] }): Promise<{ totalTokens?: number }>
+}
+
+export interface GeminiProviderOptions {
+  client?: { models: GeminiModelsClient }
+  /** Internal seam — tests inject a stub MCP client factory. */
+  mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
+}
+
+export class GeminiProvider implements Provider {
+  readonly name: string
+  private readonly models: GeminiModelsClient
+  private readonly defaultModel: string
+  private readonly defaultMaxTokens: number
+  private readonly mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
+
+  constructor(name: string, config: GeminiProviderConfig, options: GeminiProviderOptions = {}) {
+    this.name = name
+    this.defaultModel = config.defaultModel ?? DEFAULT_GEMINI_MODEL
+    this.defaultMaxTokens = config.defaultMaxTokens ?? 4096
+    this.mcpClientFactory = options.mcpClientFactory
+    if (options.client) {
+      this.models = options.client.models
+    } else {
+      const httpOpts =
+        config.baseUrl !== undefined || config.apiVersion !== undefined
+          ? {
+              ...(config.baseUrl !== undefined ? { baseUrl: config.baseUrl } : {}),
+              ...(config.apiVersion !== undefined ? { apiVersion: config.apiVersion } : {}),
+            }
+          : undefined
+      const sdk = new GoogleGenAI({
+        apiKey: config.apiKey,
+        ...(httpOpts ? { httpOptions: httpOpts } : {}),
+      })
+      this.models = sdk.models as unknown as GeminiModelsClient
+    }
+  }
+
+  async chat(messages: readonly Message[], options: ChatOptions = {}): Promise<ChatResult> {
+    const params = this.buildParams(messages, options, [])
+    const response = await this.models.generateContent(params)
+    return this.toChatResult(response, params.model)
+  }
+
+  async *stream(
+    messages: readonly Message[],
+    options: ChatOptions = {},
+  ): AsyncIterable<StreamEvent> {
+    const params = this.buildParams(messages, options, [])
+    const stream = await this.models.generateContentStream(params)
+    let finishReason: string | null = null
+    let lastUsage: ChatUsage | undefined
+    for await (const chunk of stream) {
+      const candidate = chunk.candidates?.[0]
+      const text = candidateText(candidate)
+      if (text.length > 0) yield { type: 'text', delta: text }
+      if (candidate?.finishReason) finishReason = String(candidate.finishReason)
+      if (chunk.usageMetadata) lastUsage = toUsage(chunk.usageMetadata)
+    }
+    yield {
+      type: 'stop',
+      stopReason: finishReason,
+      usage: lastUsage ?? {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+      },
+    }
+  }
+
+  async countTokens(messages: readonly Message[], options: ChatOptions = {}): Promise<number> {
+    const contents = this.toContents(messages)
+    const model = options.model ?? this.defaultModel
+    const response = await this.models.countTokens({ model, contents })
+    return response.totalTokens ?? 0
+  }
+
+  async runWithTools(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentResult> {
+    const mcpServers: readonly MCPServer[] = options.mcpServers ?? []
+    const resolved =
+      mcpServers.length > 0
+        ? await resolveMcpTools(mcpServers, {
+            ...(this.mcpClientFactory ? { clientFactory: this.mcpClientFactory } : {}),
+          })
+        : { tools: [] as Tool[], close: async () => {} }
+    try {
+      return await this._runLoop(messages, [...tools, ...resolved.tools], options)
+    } finally {
+      await resolved.close()
+    }
+  }
+
+  private async _runLoop(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions,
+  ): Promise<AgentResult> {
+    const maxIterations = options.maxIterations ?? 10
+    const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
+    const workingMessages: Message[] = [...messages]
+    const aggregated: ChatUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    }
+    let iterations = 0
+
+    while (true) {
+      const params = this.buildParams(workingMessages, options, tools)
+      const response = await this.models.generateContent(params)
+      addUsage(aggregated, response.usageMetadata)
+
+      const candidate = response.candidates?.[0]
+      if (!candidate) {
+        throw new BrainError('GeminiProvider: response had no candidates.')
+      }
+      const parts = candidate.content?.parts ?? []
+      const assistantContent = fromGeminiParts(parts)
+      workingMessages.push({ role: 'assistant', content: assistantContent })
+
+      const toolUses = (Array.isArray(assistantContent) ? assistantContent : []).filter(
+        (b): b is ToolUseBlock => b.type === 'tool_use',
+      )
+
+      if (toolUses.length === 0) {
+        return {
+          text: typeof assistantContent === 'string'
+            ? assistantContent
+            : candidateText(candidate),
+          messages: workingMessages,
+          iterations,
+          stopReason: candidate.finishReason ? String(candidate.finishReason) : 'stop',
+          usage: aggregated,
+        }
+      }
+
+      const resultBlocks: ContentBlock[] = []
+      for (const call of toolUses) {
+        const tool = toolMap.get(call.name)
+        if (!tool) {
+          throw new ToolExecutionError(
+            call.name,
+            call.id,
+            new Error(`Tool "${call.name}" is not registered.`),
+          )
+        }
+        let output: unknown
+        try {
+          output = await tool.execute(call.input, {
+            callId: call.id,
+            context: options.context ?? {},
+          })
+        } catch (cause) {
+          throw new ToolExecutionError(call.name, call.id, cause)
+        }
+        const resultBlock: ToolResultBlock = {
+          type: 'tool_result',
+          toolUseId: call.id,
+          content: typeof output === 'string' ? output : JSON.stringify(output),
+        }
+        resultBlocks.push(resultBlock)
+      }
+      workingMessages.push({ role: 'user', content: resultBlocks })
+
+      iterations++
+      if (iterations >= maxIterations) {
+        return {
+          text: candidateText(candidate),
+          messages: workingMessages,
+          iterations,
+          stopReason: 'max_iterations',
+          usage: aggregated,
+        }
+      }
+    }
+  }
+
+  async generate<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const params = this.buildParams(messages, options, [])
+    params.config = {
+      ...(params.config ?? {}),
+      responseMimeType: 'application/json',
+      responseJsonSchema: schema.jsonSchema,
+    }
+    const response = await this.models.generateContent(params)
+    const candidate = response.candidates?.[0]
+    const text = candidateText(candidate)
+    const value = parseGenerated(text, schema)
+    return {
+      value,
+      text,
+      model: response.modelVersion ?? params.model,
+      stopReason: candidate?.finishReason ? String(candidate.finishReason) : null,
+      usage: toUsage(response.usageMetadata),
+      raw: response,
+    }
+  }
+
+  // ─── Param translation ──────────────────────────────────────────────────
+
+  private buildParams(
+    messages: readonly Message[],
+    options: ChatOptions,
+    tools: readonly Tool[],
+  ): GenerateContentParameters {
+    const model = options.model ?? this.defaultModel
+    const contents = this.toContents(messages)
+    const config: GenerateContentConfig = {
+      maxOutputTokens: options.maxTokens ?? this.defaultMaxTokens,
+    }
+
+    const systemText = systemPromptText(options.system)
+    if (systemText.length > 0) {
+      config.systemInstruction = systemText
+    }
+
+    if (tools.length > 0) {
+      const functionDeclarations: FunctionDeclaration[] = tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parametersJsonSchema: t.inputSchema,
+      }))
+      config.tools = [{ functionDeclarations }]
+    }
+
+    const thinking = buildThinkingConfig(options)
+    if (thinking !== undefined) config.thinkingConfig = thinking
+
+    return { model, contents, config }
+  }
+
+  private toContents(messages: readonly Message[]): Content[] {
+    return messages.map((m) => ({
+      role: m.role === 'assistant' ? 'model' : 'user',
+      parts: toGeminiParts(m.content),
+    }))
+  }
+
+  private toChatResult(
+    response: GenerateContentResponse,
+    requestedModel: string,
+  ): ChatResult<GenerateContentResponse> {
+    const candidate = response.candidates?.[0]
+    return {
+      text: candidateText(candidate),
+      model: response.modelVersion ?? requestedModel,
+      stopReason: candidate?.finishReason ? String(candidate.finishReason) : null,
+      usage: toUsage(response.usageMetadata),
+      raw: response,
+    }
+  }
+}
+
+// ─── Shape converters ─────────────────────────────────────────────────────
+
+function systemPromptText(system: SystemPrompt | undefined): string {
+  if (system === undefined) return ''
+  if (typeof system === 'string') return system
+  if (Array.isArray(system)) return system.map((b) => b.text).join('\n')
+  return system.text
+}
+
+function toGeminiParts(content: string | ContentBlock[]): Part[] {
+  if (typeof content === 'string') return [{ text: content }]
+  const parts: Part[] = []
+  for (const block of content) {
+    if (block.type === 'text') {
+      parts.push({ text: block.text })
+    } else if (block.type === 'tool_use') {
+      parts.push({
+        functionCall: {
+          id: block.id,
+          name: block.name,
+          args: (block.input ?? {}) as Record<string, unknown>,
+        },
+      })
+    } else if (block.type === 'tool_result') {
+      const text = typeof block.content === 'string'
+        ? block.content
+        : block.content.map((t) => t.text).join('')
+      parts.push({
+        functionResponse: {
+          id: block.toolUseId,
+          name: '',
+          response: block.isError ? { error: text } : { result: text },
+        },
+      })
+    }
+    // MCP blocks (Anthropic-only) silently dropped.
+  }
+  return parts
+}
+
+function fromGeminiParts(parts: readonly Part[]): string | ContentBlock[] {
+  const blocks: ContentBlock[] = []
+  for (const part of parts) {
+    if (typeof part.text === 'string' && part.text.length > 0) {
+      blocks.push({ type: 'text', text: part.text })
+    } else if (part.functionCall) {
+      const fc = part.functionCall
+      blocks.push({
+        type: 'tool_use',
+        id: fc.id ?? `gemini_${cryptoRandomId()}`,
+        name: fc.name ?? '',
+        input: fc.args ?? {},
+      } satisfies ToolUseBlock)
+    }
+  }
+  if (blocks.length === 1 && blocks[0]?.type === 'text') return blocks[0].text
+  return blocks
+}
+
+function candidateText(candidate: { content?: { parts?: Part[] } } | undefined): string {
+  const parts = candidate?.content?.parts ?? []
+  return parts
+    .filter((p) => typeof p.text === 'string' && p.text.length > 0)
+    .map((p) => p.text as string)
+    .join('')
+}
+
+function buildThinkingConfig(options: ChatOptions): GenerateContentConfig['thinkingConfig'] {
+  if (options.effort !== undefined) {
+    const level = effortToThinkingLevel(options.effort)
+    return level !== undefined ? { thinkingLevel: level } : { thinkingBudget: -1 }
+  }
+  if (options.thinking === 'adaptive') return { thinkingBudget: -1 }
+  if (options.thinking === 'disabled') return { thinkingBudget: 0 }
+  return undefined
+}
+
+function effortToThinkingLevel(
+  effort: NonNullable<ChatOptions['effort']>,
+): ThinkingLevel | undefined {
+  switch (effort) {
+    case 'low': return ThinkingLevel.LOW
+    case 'medium': return ThinkingLevel.MEDIUM
+    case 'high':
+    case 'xhigh':
+    case 'max':
+      return ThinkingLevel.HIGH
+  }
+}
+
+function toUsage(u: { promptTokenCount?: number; candidatesTokenCount?: number; cachedContentTokenCount?: number } | undefined): ChatUsage {
+  return {
+    inputTokens: u?.promptTokenCount ?? 0,
+    outputTokens: u?.candidatesTokenCount ?? 0,
+    cacheReadTokens: u?.cachedContentTokenCount ?? 0,
+    cacheCreationTokens: 0,
+  }
+}
+
+function addUsage(
+  acc: ChatUsage,
+  u: { promptTokenCount?: number; candidatesTokenCount?: number; cachedContentTokenCount?: number } | undefined,
+): void {
+  if (!u) return
+  acc.inputTokens += u.promptTokenCount ?? 0
+  acc.outputTokens += u.candidatesTokenCount ?? 0
+  acc.cacheReadTokens += u.cachedContentTokenCount ?? 0
+}
+
+function cryptoRandomId(): string {
+  // Stable, low-entropy fallback for synthesizing tool-use ids when
+  // Gemini omits them. Uniqueness within a single response is all the
+  // loop requires — the id only travels back paired with its result
+  // and never escapes to the caller.
+  return Math.random().toString(36).slice(2, 12)
+}

package/src/providers/openai_provider.ts

@@ -53,6 +53,7 @@ import { BrainError } from '../brain_error.ts'
 import type { OpenAIProviderConfig } from '../brain_config.ts'
 import type { MCPServer } from '../mcp_server.ts'
 import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
+import { parseGenerated, type OutputSchema } from '../output_schema.ts'
 import type { Provider, RunWithToolsOptions } from '../provider.ts'
 import type { Tool } from '../tool.ts'
 import { ToolExecutionError } from '../tool_execution_error.ts'
@@ -61,6 +62,7 @@ import type {
   ChatResult,
   ChatUsage,
   ContentBlock,
+  GenerateResult,
   Message,
   StreamEvent,
   SystemPrompt,
@@ -257,6 +259,35 @@ export class OpenAIProvider implements Provider {
     }
   }
 
+  async generate<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const params = this.buildParams(messages, options, [])
+    params.response_format = {
+      type: 'json_schema',
+      json_schema: {
+        name: schema.name,
+        ...(schema.description !== undefined ? { description: schema.description } : {}),
+        schema: schema.jsonSchema,
+        strict: true,
+      },
+    }
+    const response = await this.client.chat.completions.create(params)
+    const choice = response.choices[0]
+    const text = choice?.message?.content ?? ''
+    const value = parseGenerated(text, schema)
+    return {
+      value,
+      text,
+      model: response.model,
+      stopReason: choice?.finish_reason ?? null,
+      usage: toUsage(response.usage),
+      raw: response,
+    }
+  }
+
   // ─── Param translation ──────────────────────────────────────────────────
 
   private buildParams(

package/src/types.ts

@@ -200,3 +200,18 @@ export interface ChatResult<Raw = unknown> {
 export type StreamEvent =
   | { type: 'text'; delta: string }
   | { type: 'stop'; stopReason: string | null; usage: ChatUsage }
+
+/**
+ * Result of a structured-output call. `value` is the parsed JSON
+ * shaped to the `OutputSchema<T>` passed in. `text` is the raw JSON
+ * string the model produced (useful for logging / debugging when
+ * `parse` rejects). `raw` is the provider's full native response.
+ */
+export interface GenerateResult<T = unknown, Raw = unknown> {
+  value: T
+  text: string
+  model: string
+  stopReason: string | null
+  usage: ChatUsage
+  raw: Raw
+}