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

package/src/{providers/openai_compat_provider.ts → drivers/openai_compat/openai_compat_brain_driver.ts}

@@ -1,12 +1,12 @@
 /**
- * `OpenAICompatProvider` — abstract intermediate that captures the
+ * `OpenAICompatBrainDriver` — abstract intermediate that captures the
  * "OpenAI-compatible local / third-party endpoint" pattern shared by
- * `DeepSeekProvider`, `OllamaProvider`, and anything else (Groq,
+ * `DeepSeekBrainDriver`, `OllamaBrainDriver`, and anything else (Groq,
  * Together, Fireworks, vLLM, llama.cpp's server, …) that exposes a
  * `/v1/chat/completions` surface that is request-/response-shape-
  * identical to OpenAI's.
  *
- * What it does, factored out of OpenAIProvider:
+ * What it does, factored out of OpenAIBrainDriver:
  *
  *   - **Strips `reasoning_effort`.** Compat endpoints typically
  *     reject unknown fields. `buildParams` removes it on every
@@ -39,14 +39,14 @@
  */
 
 import type OpenAI from 'openai'
-import type { AgentGenerateResult } from '../agent_generate_result.ts'
-import type { AgentStreamEvent } from '../agent_stream_event.ts'
-import { BrainError } from '../brain_error.ts'
-import { parseGenerated, type OutputSchema } from '../output_schema.ts'
-import type { RunWithToolsOptions } from '../provider.ts'
-import type { Tool } from '../tool.ts'
-import { recoverOrThrow, runToolWithRecovery } from '../tool_runner.ts'
-import { ToolExecutionError } from '../tool_execution_error.ts'
+import type { AgentGenerateResult } from '../../agent_generate_result.ts'
+import type { AgentStreamEvent } from '../../agent_stream_event.ts'
+import { BrainError } from '../../brain_error.ts'
+import { parseGenerated, type OutputSchema } from '../../output_schema.ts'
+import type { RunWithToolsOptions } from '../../brain_driver.ts'
+import type { Tool } from '../../tool.ts'
+import { recoverOrThrow, runToolWithRecovery } from '../../tool_runner.ts'
+import { ToolExecutionError } from '../../tool_execution_error.ts'
 import type {
   ChatOptions,
   ChatUsage,
@@ -56,10 +56,10 @@ import type {
   SystemPrompt,
   ToolResultBlock,
   ToolUseBlock,
-} from '../types.ts'
-import { OpenAIProvider } from './openai_provider.ts'
+} from '../../types.ts'
+import { OpenAIBrainDriver } from '../openai/openai_brain_driver.ts'
 
