@strav/brain 1.0.0-alpha.8 → 1.0.1

package/src/brain_manager.ts

@@ -1,7 +1,7 @@
 /**
  * `BrainManager` — the per-app facade apps inject and call.
  *
- * Holds the configured `Provider` registry + the default-provider key
+ * Holds the configured `BrainDriver` registry + the default-provider key
  * + the tier-to-model map. Apps call `chat / stream / countTokens`
  * with framework-native types; the manager resolves which provider
  * runs the call (default unless `options.provider` overrides),
@@ -19,33 +19,63 @@
  * ```
  */
 
+import type { Agent } from './agent.ts'
+import type { AgentResult } from './agent_result.ts'
+import type { AgentStreamEvent } from './agent_stream_event.ts'
+import type { MCPServer } from './mcp_server.ts'
+import type { AgentGenerateResult } from './agent_generate_result.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 {
+  AudioSource,
   ChatOptions,
   ChatResult,
+  EmbedOptions,
+  EmbedResult,
+  GenerateResult,
   Message,
   StreamEvent,
+  TranscribeOptions,
+  TranscribeResult,
 } from './types.ts'
-import type { Provider } from './provider.ts'
+import type {
+  BrainDriver,
+  RunWithToolsOptions,
+  RunWithToolsOptionsWithSuspend,
+} from './brain_driver.ts'
+import { appendResumeResults, type SuspendedRun, type SuspendedState, type ToolResultInput } from './suspended_run.ts'
+import type { Tool } from './tool.ts'
 import { DEFAULT_TIERS } from './brain_config.ts'
 
