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

package/src/suspended_run.ts

@@ -0,0 +1,153 @@
+/**
+ * `SuspendedRun` — what `runWithTools` (and `runner.run()`) returns
+ * when the agentic loop pauses because `shouldSuspend(call)` returned
+ * `true` for a tool the model wants to call.
+ *
+ * Use case: human-in-the-loop gating. The integrator inspects
+ * `pendingToolCalls`, obtains results out-of-band (human approval,
+ * external worker, queued job, ...), and calls
+ * `brain.resumeTools(state, results, ...)` or
+ * `runner.resume(state, results)` to continue the conversation.
+ *
+ * State model:
+ *   - `state.messages` contains every message exchanged up to and
+ *     including the assistant turn that requested the pending tool
+ *     calls. Resume picks up by appending tool_result blocks for
+ *     each pending call and re-entering the loop — no special
+ *     provider-level resume hook is needed.
+ *   - `state` is plain JSON — apps persist it across process
+ *     boundaries (e.g., one row per pending agent run in Postgres).
+ *
+ * Mid-batch invariant: when a tool call in a multi-call batch
+ * triggers suspension, ALL remaining calls in that same batch are
+ * captured together in `pendingToolCalls`. Apps MUST supply results
+ * for every entry on resume; otherwise the provider's
+ * tool_use / tool_result pairing becomes unbalanced and the next
+ * model call rejects.
+ */
+
+import { BrainError } from './brain_error.ts'
+import type {
+  ChatUsage,
+  ContentBlock,
+  Message,
+  ToolResultBlock,
+  ToolUseBlock,
+} from './types.ts'
+
+export interface SuspendedRun {
+  status: 'suspended'
+  /**
+   * The model's pending tool calls — the one that triggered the
+   * suspension, plus any unexecuted siblings from the same
+   * assistant turn. Match by `id` when supplying results.
+   */
+  pendingToolCalls: ToolUseBlock[]
+  /** JSON-serializable snapshot of the loop state at the suspension point. */
+  state: SuspendedState
+}
+
+export interface SuspendedState {
+  /** Full message history up to and including the suspending assistant turn. */
+  messages: Message[]
+  /** Iteration count at the suspension point — preserved across resume. */
+  iterations: number
+  /** Aggregated token usage across the iterations completed so far. */
+  usage: ChatUsage
+  /**
+   * Provider response id captured at the suspension point. When the
+   * provider supports stateful conversations (OpenAI Responses API),
+   * resume threads this back through `previousResponseId` so the
+   * model picks up exactly where it paused.
+   */
+  responseId?: string
+}
+
+/**
+ * Result of one pending tool call, supplied to `resumeTools`. The
+ * shape mirrors `ToolResultBlock` minus the `type` discriminator —
+ * the framework builds the block at resume time.
+ *
+ * To signal a failure (so the model adapts rather than crashing the
+ * loop), pass a string describing the error as `content` and set
+ * `isError: true`.
+ */
+export interface ToolResultInput {
+  toolUseId: string
+  content: string
+  isError?: boolean
+}
+
+/**
+ * Type guard. Convenient at call sites that need to discriminate
+ * between a completed `AgentResult` and a `SuspendedRun`.
+ *
+ * ```ts
+ * const out = await brain.runTools(prompt, tools, { shouldSuspend })
+ * if (isSuspended(out)) {
+ *   await persistForLater(out.pendingToolCalls, out.state)
+ *   return
+ * }
+ * render(out.text)
+ * ```
+ */
+export function isSuspended(value: unknown): value is SuspendedRun {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { status?: unknown }).status === 'suspended'
+  )
+}
+
+/**
+ * Append a `tool_result` user-role message to `state.messages` that
+ * carries one block per supplied result. Validates that the pending
+ * tool_use ids referenced in the latest assistant turn are all
+ * covered — missing results throw `BrainError` so the next provider
+ * call doesn't fail with an opaque "tool_use without tool_result"
+ * upstream error.
+ *
+ * Exported for `BrainManager.resumeTools` / `AgentRunner.resume`;
+ * tests can use it directly to verify resume mechanics without
+ * round-tripping through a provider.
+ */
+export function appendResumeResults(
+  state: SuspendedState,
+  results: readonly ToolResultInput[],
+): Message[] {
+  const pending = collectPendingIds(state.messages)
+  for (const id of pending) {
+    if (!results.some((r) => r.toolUseId === id)) {
+      throw new BrainError(
+        `resumeTools: missing result for pending tool call id "${id}". Every pending tool_use in the suspending assistant turn must be answered on resume.`,
+        { context: { pendingIds: [...pending], suppliedIds: results.map((r) => r.toolUseId) } },
+      )
+    }
+  }
+  const resultBlocks: ContentBlock[] = results.map((r) => {
+    const block: ToolResultBlock = {
+      type: 'tool_result',
+      toolUseId: r.toolUseId,
+      content: r.content,
+      ...(r.isError ? { isError: true } : {}),
+    }
+    return block
+  })
+  return [...state.messages, { role: 'user', content: resultBlocks }]
+}
+
+/**
+ * Look at the latest assistant turn in `messages` and pull every
+ * tool_use block's id. Used to validate resume coverage.
+ */
+function collectPendingIds(messages: readonly Message[]): string[] {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]!
+    if (m.role !== 'assistant') continue
+    if (typeof m.content === 'string') return []
+    return m.content
+      .filter((b): b is ToolUseBlock => b.type === 'tool_use')
+      .map((b) => b.id)
+  }
+  return []
+}