-export abstract class OpenAICompatProvider extends OpenAIProvider {
+export abstract class OpenAICompatBrainDriver extends OpenAIBrainDriver {
   /**
    * Same as the OpenAI build but strips `reasoning_effort` — most
    * compat endpoints reject unknown fields. Subclasses that target
@@ -528,7 +528,7 @@ function prepareToolForcing(
   const respondName = `${RESPOND_TOOL_PREFIX}${schema.name}`
   if (userTools.some((t) => t.name === respondName)) {
     throw new BrainError(
-      `OpenAICompatProvider.runWithToolsAndSchema: synthetic tool name "${respondName}" collides with a user-supplied tool. Rename your tool or the OutputSchema.name to avoid the clash.`,
+      `OpenAICompatBrainDriver.runWithToolsAndSchema: synthetic tool name "${respondName}" collides with a user-supplied tool. Rename your tool or the OutputSchema.name to avoid the clash.`,
       { context: { conflictingName: respondName } },
     )
   }
@@ -601,7 +601,7 @@ function fromOpenAIAssistant(
 function addUsageHere(
   acc: ChatUsage,
   u: OpenAI.CompletionUsage | undefined,
-  provider: OpenAICompatProvider,
+  provider: OpenAICompatBrainDriver,
 ): void {
   if (!u) return
   // Cast: `mapUsage` is protected on the abstract class; we're

package/src/drivers/openai_responses/index.ts

@@ -0,0 +1 @@
+export { OpenAIResponsesBrainDriver } from './openai_responses_brain_driver.ts'

package/src/{providers/openai_responses_provider.ts → drivers/openai_responses/openai_responses_brain_driver.ts}

@@ -1,5 +1,5 @@
 /**
- * `OpenAIResponsesProvider` — implementation of `Provider` backed
+ * `OpenAIResponsesBrainDriver` — implementation of `Provider` backed
  * by the `openai` SDK's Responses API
  * (`client.responses.create`).
  *
@@ -10,11 +10,11 @@
  *
  * For everything else (plain chat, embeddings, transcription,
  * function calling without server tools), the standard
- * `OpenAIProvider` (driver `'openai'`) is simpler. Apps that
+ * `OpenAIBrainDriver` (driver `'openai'`) is simpler. Apps that
  * use both register them as two separate providers and route
  * per-call.
  *
- * Inherits `embed` + `transcribe` from `OpenAIProvider`
+ * Inherits `embed` + `transcribe` from `OpenAIBrainDriver`
  * (embeddings + Whisper live on different endpoints unchanged).
  *
  * V1 coverage:
@@ -32,27 +32,27 @@
  *
  * The Responses API's message shape (`input_items`) is different
  * from chat completions' `messages`, so this is a separate
- * provider class rather than a strategy inside `OpenAIProvider`.
+ * provider class rather than a strategy inside `OpenAIBrainDriver`.
  * Translation lives in this file.
  */
 
 import OpenAI from 'openai'
-import type { AgentGenerateResult } from '../agent_generate_result.ts'
-import type { AgentResult } from '../agent_result.ts'
-import type { AgentStreamEvent } from '../agent_stream_event.ts'
-import { BrainError } from '../brain_error.ts'
-import type { OpenAIResponsesProviderConfig } from '../brain_config.ts'
-import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
-import type { MCPServer } from '../mcp_server.ts'
-import { parseGenerated, type OutputSchema } from '../output_schema.ts'
+import type { AgentGenerateResult } from '../../agent_generate_result.ts'
+import type { AgentResult } from '../../agent_result.ts'
+import type { AgentStreamEvent } from '../../agent_stream_event.ts'
+import { BrainError } from '../../brain_error.ts'
+import type { OpenAIResponsesProviderConfig } from '../../brain_config.ts'
+import { resolveMcpTools, type ResolveMcpToolsOptions } from '../../mcp/resolve_mcp_tools.ts'
+import type { MCPServer } from '../../mcp_server.ts'
+import { parseGenerated, type OutputSchema } from '../../output_schema.ts'
 import type {
-  Provider,
+  BrainDriver,
   RunWithToolsOptions,
   RunWithToolsOptionsWithSuspend,
-} from '../provider.ts'
-import type { SuspendedRun } from '../suspended_run.ts'
-import type { Tool } from '../tool.ts'
-import { runToolWithRecovery } from '../tool_runner.ts'
+} from '../../brain_driver.ts'
+import type { SuspendedRun } from '../../suspended_run.ts'
+import type { Tool } from '../../tool.ts'
+import { runToolWithRecovery } from '../../tool_runner.ts'
 import type {
   ChatOptions,
   ChatResult,
@@ -66,8 +66,8 @@ import type {
   TextBlock,
   ToolResultBlock,
   ToolUseBlock,
-} from '../types.ts'
-import { OpenAIProvider } from './openai_provider.ts'
+} from '../../types.ts'
+import { OpenAIBrainDriver } from '../openai/openai_brain_driver.ts'
 
 const DEFAULT_OPENAI_MODEL = 'gpt-5'
 const DEFAULT_OPENAI_MAX_TOKENS = 4096
@@ -83,13 +83,13 @@ export interface OpenAIResponsesProviderOptions {
 /** Translation: framework `ServerTool` → Responses API tool entry. */
 type ResponsesTool = Record<string, unknown>
 
-export class OpenAIResponsesProvider extends OpenAIProvider implements Provider {
+export class OpenAIResponsesBrainDriver extends OpenAIBrainDriver implements BrainDriver {
   constructor(
     name: string,
     config: OpenAIResponsesProviderConfig,
     options: OpenAIResponsesProviderOptions = {},
   ) {
-    // Reuse OpenAIProvider's constructor for the SDK client + the
+    // Reuse OpenAIBrainDriver's constructor for the SDK client + the
     // chat / embed / transcribe model defaults. Inheritance keeps
     // `client`, `defaultEmbedModel`, `defaultTranscribeModel`
     // working unchanged.
@@ -951,12 +951,12 @@ function responsesServerTools(serverTools: readonly ServerTool[]): ResponsesTool
       out.push({ type: 'code_interpreter', container: { type: 'auto' } })
     } else if (t.type === 'web_fetch') {
       throw new BrainError(
-        'OpenAIResponsesProvider: server tool `web_fetch` is Anthropic-only. Use `web_search` for OpenAI, or route to Anthropic.',
+        'OpenAIResponsesBrainDriver: server tool `web_fetch` is Anthropic-only. Use `web_search` for OpenAI, or route to Anthropic.',
         { context: { provider: 'openai-responses' } },
       )
     } else if (t.type === 'url_context') {
       throw new BrainError(
-        'OpenAIResponsesProvider: server tool `url_context` is Gemini-only. Route to Gemini, or include the URL in the prompt and use `web_search`.',
+        'OpenAIResponsesBrainDriver: server tool `url_context` is Gemini-only. Route to Gemini, or include the URL in the prompt and use `web_search`.',
         { context: { provider: 'openai-responses' } },
       )
     }
@@ -1003,7 +1003,7 @@ async function tryRecoverParseError(
   cause: Error,
   options: RunWithToolsOptions,
 ): Promise<{ content: string; isError: boolean }> {
-  const { ToolExecutionError } = await import('../tool_execution_error.ts')
+  const { ToolExecutionError } = await import('../../tool_execution_error.ts')
   const err = new ToolExecutionError(
     toolName,
     callId,

package/src/index.ts

@@ -1,9 +1,9 @@
 // Public API of @strav/brain.
 //
-// V1: Provider interface + AnthropicProvider, BrainManager, Thread,
+// V1: BrainDriver interface + AnthropicBrainDriver, BrainManager, Thread,
 // BrainProvider service-wiring, prompt caching.
 // V2 (this slice): tools + agents — defineTool, Agent base + AgentRunner,
-// BrainManager.runTools / .agent(Class), Provider.runWithTools.
+// BrainManager.runTools / .agent(Class), BrainDriver.runWithTools.
 // Still deferred: MCP, embeddings, streaming agent loops, server-side
 // tools, structured outputs, other providers.
 
@@ -29,7 +29,13 @@ export {
   type OpenAIResponsesProviderConfig,
   type ProviderConfig,
 } from './brain_config.ts'
-export { BrainError } from './brain_error.ts'
+export {
+  BrainConfigError,
+  BrainError,
+  BrainProviderError,
+  BrainUsageError,
+  UnknownProviderError,
+} from './brain_error.ts'
 export {
   type AgentResolver,
   BrainManager,
@@ -40,18 +46,18 @@ export { defineTool, type DefineToolSpec } from './define_tool.ts'
 export { MCPClientPool, type MCPClientFactory } from './mcp/pool.ts'
 export type { MCPServer, MCPServerToolConfig } from './mcp_server.ts'
 export type { OutputSchema } from './output_schema.ts'
-export { AnthropicProvider } from './providers/anthropic_provider.ts'
-export { DeepSeekProvider } from './providers/deepseek_provider.ts'
-export { GeminiProvider } from './providers/gemini_provider.ts'
-export { OllamaProvider } from './providers/ollama_provider.ts'
-export { OpenAICompatProvider } from './providers/openai_compat_provider.ts'
-export { OpenAIProvider } from './providers/openai_provider.ts'
-export { OpenAIResponsesProvider } from './providers/openai_responses_provider.ts'
+export { AnthropicBrainDriver } from './drivers/anthropic/anthropic_brain_driver.ts'
+export { DeepSeekBrainDriver } from './drivers/deepseek/deepseek_brain_driver.ts'
+export { GeminiBrainDriver } from './drivers/gemini/gemini_brain_driver.ts'
+export { OllamaBrainDriver } from './drivers/ollama/ollama_brain_driver.ts'
+export { OpenAICompatBrainDriver } from './drivers/openai_compat/openai_compat_brain_driver.ts'
+export { OpenAIBrainDriver } from './drivers/openai/openai_brain_driver.ts'
+export { OpenAIResponsesBrainDriver } from './drivers/openai_responses/openai_responses_brain_driver.ts'
 export type {
-  Provider,
+  BrainDriver,
   RunWithToolsOptions,
   RunWithToolsOptionsWithSuspend,
-} from './provider.ts'
+} from './brain_driver.ts'
 export {
   appendResumeResults,
   isSuspended,

package/src/mcp/pool.ts

@@ -23,7 +23,7 @@
  * ```ts
  * const pool = new MCPClientPool()
  *
- * const openai = new OpenAIProvider(
+ * const openai = new OpenAIBrainDriver(
  *   'openai',
  *   { driver: 'openai', apiKey: ... },
  *   { mcpPool: pool },

package/src/persistence/brain_message.ts

@@ -13,7 +13,7 @@
 
 import { Model } from '@strav/database'
 import type { ChatUsage, ContentBlock } from '../types.ts'
-import { brainMessageSchema } from './schema/brain_message_schema.ts'
+import { brainMessageSchema } from './schemas/brain_message_schema.ts'
 
 export type BrainMessageRole = 'user' | 'assistant'
 

package/src/persistence/brain_message_repository.ts

@@ -13,13 +13,11 @@
  *     pagination UIs.
  */
 
-// biome-ignore lint/style/useImportType: PostgresDatabase needs to be a value import for @inject().
-import { PostgresDatabase, quoteIdent, Repository, type RepositoryScope } from '@strav/database'
-// biome-ignore lint/style/useImportType: EventBus value import for @inject().
-import { EventBus, inject, ulid } from '@strav/kernel'
+import { quoteIdent, Repository, type RepositoryScope } from '@strav/database'
+import { ulid } from '@strav/kernel'
 import type { ChatUsage, ContentBlock } from '../types.ts'
 import { BrainMessage, type BrainMessageRole } from './brain_message.ts'
-import { brainMessageSchema } from './schema/brain_message_schema.ts'
+import { brainMessageSchema } from './schemas/brain_message_schema.ts'
 
 export interface AppendTurnInput {
   threadId: string
@@ -37,16 +35,10 @@ export interface LoadMessagesOptions {
   offset?: number
 }
 
-@inject()
 export class BrainMessageRepository extends Repository<BrainMessage> {
   static override readonly schema = brainMessageSchema
   static override readonly model = BrainMessage
 
-  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor for @inject() metadata emission.
-  constructor(db: PostgresDatabase, events: EventBus) {
-    super(db, events)
-  }
-
   /**
    * Insert a new turn at the next `turn_index` for the thread. The
    * `turn_index` is computed in-SQL so two concurrent appends

package/src/persistence/brain_suspended_run.ts

@@ -11,7 +11,7 @@
 import { Model } from '@strav/database'
 import type { SuspendedState } from '../suspended_run.ts'
 import type { ToolUseBlock } from '../types.ts'
-import { brainSuspendedRunSchema } from './schema/brain_suspended_run_schema.ts'
+import { brainSuspendedRunSchema } from './schemas/brain_suspended_run_schema.ts'
 
 export type BrainSuspendedRunStatus = 'pending' | 'resumed' | 'cancelled'
 

package/src/persistence/brain_suspended_run_repository.ts

@@ -12,12 +12,9 @@
  *     filtered by `user_id` or `thread_id`.
  */
 
-// biome-ignore lint/style/useImportType: PostgresDatabase value import for @inject().
-import { PostgresDatabase, Repository } from '@strav/database'
-// biome-ignore lint/style/useImportType: EventBus value import for @inject().
-import { EventBus, inject } from '@strav/kernel'
+import { Repository } from '@strav/database'
 import { BrainSuspendedRun, type BrainSuspendedRunStatus } from './brain_suspended_run.ts'
-import { brainSuspendedRunSchema } from './schema/brain_suspended_run_schema.ts'
+import { brainSuspendedRunSchema } from './schemas/brain_suspended_run_schema.ts'
 
 export interface ListPendingOptions {
   /** Filter by app-defined user — useful when an app has per-user approval queues. */
@@ -29,16 +26,10 @@ export interface ListPendingOptions {
   offset?: number
 }
 
-@inject()
 export class BrainSuspendedRunRepository extends Repository<BrainSuspendedRun> {
   static override readonly schema = brainSuspendedRunSchema
   static override readonly model = BrainSuspendedRun
 
-  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor for @inject() metadata emission.
-  constructor(db: PostgresDatabase, events: EventBus) {
-    super(db, events)
-  }
-
   /** Flip status to `resumed` after `brain.resumeTools(state, ...)` succeeds. */
   async markResumed(run: BrainSuspendedRun): Promise<BrainSuspendedRun> {
     return this.markStatus(run, 'resumed')

package/src/persistence/brain_thread.ts

@@ -13,7 +13,7 @@
 
 import { Model } from '@strav/database'
 import type { ChatOptions, SystemPrompt } from '../types.ts'
-import { brainThreadSchema } from './schema/brain_thread_schema.ts'
+import { brainThreadSchema } from './schemas/brain_thread_schema.ts'
 
 export class BrainThread extends Model {
   static override readonly schema = brainThreadSchema

package/src/persistence/brain_thread_repository.ts

@@ -14,12 +14,9 @@
  * shows up in this code — the database enforces isolation.
  */
 
-// biome-ignore lint/style/useImportType: PostgresDatabase needs to be a value import — the @inject() decorator below resolves the constructor param via reflect-metadata, which requires the runtime class reference.
-import { PostgresDatabase, Repository } from '@strav/database'
-// biome-ignore lint/style/useImportType: EventBus has the same constraint as PostgresDatabase.
-import { EventBus, inject } from '@strav/kernel'
+import { Repository } from '@strav/database'
 import { BrainThread } from './brain_thread.ts'
-import { brainThreadSchema } from './schema/brain_thread_schema.ts'
+import { brainThreadSchema } from './schemas/brain_thread_schema.ts'
 
 export interface ListThreadsOptions {
   /** Pagination — defaults to 50. */
@@ -27,16 +24,10 @@ export interface ListThreadsOptions {
   offset?: number
 }
 
-@inject()
 export class BrainThreadRepository extends Repository<BrainThread> {
   static override readonly schema = brainThreadSchema
   static override readonly model = BrainThread
 
-  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor forces TypeScript to emit `design:paramtypes` metadata on the subclass for the @inject() decorator above.
-  constructor(db: PostgresDatabase, events: EventBus) {
-    super(db, events)
-  }
-
   /**
    * List threads for a given app-defined user, newest-first. Empty
    * `userId` lists every thread visible under RLS — useful for

package/src/persistence/index.ts

@@ -45,4 +45,4 @@ export {
   brainMessageSchema,
   brainSuspendedRunSchema,
   brainThreadSchema,
-} from './schema/index.ts'
+} from './schemas/index.ts'

package/src/tool_runner.ts

@@ -22,7 +22,7 @@
  * message content; Gemini `functionResponse` with `{ error }`).
  */
 
-import type { RunWithToolsOptions } from './provider.ts'
+import type { RunWithToolsOptions } from './brain_driver.ts'
 import type { Tool, ToolContext } from './tool.ts'
 import { ToolExecutionError } from './tool_execution_error.ts'
 

package/src/types.ts

@@ -376,7 +376,7 @@ export interface ChatOptions {
    * subsequent requests (Thread does this automatically). Saves
    * tokens on long threads without lossy client-side pruning.
    *
-   * Only honored by `AnthropicProvider` (driver `'anthropic'`),
+   * Only honored by `AnthropicBrainDriver` (driver `'anthropic'`),
    * via the `compact-2026-01-12` beta. Silently ignored by every
    * other provider so apps targeting multiple providers with the
    * same options object don't have to special-case.
@@ -388,7 +388,7 @@ export interface ChatOptions {
    * from the prior `Response` identified by this id and replays
    * the conversation server-side. Saves tokens on long threads.
    *
-   * Only honored by `OpenAIResponsesProvider` (driver
+   * Only honored by `OpenAIResponsesBrainDriver` (driver
    * `'openai-responses'`); silently ignored by every other provider
    * — apps that target multiple providers with the same options
    * object don't have to special-case.