@strav/brain 1.0.0-alpha.16 → 1.0.0-alpha.18

package/src/persistence/schema/brain_suspended_run_schema.ts

@@ -0,0 +1,58 @@
+/**
+ * `brainSuspendedRunSchema` — a paused agentic loop awaiting
+ * human-in-the-loop tool approval.
+ *
+ * Two real use cases drive the shape:
+ *
+ *   1. **Linked to a thread** — the suspending run was part of a
+ *      conversational thread; the app wants the suspended state to
+ *      reference its thread so the UI can show "thread X is paused
+ *      waiting on Y." `thread_id` is the FK, nullable so detached
+ *      runs are fine.
+ *   2. **Standalone** — the run came from a one-shot `runTools(...)`
+ *      call (cron job, queued worker, ...). No thread context;
+ *      `thread_id` stays NULL.
+ *
+ * Columns:
+ *
+ *   - `id`                  ULID primary key. The id apps reference
+ *                           when resuming.
+ *   - `thread_id`           FK → `brain_thread`, NULLABLE,
+ *                           `onDelete: set null` — if the thread
+ *                           gets deleted, the suspended run keeps
+ *                           its data so the human approver can
+ *                           still inspect it.
+ *   - `user_id`             App-defined approver / owner.
+ *   - `pending_tool_calls`  JSONB — `ToolUseBlock[]` the model
+ *                           wants executed. Multi-call batches are
+ *                           captured together (mid-batch invariant).
+ *   - `state`               JSONB — `SuspendedState` snapshot. The
+ *                           framework's `brain.resumeTools(state,
+ *                           ...)` takes this as its first arg.
+ *   - `status`              `pending | resumed | cancelled`. Apps
+ *                           bulk-list pending runs and walk through
+ *                           an approval queue.
+ *   - `timestamps`          `created_at` for "how long pending?"
+ *                           sorts, `updated_at` for transition
+ *                           tracking.
+ *
+ * Tenanted: standard `tenant_id` + RLS.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+import { brainThreadSchema } from './brain_thread_schema.ts'
+
+export const brainSuspendedRunSchema = defineSchema(
+  'brain_suspended_run',
+  Archetype.Entity,
+  (t) => {
+    t.id()
+    t.reference('thread_id').to(brainThreadSchema).onDelete('set null').nullable()
+    t.string('user_id').max(64).nullable()
+    t.json('pending_tool_calls').notNull()
+    t.json('state').notNull()
+    t.enum('status', ['pending', 'resumed', 'cancelled']).notNull().default('pending')
+    t.timestamps()
+  },
+  { tenanted: true },
+)

package/src/persistence/schema/brain_thread_schema.ts

@@ -0,0 +1,50 @@
+/**
+ * `brainThreadSchema` — one row per conversation.
+ *
+ * Carries the per-thread defaults that `Thread` already serializes
+ * (`system`, `options`, `lastResponseId`) plus a few framework-side
+ * fields apps want to filter / sort on:
+ *
+ *   - `id`            ULID primary key. Hand the same value back to
+ *                     `BrainStore.loadThread(id)` to rehydrate.
+ *   - `user_id`       App-defined owner. Stored as `text` (no FK) —
+ *                     user table shape varies per app. Indexed in
+ *                     the recommended migration so "list threads
+ *                     for user X" stays fast.
+ *   - `title`         Human label. Apps set it from the first user
+ *                     turn or via an explicit "rename" UI.
+ *   - `system`        Thread-owned system prompt. Mirrors
+ *                     `ThreadState.system`. JSONB so the structured
+ *                     form (text + cache flag) round-trips.
+ *   - `options`       Thread defaults applied to every `send()`.
+ *                     Mirrors `ThreadState.options`.
+ *   - `last_response_id`  OpenAI Responses API stateful pointer.
+ *                     Mirrors `ThreadState.lastResponseId`. NULL for
+ *                     non-Responses providers.
+ *   - `timestamps`    `created_at` + `updated_at` for sort / audit.
+ *
+ * Tenanted: `tenant_id` FK + RLS policies auto-injected by
+ * `@strav/database`. Apps wrap calls in `tenants.withTenant(...)`
+ * and the database enforces isolation — no app-level filter needed.
+ *
+ * The per-turn message history lives in `brain_message`, joined by
+ * `thread_id`. This keeps every send to an O(1) INSERT and makes
+ * pagination / per-turn analytics cheap.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const brainThreadSchema = defineSchema(
+  'brain_thread',
+  Archetype.Entity,
+  (t) => {
+    t.id()
+    t.string('user_id').max(64).nullable()
+    t.string('title').max(255).nullable()
+    t.json('system').nullable()
+    t.json('options').nullable()
+    t.string('last_response_id').max(128).nullable()
+    t.timestamps()
+  },
+  { tenanted: true },
+)

package/src/persistence/schema/index.ts

@@ -0,0 +1,3 @@
+export { brainMessageSchema } from './brain_message_schema.ts'
+export { brainSuspendedRunSchema } from './brain_suspended_run_schema.ts'
+export { brainThreadSchema } from './brain_thread_schema.ts'

package/src/provider.ts

@@ -12,16 +12,26 @@
  * subclassing.
  */
 