package/src/thread.ts

@@ -35,6 +35,14 @@ export interface ThreadState {
   messages: Message[]
   system?: SystemPrompt
   options?: ChatOptions
+  /**
+   * Last provider response id captured by `send(...)` — restored on
+   * `fromJSON` so subsequent sends thread it via
+   * `ChatOptions.previousResponseId` automatically. Only ever set
+   * when the underlying provider surfaces `responseId` (OpenAI
+   * Responses API today).
+   */
+  lastResponseId?: string
 }
 
 export class Thread {
@@ -42,6 +50,13 @@ export class Thread {
   readonly messages: Message[] = []
   readonly system?: SystemPrompt
   readonly options?: ChatOptions
+  /**
+   * Last response id returned by the provider on this thread. Used to
+   * thread stateful-conversation hints (OpenAI Responses API) into
+   * the next `send(...)` so apps don't have to manage it manually.
+   * `undefined` for providers that don't surface a response id.
+   */
+  lastResponseId?: string
   private readonly brain: BrainManager
 
   constructor(brain: BrainManager, opts: ThreadOptions = {}) {
@@ -54,6 +69,11 @@ export class Thread {
    * Append a user turn, call the model, append the assistant reply,
    * and return the reply text. Per-call options override the
    * thread's defaults; `system` always comes from the thread.
+   *
+   * When the underlying provider supports stateful conversations
+   * (OpenAI Responses API), `previousResponseId` is auto-threaded
+   * from the prior turn — apps don't need to manage it. Per-call
+   * `options.previousResponseId` wins if supplied explicitly.
    */
   async send(text: string, options: ChatOptions = {}): Promise<string> {
     this.messages.push({ role: 'user', content: text })
@@ -65,8 +85,25 @@ export class Thread {
       // mid-thread by changing the system prompt every turn.
       ...(this.system !== undefined ? { system: this.system } : {}),
     }
+    if (
+      merged.previousResponseId === undefined &&
+      this.lastResponseId !== undefined
+    ) {
+      merged.previousResponseId = this.lastResponseId
+    }
     const result = await this.brain.chat(this.messages, merged)
-    this.messages.push({ role: 'assistant', content: result.text })
+    // Preserve structured assistant content when present (compaction
+    // blocks today; reasoning blocks later). Round-tripping these
+    // back to the provider on subsequent sends is what makes
+    // server-side compaction actually save tokens — once a turn
+    // carries a `compaction` block, the older raw turns drop out
+    // and the model only re-reads the summary.
+    if (result.content !== undefined && result.content.length > 0) {
+      this.messages.push({ role: 'assistant', content: result.content })
+    } else {
+      this.messages.push({ role: 'assistant', content: result.text })
+    }
+    if (result.responseId !== undefined) this.lastResponseId = result.responseId
     return result.text
   }
 
@@ -80,6 +117,7 @@ export class Thread {
     const state: ThreadState = { messages: [...this.messages] }
     if (this.system !== undefined) state.system = this.system
     if (this.options !== undefined) state.options = this.options
+    if (this.lastResponseId !== undefined) state.lastResponseId = this.lastResponseId
     return state
   }
 
@@ -94,6 +132,7 @@ export class Thread {
     if (state.options !== undefined) options.options = state.options
     const thread = new Thread(brain, options)
     for (const m of state.messages) thread.messages.push(m)
+    if (state.lastResponseId !== undefined) thread.lastResponseId = state.lastResponseId
     return thread
   }
 }

package/src/tool.ts

@@ -23,6 +23,13 @@ export interface ToolContext {
   readonly callId: string
   /** Per-run free-form context bag passed by the caller. Optional. */
   readonly context: Readonly<Record<string, unknown>>
+  /**
+   * Cancellation signal forwarded from the run's `options.signal`.
+   * Tools that wrap network calls (HTTP fetches, MCP servers, child
+   * processes) should pass this through so cancellation actually
+   * unwinds in-flight work.
+   */
+  readonly signal?: AbortSignal
 }
 
 export interface Tool<TInput = unknown, TOutput = unknown> {

package/src/tool_runner.ts

@@ -0,0 +1,81 @@
+/**
+ * `runToolWithRecovery` — shared helper used by every provider's
+ * agentic loop to execute one tool call.
+ *
+ * Encapsulates two error paths and the optional `onToolError`
+ * recovery callback:
+ *
+ *   1. **Tool not registered** — the model called a name that
+ *      isn't in `toolMap`. Without recovery, throw
+ *      `ToolExecutionError`. With recovery, the callback's return
+ *      string becomes the `tool_result.content` (with `isError:
+ *      true`) and the loop continues — the model sees "unknown
+ *      tool" and adapts.
+ *
+ *   2. **`execute()` throws** — the tool's body raised. Same
+ *      pattern: either rethrow as `ToolExecutionError` or feed
+ *      back as an error result.
+ *
+ * The returned shape is the framework-agnostic `{ content, isError }`
+ * pair each provider then wraps into its own `tool_result` block
+ * shape (Anthropic `tool_result` with `is_error`; OpenAI tool-role
+ * message content; Gemini `functionResponse` with `{ error }`).
+ */
+
+import type { RunWithToolsOptions } from './provider.ts'
+import type { Tool, ToolContext } from './tool.ts'
+import { ToolExecutionError } from './tool_execution_error.ts'
+
+export interface ToolRunResult {
+  content: string
+  isError: boolean
+}
+
+export async function runToolWithRecovery(
+  tool: Tool | undefined,
+  toolName: string,
+  callId: string,
+  input: unknown,
+  options: RunWithToolsOptions,
+): Promise<ToolRunResult> {
+  if (!tool) {
+    return recoverOrThrow(
+      new ToolExecutionError(
+        toolName,
+        callId,
+        new Error(`Tool "${toolName}" is not registered.`),
+      ),
+      options,
+    )
+  }
+
+  const ctx: ToolContext = {
+    callId,
+    context: options.context ?? {},
+    ...(options.signal !== undefined ? { signal: options.signal } : {}),
+  }
+  let output: unknown
+  try {
+    output = await tool.execute(input, ctx)
+  } catch (cause) {
+    return recoverOrThrow(new ToolExecutionError(toolName, callId, cause), options)
+  }
+  return {
+    content: typeof output === 'string' ? output : JSON.stringify(output),
+    isError: false,
+  }
+}
+
+/**
+ * Resolve a `ToolExecutionError` through the `onToolError` callback
+ * (when set) or rethrow. Used by providers for failures that happen
+ * outside `tool.execute` — e.g., OpenAI's JSON-parse-arguments path.
+ */
+export function recoverOrThrow(
+  error: ToolExecutionError,
+  options: RunWithToolsOptions,
+): ToolRunResult {
+  const recovered = options.onToolError?.(error)
+  if (typeof recovered !== 'string') throw error
+  return { content: recovered, isError: true }
+}