@strav/brain 1.0.0-alpha.22 → 1.0.0-alpha.24

package/package.json

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

package/src/agent_runner.ts

@@ -31,7 +31,7 @@ import type {
   Message,
   ToolUseBlock,
 } from './types.ts'
-import type { RunWithToolsOptions } from './provider.ts'
+import type { RunWithToolsOptions } from './brain_driver.ts'
 import type {
   SuspendedRun,
   SuspendedState,

package/src/{provider.ts → brain_driver.ts}

@@ -1,15 +1,16 @@
 /**
- * `Provider` — the contract every brain backend implements.
+ * `BrainDriver` — the contract every brain backend implements.
  *
- * Each concrete provider (Anthropic, OpenAI later, Gemini later,
- * DeepSeek later) wraps the vendor's SDK and translates the framework
- * shapes (`Message`, `ChatOptions`) into the vendor's native request,
- * then translates the response back into `ChatResult` / `StreamEvent`.
+ * Each concrete driver (`AnthropicBrainDriver`, `OpenAIBrainDriver`,
+ * `GeminiBrainDriver`, `DeepSeekBrainDriver`, …) wraps the vendor's
+ * SDK and translates the framework shapes (`Message`, `ChatOptions`)
+ * into the vendor's native request, then translates the response back
+ * into `ChatResult` / `StreamEvent`.
  *
- * Providers are values, not classes — apps use them via the
- * `BrainManager` facade. The interface is exported so apps that need
- * to plug in a custom provider (e.g. a local Ollama) can do so without
- * subclassing.
+ * Drivers are values, not classes the app instantiates by name — apps
+ * use them via the `BrainManager` facade. The interface is exported so
+ * apps that need to plug in a custom backend (e.g. a local Ollama
+ * variant, or a private gateway) can do so without subclassing.
  */
 
 import type { AgentGenerateResult } from './agent_generate_result.ts'
@@ -106,7 +107,7 @@ export type RunWithToolsOptionsWithSuspend = RunWithToolsOptions & {
   shouldSuspend: NonNullable<RunWithToolsOptions['shouldSuspend']>
 }
 
-export interface Provider {
+export interface BrainDriver {
   /** Identifier — matches the `config.brain.providers` key. */
   readonly name: string
 

package/src/brain_error.ts

@@ -1,16 +1,32 @@
 /**
- * `BrainError` — typed wrapper for failures originating in the brain
- * stack. Provider-native errors (e.g. `Anthropic.RateLimitError`) are
- * preserved on `.cause` so apps can `instanceof`-check them when they
- * need provider-specific recovery; the wrapping just gives the
- * framework a consistent `StravError` to render through the standard
+ * `BrainError` hierarchy — typed wrappers for failures originating
+ * in the brain stack.
+ *
+ * Provider-native errors (e.g. `Anthropic.RateLimitError`) are
+ * preserved on `.cause` so apps can `instanceof`-check them when
+ * they need vendor-specific recovery; the framework wrapping gives
+ * a consistent `StravError` to render through the standard
  * exception handler.
  *
- * Subclassing surface deferred — V1 has one error type. When a real
- * use case appears for distinguishing "model refused" vs "rate
- * limited" at the framework level (rather than `instanceof
- * Anthropic.RateLimitError` at the call site), a typed hierarchy
- * lands.
+ * Subclasses ship in v1 for the boot / lookup / usage paths.
+ * Vendor-side runtime errors use `BrainProviderError` as the
+ * generic wrapper. Granular vendor classes (rate-limit, content
+ * filter, etc.) land when apps actually need to branch on them at
+ * the framework level — until then, `instanceof Anthropic.RateLimitError`
+ * on `.cause` is the call-site pattern.
+ *
+ *   - `BrainConfigError` — boot-time misconfiguration (missing
+ *     provider in `config.brain.providers`, default key absent).
+ *
+ *   - `UnknownProviderError` — `brain.provider(name)` for a name
+ *     that wasn't registered.
+ *
+ *   - `BrainUsageError` — pre-condition violations from the
+ *     framework's own API contract (e.g. `AgentRunner.run` called
+ *     before `input()`).
+ *
+ *   - `BrainProviderError` — wraps a vendor exception. `cause` is
+ *     preserved; default status 502.
  */
 
 import { StravError } from '@strav/kernel'
@@ -27,3 +43,63 @@ export class BrainError extends StravError {
     )
   }
 }
+
+export class BrainConfigError extends BrainError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown> } = {},
+  ) {
+    super(message, options)
+    // Reassign code/status via the underlying StravError props (the
+    // base constructor froze them with `brain.error`); we read them
+    // back through getters so subclass-specific overrides surface in
+    // logs.
+    Object.defineProperty(this, 'code', { value: 'brain.config' })
+    Object.defineProperty(this, 'status', { value: 500 })
+  }
+}
+
+export class UnknownProviderError extends BrainError {
+  constructor(name: string, available: readonly string[]) {
+    super(
+      `Brain provider "${name}" is not registered. Available: ${available.join(', ') || '<none>'}.`,
+      { context: { requested: name, available } },
+    )
+    Object.defineProperty(this, 'code', { value: 'brain.unknown_provider' })
+    Object.defineProperty(this, 'status', { value: 400 })
+  }
+}
+
+export class BrainUsageError extends BrainError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown> } = {},
+  ) {
+    super(message, options)
+    Object.defineProperty(this, 'code', { value: 'brain.usage' })
+    Object.defineProperty(this, 'status', { value: 500 })
+  }
+}
+
+export class BrainProviderError extends BrainError {
+  constructor(
+    message: string,
+    options: {
+      provider: string
+      operation: string
+      context?: Record<string, unknown>
+      cause?: unknown
+    },
+  ) {
+    super(message, {
+      context: {
+        provider: options.provider,
+        operation: options.operation,
+        ...(options.context ?? {}),
+      },
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+    Object.defineProperty(this, 'code', { value: 'brain.provider_error' })
+    Object.defineProperty(this, 'status', { value: 502 })
+  }
+}

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),
@@ -41,10 +41,10 @@ import type {
   TranscribeResult,
 } from './types.ts'
 import type {
-  Provider,
+  BrainDriver,
   RunWithToolsOptions,
   RunWithToolsOptionsWithSuspend,
-} from './provider.ts'
+} 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'
@@ -56,7 +56,7 @@ 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. */
@@ -72,7 +72,7 @@ export interface BrainManagerOptions {
 
 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[]
@@ -92,7 +92,7 @@ export class BrainManager {
   }
 
   /** 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) {
@@ -103,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.
    *
@@ -155,7 +178,7 @@ export class BrainManager {
    *
    * Throws `BrainError` when the configured provider doesn't
    * implement `runWithTools` (V1: OpenAI / Gemini / DeepSeek providers
-   * don't yet — only `AnthropicProvider`).
+   * don't yet — only `AnthropicBrainDriver`).
    */
   runTools(
     input: string | readonly Message[],

package/src/brain_provider.ts

@@ -27,13 +27,13 @@
 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 { DeepSeekProvider } from './providers/deepseek_provider.ts'
-import { GeminiProvider } from './providers/gemini_provider.ts'
-import { OllamaProvider } from './providers/ollama_provider.ts'
-import { OpenAIProvider } from './providers/openai_provider.ts'
-import { OpenAIResponsesProvider } from './providers/openai_responses_provider.ts'
-import type { Provider } from './provider.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 { 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 type { BrainDriver } from './brain_driver.ts'
 
 export class BrainProvider extends ServiceProvider {
   override readonly name = 'brain'
@@ -58,9 +58,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] = {
@@ -89,7 +89,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) {
@@ -97,42 +97,42 @@ 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)
+      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 OpenAIProvider(name, config)
+      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 OpenAIResponsesProvider(name, config)
+      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 GeminiProvider(name, config)
+      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 DeepSeekProvider(name, config)
+      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 OllamaProvider(name, config)
+      return new OllamaBrainDriver(name, config)
     default: {
       const exhaustiveCheck: never = config
       throw new ConfigError(