+/** Container-aware Agent constructor resolver — `BrainProvider` installs one wired to `app.resolve(...)`. */
+export type AgentResolver = <A extends Agent<unknown>>(cls: new (...args: never[]) => A) => A
+
 export interface BrainManagerOptions {
   /** Name of the default provider — must exist in `providers`. */
   default: string
   /** Provider registry keyed by name. */
-  providers: Record<string, Provider>
+  providers: Record<string, BrainDriver>
   /** Tier-to-model overrides; merged on top of the framework defaults. */
   tiers?: Partial<Record<ModelTier, string>>
   /** Default for `ChatOptions.cache` when the call site doesn't pass one. */
   defaultCache?: boolean
+  /**
+   * Default MCP servers used on every `runTools` call when the per-call
+   * options don't specify them. Per-call `mcpServers` replaces the
+   * default outright (no merge) — apps that want additive behavior
+   * concat at the call site.
+   */
+  defaultMcpServers?: readonly MCPServer[]
 }
 
 export class BrainManager {
   readonly defaultProvider: string
-  private readonly providers: Map<string, Provider>
+  private readonly providers: Map<string, BrainDriver>
   private readonly tiers: Record<ModelTier, string>
   private readonly defaultCache: boolean
+  private readonly defaultMcpServers: readonly MCPServer[]
 
   constructor(options: BrainManagerOptions) {
     if (!options.providers[options.default]) {
@@ -58,10 +88,11 @@ export class BrainManager {
     this.providers = new Map(Object.entries(options.providers))
     this.tiers = { ...DEFAULT_TIERS, ...(options.tiers ?? {}) }
     this.defaultCache = options.defaultCache ?? false
+    this.defaultMcpServers = options.defaultMcpServers ?? []
   }
 
   /** Resolve a provider by name. Default when no name passed. Throws when unknown. */
-  provider(name?: string): Provider {
+  provider(name?: string): BrainDriver {
     const key = name ?? this.defaultProvider
     const provider = this.providers.get(key)
     if (!provider) {
@@ -72,6 +103,29 @@ export class BrainManager {
     return provider
   }
 
+  /**
+   * Register an additional provider after construction. Apps that
+   * wire a custom adapter (a fine-tuned model server, a fork of
+   * Anthropic with extra knobs, an internal LLM) use this to add it
+   * to the registry without going through `config.brain.providers`.
+   *
+   * Overwrites any existing provider under the same name.
+   *
+   * ```ts
+   * brain.extend('internal', new InternalLlmProvider({ baseUrl }))
+   * const reply = await brain.chat(messages, { provider: 'internal' })
+   * ```
+   *
+   * Mirrors `RagManager.extend(name, factory)` / `PaymentManager.extend(name, factory)`
+   * — the OCP escape hatch every multi-driver Strav manager exposes.
+   */
+  extend(name: string, provider: BrainDriver): void {
+    if (!name) {
+      throw new BrainError('BrainManager.extend: provider name must be a non-empty string.')
+    }
+    this.providers.set(name, provider)
+  }
+
   /**
    * One-shot chat: send the messages, await the full reply.
    *
@@ -117,8 +171,305 @@ export class BrainManager {
     return provider.countTokens(messages, resolved)
   }
 
+  /**
+   * Run an agentic loop: send `messages` + `tools` to the model;
+   * execute any tool the model calls; loop until the model returns
+   * a terminal `stop_reason` (`'end_turn'`) or `maxIterations` is hit.
+   *
+   * Throws `BrainError` when the configured provider doesn't
+   * implement `runWithTools` (V1: OpenAI / Gemini / DeepSeek providers
+   * don't yet — only `AnthropicBrainDriver`).
+   */
+  runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptionsWithSuspend,
+  ): Promise<AgentResult | SuspendedRun>
+  runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options?: RunWithToolsOptions,
+  ): Promise<AgentResult>
+  async runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentResult | SuspendedRun> {
+    const provider = this.provider(options.provider)
+    if (!provider.runWithTools) {
+      throw new BrainError(
+        `BrainManager.runTools: provider "${provider.name}" does not implement runWithTools. Use a provider that supports tool use (V1: Anthropic).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    // MCP defaults — per-call override (when present) replaces the
+    // configured list outright; apps that want concat behavior
+    // construct the merged array themselves and pass it in.
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.runWithTools(messages, tools, resolved)
+  }
+
+  /**
+   * Resume a previously-suspended tool-use loop. Takes the
+   * `SuspendedRun.state` snapshot plus the results the integrator
+   * gathered for each `pendingToolCalls` entry; appends a `tool_result`
+   * block per entry; re-enters `runTools` so the model can continue
+   * (potentially suspending again on the next tool).
+   *
+   * Mid-batch invariant: every pending call MUST get a result —
+   * otherwise the provider rejects the next request because the
+   * assistant turn's `tool_use` blocks are no longer balanced.
+   * `resumeTools` throws `BrainError` when results are missing.
+   *
+   * The `previousResponseId` carried on the snapshot (when the
+   * provider supports stateful conversations) is threaded back via
+   * `options.previousResponseId` automatically — per-call
+   * `options.previousResponseId` wins if supplied explicitly.
+   */
+  async resumeTools(
+    state: SuspendedState,
+    results: readonly ToolResultInput[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentResult | SuspendedRun> {
+    const resumed = appendResumeResults(state, results)
+    const merged: RunWithToolsOptions = { ...options }
+    if (merged.previousResponseId === undefined && state.responseId !== undefined) {
+      merged.previousResponseId = state.responseId
+    }
+    const out = await this.runTools(
+      resumed,
+      tools,
+      merged as RunWithToolsOptionsWithSuspend,
+    )
+    return mergeResumeCounters(out, state)
+  }
+
+  /**
+   * Streaming variant of `generateWithTools`. Yields
+   * `AgentStreamEvent<T>`s as the loop progresses; the terminal
+   * `stop` event carries the parsed value + raw JSON text. Throws
+   * `BrainError` when the provider lacks
+   * `streamWithToolsAndSchema` (V1: all three providers
+   * implement it).
+   */
+  streamGenerateWithTools<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent<T>> {
+    rejectShouldSuspend(options, 'streamGenerateWithTools')
+    const provider = this.provider(options.provider)
+    if (!provider.streamWithToolsAndSchema) {
+      throw new BrainError(
+        `BrainManager.streamGenerateWithTools: provider "${provider.name}" does not implement streamWithToolsAndSchema.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.streamWithToolsAndSchema<T>(messages, tools, schema, resolved)
+  }
+
+  /**
+   * Tool-loop + structured output combined. Runs the agentic loop
+   * with the supplied `tools` while pinning the output to `schema`
+   * on every turn; returns the parsed value when the model finally
+   * answers without calling a tool. MCP defaults + tier resolution
+   * + provider routing match `runTools` / `generate`.
+   *
+   * Throws `BrainError` when the chosen provider doesn't implement
+   * `runWithToolsAndSchema`. V1: all three providers do.
+   */
+  async generateWithTools<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentGenerateResult<T>> {
+    rejectShouldSuspend(options, 'generateWithTools')
+    const provider = this.provider(options.provider)
+    if (!provider.runWithToolsAndSchema) {
+      throw new BrainError(
+        `BrainManager.generateWithTools: provider "${provider.name}" does not implement runWithToolsAndSchema.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.runWithToolsAndSchema<T>(messages, tools, schema, resolved)
+  }
+
+  /**
+   * Streaming variant of `runTools`. Yields `AgentStreamEvent`s
+   * as the agentic loop progresses — text deltas during model
+   * turns, `tool_use` / `tool_result` boundaries around tool
+   * execution, `iteration_start` / `iteration_end` per round, a
+   * terminal `stop` with the full trace + usage.
+   *
+   * Throws `BrainError` when the configured provider doesn't
+   * implement `streamWithTools`.
+   */
+  streamTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent> {
+    rejectShouldSuspend(options, 'streamTools')
+    const provider = this.provider(options.provider)
+    if (!provider.streamWithTools) {
+      throw new BrainError(
+        `BrainManager.streamTools: provider "${provider.name}" does not implement streamWithTools.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.streamWithTools(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)
+  }
+
+  /**
+   * Turn one or more text inputs into embedding vectors. Accepts
+   * either a single string (returns one vector) or an array
+   * (batch — returns one vector per input in the same order).
+   *
+   * Throws `BrainError` when the configured (or
+   * `options.provider`-overridden) provider doesn't implement
+   * `embed`. V1: OpenAI, Gemini, Ollama support it; Anthropic +
+   * DeepSeek throw with a clear "route to a different provider"
+   * message.
+   */
+  async embed(
+    input: string | readonly string[],
+    options: EmbedOptions = {},
+  ): Promise<EmbedResult> {
+    const provider = this.provider(options.provider)
+    if (!provider.embed) {
+      throw new BrainError(
+        `BrainManager.embed: provider "${provider.name}" does not implement embed. Route to a provider with an embeddings API (V1: OpenAI / Gemini / Ollama).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const texts = typeof input === 'string' ? [input] : input
+    return provider.embed(texts, options)
+  }
+
+  /**
+   * Transcribe one audio clip to text. Complements `AudioBlock`
+   * (which sends audio + a text prompt together to a multimodal
+   * chat model) by exposing the dedicated transcription endpoint
+   * where the provider has one. Apps that already have an
+   * `AudioBlock` can pass its `source` directly.
+   *
+   * Throws `BrainError` when the configured (or
+   * `options.provider`-overridden) provider doesn't implement
+   * `transcribe`. V1: OpenAI / Ollama (Whisper / gpt-4o-transcribe
+   * / local) and Gemini (chat-wrap fallback); Anthropic +
+   * DeepSeek throw.
+   */
+  async transcribe(
+    audio: AudioSource,
+    options: TranscribeOptions = {},
+  ): Promise<TranscribeResult> {
+    const provider = this.provider(options.provider)
+    if (!provider.transcribe) {
+      throw new BrainError(
+        `BrainManager.transcribe: provider "${provider.name}" does not implement transcribe. Route to a provider with audio support (V1: OpenAI / Ollama / Gemini).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    return provider.transcribe(audio, options)
+  }
+
+  /**
+   * Resolve an `Agent` subclass from the container and return an
+   * `AgentRunner` ready to receive `input(...)` and `run()`. Apps
+   * `@inject()`-decorate their Agent subclass so constructor
+   * injection of dependencies (Repositories, services, etc.) flows
+   * through normally.
+   *
+   * When the agent subclass extends `Agent<T>` for some `T` and
+   * declares `outputSchema`, the returned runner is typed as
+   * `AgentRunner<T>` and the schema is pre-applied — `.run()`
+   * returns `AgentGenerateResult<T>` without a per-call
+   * `.output(schema)`. Apps can still chain `.output(otherSchema)`
+   * to override.
+   */
+  agent<T = never>(
+    AgentClass: new (...args: never[]) => Agent<T>,
+    instance?: Agent<T>,
+  ): AgentRunner<T> {
+    const agent = instance ?? this.resolveAgent(AgentClass)
+    const runner = new AgentRunner<T>(this, agent)
+    if (agent.outputSchema !== undefined) {
+      return runner.output(agent.outputSchema)
+    }
+    return runner
+  }
+
   // ─── Internal ────────────────────────────────────────────────────────────
 
+  private resolveAgent<A extends Agent<unknown>>(AgentClass: new (...args: never[]) => A): A {
+    if (this.agentResolver) return this.agentResolver(AgentClass)
+    // Fallback: assume the Agent class is constructible without args.
+    // Apps that need DI on the agent register a resolver via
+    // `setAgentResolver` (BrainProvider wires this to the container).
+    return new (AgentClass as unknown as new () => A)()
+  }
+
+  /**
+   * Internal — `BrainProvider` calls this at boot to plug in the
+   * container's resolution function so `brain.agent(MyAgent)` runs
+   * `app.resolve(MyAgent)` under the hood. Apps that build a
+   * `BrainManager` by hand for tests can leave this unset and pass
+   * a pre-constructed agent to `brain.agent(_, instance)`.
+   */
+  setAgentResolver(resolver: AgentResolver): void {
+    this.agentResolver = resolver
+  }
+
+  private agentResolver: AgentResolver | undefined
+
   private applyDefaults(options: ChatOptions): ChatOptions {
     const resolved: ChatOptions = { ...options }
     if (resolved.model === undefined && resolved.tier !== undefined) {
@@ -137,3 +488,66 @@ function normalizeInput(input: string | readonly Message[]): readonly Message[]
   }
   return input
 }
+
+/**
+ * V1 scope guard. `shouldSuspend` is wired only into the non-
+ * streaming `runWithTools` loop; the streaming and schema variants
+ * don't yet model pause / resume, so silently ignoring would be
+ * worse than throwing. Apps that need both should run tools first
+ * (suspending as needed), then call `generate` for the structured
+ * summary in a separate step.
+ */
+/**
+ * Carry forward the pre-suspension iteration count + token usage so
+ * `result.iterations` / `result.usage` reflect the full run, not
+ * just the post-resume portion. When the resumed call suspends
+ * again, the new state's iterations + usage also get the carry-
+ * forward so apps see a running total across an arbitrary number
+ * of suspension cycles.
+ */
+function mergeResumeCounters(
+  out: AgentResult | SuspendedRun,
+  state: SuspendedState,
+): AgentResult | SuspendedRun {
+  // +1 accounts for the suspended round itself — at suspension time
+  // the loop hadn't yet incremented `iterations` (we paused mid-
+  // batch, before tool execution). Supplying results to resume
+  // effectively completes that round.
+  const carryIter = state.iterations + 1
+  if ('status' in out) {
+    return {
+      ...out,
+      state: {
+        ...out.state,
+        iterations: out.state.iterations + carryIter,
+        usage: addUsage(out.state.usage, state.usage),
+      },
+    }
+  }
+  return {
+    ...out,
+    iterations: out.iterations + carryIter,
+    usage: addUsage(out.usage, state.usage),
+  }
+}
+
+function addUsage(
+  a: SuspendedState['usage'],
+  b: SuspendedState['usage'],
+): SuspendedState['usage'] {
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+  }
+}
+
+function rejectShouldSuspend(options: RunWithToolsOptions, entry: string): void {
+  if (options.shouldSuspend !== undefined) {
+    throw new BrainError(
+      `BrainManager.${entry}: \`shouldSuspend\` is only supported on \`runTools\` (the non-streaming + no-schema entrypoint) in V1. Run tools first with suspension, then call \`generate\` for the structured summary as a separate step.`,
+      { context: { entry } },
+    )
+  }
+}

package/src/brain_provider.ts

@@ -25,10 +25,18 @@
  */
 
 import { type Application, ConfigError, ConfigRepository, ServiceProvider } from '@strav/kernel'
-import { BrainManager } from './brain_manager.ts'
 import type { BrainConfigShape, ProviderConfig } from './brain_config.ts'
-import { AnthropicProvider } from './providers/anthropic_provider.ts'
-import type { Provider } from './provider.ts'
+import type { BrainDriver } from './brain_driver.ts'
+import { BrainManager } from './brain_manager.ts'
+import { AnthropicBrainDriver } from './drivers/anthropic/anthropic_brain_driver.ts'
+import { DeepSeekBrainDriver } from './drivers/deepseek/deepseek_brain_driver.ts'
+import { GeminiBrainDriver } from './drivers/gemini/gemini_brain_driver.ts'
+import { MiniMaxBrainDriver } from './drivers/minimax/minimax_brain_driver.ts'
+import { OllamaBrainDriver } from './drivers/ollama/ollama_brain_driver.ts'
+import { OpenAIBrainDriver } from './drivers/openai/openai_brain_driver.ts'
+import { OpenAIResponsesBrainDriver } from './drivers/openai_responses/openai_responses_brain_driver.ts'
+import { OpenRouterBrainDriver } from './drivers/openrouter/openrouter_brain_driver.ts'
+import { QwenBrainDriver } from './drivers/qwen/qwen_brain_driver.ts'
 
 export class BrainProvider extends ServiceProvider {
   override readonly name = 'brain'
@@ -53,9 +61,9 @@ export class BrainProvider extends ServiceProvider {
         )
       }
 
-      const providers: Record<string, Provider> = {}
+      const providers: Record<string, BrainDriver> = {}
       for (const [name, entry] of Object.entries(config.providers)) {
-        providers[name] = buildProvider(name, entry)
+        providers[name] = buildBrainDriver(name, entry)
       }
 
       const options: ConstructorParameters<typeof BrainManager>[0] = {
@@ -64,7 +72,17 @@ export class BrainProvider extends ServiceProvider {
       }
       if (config.tiers !== undefined) options.tiers = config.tiers
       if (config.cache?.auto !== undefined) options.defaultCache = config.cache.auto
-      return new BrainManager(options)
+      if (config.mcpServers !== undefined) options.defaultMcpServers = config.mcpServers
+      const manager = new BrainManager(options)
+      // Plug in the container so `brain.agent(MyAgent)` resolves
+      // its constructor deps through `@inject()` like every other
+      // injected class. The variance widening at the boundary
+      // (`never[]` ↔ `any[]`) is purely a TS typing artifact — the
+      // container call is identical to a direct `c.resolve(MyAgent)`.
+      manager.setAgentResolver(<A>(cls: new (...args: never[]) => A) =>
+        c.resolve(cls as unknown as new (...args: unknown[]) => A),
+      )
+      return manager
     })
   }
 
@@ -74,7 +92,7 @@ export class BrainProvider extends ServiceProvider {
   }
 }
 
-function buildProvider(name: string, config: ProviderConfig): Provider {
+function buildBrainDriver(name: string, config: ProviderConfig): BrainDriver {
   switch (config.driver) {
     case 'anthropic':
       if (!config.apiKey) {
@@ -82,10 +100,71 @@ function buildProvider(name: string, config: ProviderConfig): Provider {
           `BrainProvider: anthropic provider "${name}" is missing apiKey. Source from env('ANTHROPIC_API_KEY').`,
         )
       }
-      return new AnthropicProvider(name, config)
-    default:
+      return new AnthropicBrainDriver(name, config)
+    case 'openai':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openai provider "${name}" is missing apiKey. Source from env('OPENAI_API_KEY').`,
+        )
+      }
+      return new OpenAIBrainDriver(name, config)
+    case 'openai-responses':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openai-responses provider "${name}" is missing apiKey. Source from env('OPENAI_API_KEY').`,
+        )
+      }
+      return new OpenAIResponsesBrainDriver(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 GeminiBrainDriver(name, config)
+    case 'deepseek':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: deepseek provider "${name}" is missing apiKey. Source from env('DEEPSEEK_API_KEY').`,
+        )
+      }
+      return new DeepSeekBrainDriver(name, config)
+    case 'ollama':
+      if (!config.defaultModel) {
+        throw new ConfigError(
+          `BrainProvider: ollama provider "${name}" is missing defaultModel. Ollama models are user-installed — pick one you've pulled (e.g. 'llama3.2').`,
+        )
+      }
+      return new OllamaBrainDriver(name, config)
+    case 'qwen':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: qwen provider "${name}" is missing apiKey. Source from env('DASHSCOPE_API_KEY') or env('QWEN_API_KEY').`,
+        )
+      }
+      return new QwenBrainDriver(name, config)
+    case 'minimax':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: minimax provider "${name}" is missing apiKey. Source from env('MINIMAX_API_KEY').`,
+        )
+      }
+      return new MiniMaxBrainDriver(name, config)
+    case 'openrouter':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openrouter provider "${name}" is missing apiKey. Source from env('OPENROUTER_API_KEY').`,
+        )
+      }
+      return new OpenRouterBrainDriver(name, config)
+    default: {
+      const exhaustiveCheck: never = config
       throw new ConfigError(
-        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic.`,
+        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic, openai, openai-responses, google, deepseek, ollama, qwen, minimax, openrouter.`,
       )
+      // (unreachable — kept for the exhaustive check to fire when a new driver lands)
+      // biome-ignore lint/correctness/noUnreachable: kept for the exhaustive-check above
+      return exhaustiveCheck
+    }
   }
 }

package/src/define_tool.ts

@@ -0,0 +1,42 @@
+/**
+ * `defineTool({ name, description, inputSchema, execute })` — typed
+ * factory mirroring `defineWorkflow` / `defineMachine` / `defineDurable`.
+ *
+ * ```ts
+ * const getWeather = defineTool({
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a location.',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { city: { type: 'string' } },
+ *     required: ['city'],
+ *   },
+ *   execute: async ({ city }: { city: string }, ctx) => {
+ *     return weatherService.lookup(city, ctx.context.userId as string)
+ *   },
+ * })
+ * ```
+ *
+ * The generic parameters are usually inferred from `execute`'s first
+ * arg + return type; apps that want explicit typing pass them.
+ */
+
+import type { Tool, ToolContext } from './tool.ts'
+
+export interface DefineToolSpec<TInput, TOutput> {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+  execute(input: TInput, ctx: ToolContext): Promise<TOutput>
+}
+
+export function defineTool<TInput = unknown, TOutput = unknown>(
+  spec: DefineToolSpec<TInput, TOutput>,
+): Tool<TInput, TOutput> {
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    execute: spec.execute,
+  }
+}