+import type { AgentGenerateResult } from './agent_generate_result.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 { OutputSchema } from './output_schema.ts'
+import type { SuspendedRun } from './suspended_run.ts'
 import type { Tool } from './tool.ts'
+import type { ToolExecutionError } from './tool_execution_error.ts'
 import type {
+  AudioSource,
   ChatOptions,
   ChatResult,
+  EmbedOptions,
+  EmbedResult,
   GenerateResult,
   Message,
   StreamEvent,
+  ToolUseBlock,
+  TranscribeOptions,
+  TranscribeResult,
 } from './types.ts'
 
 export interface RunWithToolsOptions extends ChatOptions {
@@ -37,6 +47,63 @@ export interface RunWithToolsOptions extends ChatOptions {
    * resulting `mcp_tool_use` / `mcp_tool_result` blocks.
    */
   mcpServers?: readonly MCPServer[]
+  /**
+   * Tool-error recovery hook. Called when a tool's `execute` throws
+   * — OR when the model called a tool that isn't registered. Two
+   * outcomes:
+   *
+   *   - Return a string → the loop continues. The string lands as
+   *     `tool_result.content` with `isError: true`, the model sees
+   *     the error and can adapt (try a different approach, ask the
+   *     user, give up). Recommended for production agents that
+   *     should survive transient failures.
+   *
+   *   - Return `undefined` (the default when this option is unset)
+   *     → the framework throws `ToolExecutionError` and the loop
+   *     aborts. Same behavior as before this option existed.
+   *
+   * The hook may inspect `error.cause` to filter — e.g., feed back
+   * transient HTTP errors but rethrow programmer errors:
+   *
+   * ```ts
+   * onToolError: (err) =>
+   *   err.cause instanceof TransientError ? err.cause.message : undefined
+   * ```
+   */
+  onToolError?(error: ToolExecutionError): string | undefined
+  /**
+   * Human-in-the-loop gate. Called before each tool execution; when
+   * it returns `true`, the loop suspends and `runWithTools` returns
+   * a `SuspendedRun` carrying the pending tool calls + a JSON-
+   * serializable snapshot of the loop state. Apps obtain results
+   * out-of-band (human approval, queued worker, external system,
+   * ...) and call `brain.resumeTools(state, results, tools, options)`
+   * to continue.
+   *
+   * Mid-batch invariant: if a tool call inside a multi-call batch
+   * triggers suspension, the framework also captures all unexecuted
+   * siblings from the same assistant turn — the provider's
+   * `tool_use` / `tool_result` pairing must stay balanced on resume.
+   *
+   * V1 scope: only honored on non-streaming `runWithTools`. Pass it
+   * to `streamWithTools`, `runWithToolsAndSchema`, or
+   * `streamWithToolsAndSchema` and the framework throws `BrainError`
+   * — those entrypoints don't yet model the pause/resume protocol.
+   */
+  shouldSuspend?(
+    call: ToolUseBlock,
+    context?: Record<string, unknown>,
+  ): boolean | Promise<boolean>
+}
+
+/**
+ * Same as `RunWithToolsOptions` but with `shouldSuspend` required.
+ * Used to narrow the return type of `runWithTools` overloads — when
+ * apps opt in to the human-in-the-loop gate, the result widens to
+ * `AgentResult | SuspendedRun`; otherwise it's just `AgentResult`.
+ */
+export type RunWithToolsOptionsWithSuspend = RunWithToolsOptions & {
+  shouldSuspend: NonNullable<RunWithToolsOptions['shouldSuspend']>
 }
 
 export interface Provider {
@@ -81,7 +148,7 @@ export interface Provider {
     messages: readonly Message[],
     tools: readonly Tool[],
     options?: RunWithToolsOptions,
-  ): Promise<AgentResult>
+  ): Promise<AgentResult | SuspendedRun>
 
   /**
    * Structured output. Sends `messages` to the model with a
@@ -99,4 +166,81 @@ export interface Provider {
     schema: OutputSchema<T>,
     options?: ChatOptions,
   ): Promise<GenerateResult<T>>
+
+  /**
+   * Tool-loop + structured output combined. Runs the agentic loop
+   * with the same tool-handling as `runWithTools`, but pins a
+   * JSON-Schema constraint on every turn — so when the model
+   * finally answers without calling a tool, its text is JSON
+   * matching the schema. Returns the parsed value alongside the
+   * loop bookkeeping.
+   *
+   * Optional on the interface; `BrainManager.generateWithTools`
+   * throws `BrainError` when the configured provider lacks it.
+   */
+  runWithToolsAndSchema?<T>(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    schema: OutputSchema<T>,
+    options?: RunWithToolsOptions,
+  ): Promise<AgentGenerateResult<T>>
+
+  /**
+   * Streaming variant of `runWithToolsAndSchema`. Same agentic loop,
+   * same schema constraint on every turn — yielded as
+   * `AgentStreamEvent<T>`s. The terminal `stop` event carries the
+   * parsed `value` + raw `text` alongside the loop bookkeeping.
+   *
+   * Optional; `BrainManager.streamGenerateWithTools` throws
+   * `BrainError` when the chosen provider doesn't implement it.
+   */
+  streamWithToolsAndSchema?<T>(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    schema: OutputSchema<T>,
+    options?: RunWithToolsOptions,
+  ): AsyncIterable<AgentStreamEvent<T>>
+
+  /**
+   * Streaming variant of `runWithTools`. Yields `AgentStreamEvent`s
+   * as the 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.
+   *
+   * Optional — providers without a streaming tool-loop implementation
+   * can omit it; `BrainManager.streamTools` throws `BrainError` in
+   * that case.
+   */
+  streamWithTools?(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options?: RunWithToolsOptions,
+  ): AsyncIterable<AgentStreamEvent>
+
+  /**
+   * Embeddings — turn one or more text inputs into vectors for
+   * similarity search / RAG / clustering. Optional because not
+   * every provider exposes an embeddings endpoint (V1: Anthropic
+   * and DeepSeek don't; OpenAI, Gemini, Ollama do).
+   */
+  embed?(
+    texts: readonly string[],
+    options?: EmbedOptions,
+  ): Promise<EmbedResult>
+
+  /**
+   * Audio transcription — convert an audio clip to text.
+   * Complements `AudioBlock` (which sends audio + text together
+   * to a multimodal chat model) by exposing the dedicated
+   * transcription endpoint where the provider has one. V1:
+   * OpenAI (Whisper / gpt-4o-transcribe), Ollama (inherits via
+   * OpenAI-compat), Gemini (chat-wrap fallback — internally
+   * sends an AudioBlock with a "transcribe verbatim" prompt).
+   * Anthropic + DeepSeek throw — no transcription API.
+   */
+  transcribe?(
+    audio: AudioSource,
+    options?: TranscribeOptions,
+  ): Promise<TranscribeResult>
 }