@strav/brain 0.4.31 → 1.0.0-alpha.9

package/package.json

@@ -1,32 +1,29 @@
 {
   "name": "@strav/brain",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.9",
+  "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching. Anthropic provider in V1; OpenAI / Gemini / DeepSeek follow.",
   "type": "module",
-  "description": "AI module for the Strav framework",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*.ts"
+    ".": "./src/index.ts"
   },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json",
-    "CHANGELOG.md"
+    "src",
+    "README.md"
   ],
-  "peerDependencies": {
-    "@strav/kernel": "0.4.31"
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@strav/mcp": "0.4.31",
-    "@strav/workflow": "0.4.31",
-    "zod": "^3.25 || ^4.0"
+    "@strav/kernel": "1.0.0-alpha.9",
+    "@anthropic-ai/sdk": "^0.100.0"
   },
-  "devDependencies": {
-    "@strav/http": "0.4.31"
+  "peerDependencies": {
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/agent.ts

@@ -1,93 +1,59 @@
-import type {
-  ToolDefinition,
-  ToolCall,
-  ToolCallRecord,
-  AgentResult,
-  OutputSchema,
-} from './types.ts'
-
 /**
- * Base class for AI agents.
+ * `Agent` — declarative base class for AI agents.
  *
- * Extend this class to define an agent with custom instructions,
- * tools, structured output, and lifecycle hooks.
+ * Apps subclass and set the static-ish properties: which model to
+ * use, what the agent's persona is, which tools it has access to,
+ * and an optional iteration ceiling. The `BrainManager.agent(Class)`
+ * call resolves an instance via the container, builds an
+ * `AgentRunner`, and lets the app stream input + context into it.
  *
- * @example
- * class SupportAgent extends Agent {
- *   provider = 'anthropic'
- *   model = 'claude-sonnet-4-5-20250929'
- *   instructions = 'You are a customer support agent.'
- *   tools = [searchTool, lookupOrderTool]
+ * ```ts
+ * @inject()
+ * class ResearchAgent extends Agent {
+ *   override readonly instructions = 'You are a meticulous research assistant.'
+ *   override readonly tools = [searchTool, summarizeTool]
+ *   override readonly tier: ModelTier = 'powerful'
+ * }
  *
- *   output = z.object({
- *     reply: z.string(),
- *     category: z.enum(['billing', 'shipping', 'product', 'other']),
- *   })
+ * const result = await brain.agent(ResearchAgent)
+ *   .input('What is the current state of bun.sql?')
+ *   .context({ userId: '01ABC...' })
+ *   .run()
+ * ```
  *
- *   onToolCall(call: ToolCall) {
- *     console.log(`Calling tool: ${call.name}`)
- *   }
- * }
+ * V1 makes the configuration declarative-only — apps that need
+ * runtime knobs (per-request model overrides, dynamic tool sets)
+ * use `BrainManager.runTools(...)` directly. Adding per-instance
+ * overrides on the Agent class is a future ergonomic slice.
  */
-export abstract class Agent {
-  /** Provider name (e.g., 'anthropic', 'openai'). Falls back to config default. */
-  provider?: string
-
-  /** Model identifier. Falls back to the provider's configured default model. */
-  model?: string
-
-  /** System prompt / instructions for this agent. Supports `{{key}}` context interpolation. */
-  instructions: string = ''
 
-  /** Tools available to this agent during execution. */
-  tools?: ToolDefinition[]
+import type { ModelTier } from './types.ts'
+import type { Tool } from './tool.ts'
 
-  /** Structured output schema (Zod or JSON Schema). When set, the final response is parsed and validated. */
-  output?: OutputSchema
-
-  /** Maximum tool-use loop iterations before forcing a stop. Falls back to config default (10). */
-  maxIterations?: number
-
-  /** Maximum tokens per completion request. Falls back to config default (4096). */
-  maxTokens?: number
+export abstract class Agent {
+  /** System prompt — the persona / instructions Claude sees on every turn. */
+  abstract readonly instructions: string
 
-  /** Temperature for completion requests. Falls back to config default (0.7). */
-  temperature?: number
+  /** Tools the agent can call. Empty array → the model answers without tools. */
+  readonly tools: readonly Tool[] = []
 
-  // ── Lifecycle hooks (optional) ───────────────────────────────────────────
+  /** Override the configured default provider. Default = brain's default provider. */
+  readonly provider?: string
 
-  /** Called before the first completion request. */
-  onStart?(input: string, context: Record<string, unknown>): void | Promise<void>
+  /** Explicit model ID. Wins over `tier`. */
+  readonly model?: string
 
-  /** Called when the model requests a tool call, before execution. */
-  onToolCall?(call: ToolCall): void | Promise<void>
+  /** Tier sugar. Default `'powerful'` for agentic work. */
+  readonly tier: ModelTier = 'powerful'
 
   /**
-   * Called before a tool is executed. Return `true` to suspend the agent loop
-   * before running this tool call; the runner will return a `SuspendedRun`
-   * with a JSON-serializable snapshot of the loop state. Resume later via
-   * `AgentRunner.resume(state, toolResults)` once the tool result is known.
-   *
-   * This is a policy-free primitive: the framework does not attach meaning
-   * to suspension. Integrators can use it to gate mutating tools on human
-   * approval, dispatch a tool to an external worker, rate-limit, etc.
-   *
-   * When suspension occurs mid-batch, the triggering call and any remaining
-   * unprocessed calls in the same batch are captured together in
-   * `pendingToolCalls` so the provider's tool_use/tool_result contract stays
-   * balanced on resume.
+   * Safety ceiling on the agentic loop. Default `10`. Hitting it
+   * returns a result with `stopReason: 'max_iterations'`; the loop
+   * doesn't throw because partial progress (assistant messages, tool
+   * results) is usually still useful to surface.
    */
-  shouldSuspend?(
-    call: ToolCall,
-    context: Record<string, unknown>
-  ): boolean | Promise<boolean>
-
-  /** Called after a tool finishes execution. */
-  onToolResult?(call: ToolCallRecord): void | Promise<void>
-
-  /** Called when the agent run completes successfully. */
-  onComplete?(result: AgentResult): void | Promise<void>
+  readonly maxIterations: number = 10
 
-  /** Called when the agent run encounters an error. */
-  onError?(error: Error): void | Promise<void>
+  /** Hard cap on per-call response tokens. Default `4096`. */
+  readonly maxTokens: number = 4096
 }

package/src/agent_result.ts

@@ -0,0 +1,32 @@
+/**
+ * `AgentResult` — what an agentic loop returns when it ends. Combines
+ * the final assistant `text`, the full message history (including
+ * tool calls + results so apps can render the trace), the total
+ * iteration count (how many tool-use round-trips the loop made),
+ * and aggregated token usage across every model call inside the
+ * loop.
+ *
+ * `stopReason` is the provider's terminal stop reason (typically
+ * `'end_turn'`). When the loop exits because it hit `maxIterations`,
+ * `stopReason` is `'max_iterations'` — distinct from the provider
+ * value so apps can detect "the model would have kept going."
+ */
+
+import type { ChatUsage, Message } from './types.ts'
+
+export interface AgentResult {
+  /** Concatenated text from the final assistant turn. */
+  text: string
+  /** Full message history of the loop, including tool_use / tool_result blocks. */
+  messages: Message[]
+  /** Number of tool-use rounds. `0` when the model answered without tools. */
+  iterations: number
+  /**
+   * Terminal stop reason. Either the provider's stop_reason (typically
+   * `'end_turn'`) or the framework-specific `'max_iterations'` when
+   * the loop hit its iteration ceiling.
+   */
+  stopReason: string
+  /** Token usage summed across every model call in the loop. */
+  usage: ChatUsage
+}

package/src/agent_runner.ts

@@ -0,0 +1,61 @@
+/**
+ * `AgentRunner` — fluent builder returned by `BrainManager.agent(Class)`.
+ *
+ * Carries the agent instance + an input message + an optional
+ * per-run context bag. `run()` translates the agent's declarative
+ * configuration into a `runWithTools` call and returns the
+ * `AgentResult`.
+ *
+ * Designed to chain: `brain.agent(R).input(text).context({...}).run()`.
+ * Apps that need the full Message-array surface bypass the runner
+ * and call `BrainManager.runTools(messages, tools, options)` directly.
+ */
+
+import type { Agent } from './agent.ts'
+import type { AgentResult } from './agent_result.ts'
+import type { BrainManager } from './brain_manager.ts'
+import type { ChatOptions, Message } from './types.ts'
+
+export class AgentRunner {
+  private prompt: string | undefined
+  private contextBag: Record<string, unknown> = {}
+
+  constructor(
+    private readonly brain: BrainManager,
+    private readonly agent: Agent,
+  ) {}
+
+  /** Set the user input. Required before `run()`. */
+  input(text: string): this {
+    this.prompt = text
+    return this
+  }
+
+  /**
+   * Attach context that every tool's `execute(input, ctx)` will see
+   * on `ctx.context`. Useful for per-request data the agent's tools
+   * need but the model shouldn't see directly (auth identity,
+   * tenant id, request-id for tracing).
+   */
+  context(data: Record<string, unknown>): this {
+    this.contextBag = { ...this.contextBag, ...data }
+    return this
+  }
+
+  async run(): Promise<AgentResult> {
+    if (this.prompt === undefined) {
+      throw new Error('AgentRunner.run: input() must be called before run().')
+    }
+    const messages: Message[] = [{ role: 'user', content: this.prompt }]
+    const options: ChatOptions & { maxIterations?: number; context?: Record<string, unknown> } = {
+      tier: this.agent.tier,
+      maxTokens: this.agent.maxTokens,
+      system: this.agent.instructions,
+      maxIterations: this.agent.maxIterations,
+      context: this.contextBag,
+    }
+    if (this.agent.model !== undefined) options.model = this.agent.model
+    if (this.agent.provider !== undefined) options.provider = this.agent.provider
+    return this.brain.runTools(messages, this.agent.tools, options)
+  }
+}

package/src/brain_config.ts

@@ -0,0 +1,72 @@
+/**
+ * Brain configuration shape — what `config.brain` looks like.
+ *
+ * Mirrors the manager-pattern config used by other Strav packages
+ * (auth.guards, mail.transports, database.connections): a `default`
+ * provider key + a `providers` map keyed by name. Each provider entry
+ * carries its driver and driver-specific options.
+ *
+ * `tiers` map model-tier sugar (`fast` / `balanced` / `powerful`) to
+ * concrete model IDs. The `'fast' → claude-haiku-4-5` etc. defaults
+ * apply when this section is omitted; apps can rewire to point at,
+ * e.g., self-hosted Llama for the `fast` tier.
+ *
+ * `cache.auto` is the default for `ChatOptions.cache` when the call
+ * site doesn't pass one. Prompt caching is opt-in by default — apps
+ * that want every long request to cache flip this to `true`.
+ */
+
+import type { ModelTier } from './types.ts'
+
+/** Anthropic-specific driver config. */
+export interface AnthropicProviderConfig {
+  driver: 'anthropic'
+  /** API key. Required. Most apps source from `env('ANTHROPIC_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. */
+  defaultModel?: string
+  /** Default `max_tokens` for `chat()` calls that don't specify one. */
+  defaultMaxTokens?: number
+  /** Optional beta headers added to every request from this provider. */
+  betas?: readonly string[]
+}
+
+export type ProviderConfig = AnthropicProviderConfig // | OpenAIProviderConfig | … (later slices)
+
+/** Cache-shape defaults applied when `ChatOptions.cache` is omitted. */
+export interface BrainCacheConfig {
+  /** Set `cache_control` on the last cacheable block on every request. Default `false`. */
+  auto?: boolean
+}
+
+export interface BrainConfigShape {
+  /** Name of the default provider; must exist in `providers`. */
+  default: string
+  /** Provider registry. Each entry is one configured backend. */
+  providers: Record<string, ProviderConfig>
+  /**
+   * Model-tier sugar. When omitted, the framework defaults apply:
+   *   - fast: 'claude-haiku-4-5'
+   *   - balanced: 'claude-sonnet-4-6'
+   *   - powerful: 'claude-opus-4-7'
+   */
+  tiers?: Partial<Record<ModelTier, string>>
+  /** Prompt-cache defaults. */
+  cache?: BrainCacheConfig
+}
+
+/**
+ * Framework-level tier defaults. Apps that don't override
+ * `config.brain.tiers` get these. Lives here so `BrainManager` and
+ * the docs both pull from one source.
+ */
+export const DEFAULT_TIERS: Record<ModelTier, string> = {
+  fast: 'claude-haiku-4-5',
+  balanced: 'claude-sonnet-4-6',
+  powerful: 'claude-opus-4-7',
+}
+
+/** The model the framework reaches for when nothing else is specified. */
+export const DEFAULT_MODEL = DEFAULT_TIERS.powerful

package/src/brain_error.ts

@@ -0,0 +1,29 @@
+/**
+ * `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
+ * 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.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class BrainError extends StravError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(
+      message,
+      { code: 'brain.error', status: 500 },
+      { ...options },
+    )
+  }
+}