@strav/brain 0.3.22 → 0.3.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "type": "module",
   "description": "AI module for the Strav framework",
   "license": "MIT",
@@ -15,10 +15,10 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@strav/kernel": "0.3.22"
+    "@strav/kernel": "0.3.24"
   },
   "dependencies": {
-    "@strav/workflow": "0.3.22",
+    "@strav/workflow": "0.3.24",
     "zod": "^3.25 || ^4.0"
   },
   "scripts": {

package/src/agent.ts

@@ -62,6 +62,26 @@ export abstract class Agent {
   /** Called when the model requests a tool call, before execution. */
   onToolCall?(call: ToolCall): void | Promise<void>
 
+  /**
+   * 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.
+   */
+  shouldSuspend?(
+    call: ToolCall,
+    context: Record<string, unknown>
+  ): boolean | Promise<boolean>
+
   /** Called after a tool finishes execution. */
   onToolResult?(call: ToolCallRecord): void | Promise<void>
 

package/src/helpers.ts

@@ -20,6 +20,9 @@ import type {
   Usage,
   JsonSchema,
   SerializedThread,
+  SerializedAgentState,
+  SuspendedRun,
+  ToolCallResult,
 } from './types.ts'
 
 // ── Shared tool executor ─────────────────────────────────────────────────────
@@ -257,8 +260,57 @@ export class AgentRunner<T extends Agent = Agent> {
     return this
   }
 
-  /** Run the agent to completion. */
-  async run(): Promise<AgentResult> {
+  /** Run the agent to completion (or until it suspends on a tool call). */
+  async run(): Promise<AgentResult | SuspendedRun> {
+    return this.runFromState(null)
+  }
+
+  /**
+   * Resume a previously suspended agent run with the results of the pending
+   * tool calls. Returns a completed `AgentResult` — or another `SuspendedRun`
+   * if the continuation itself hits another suspending tool call.
+   *
+   * `toolResults` must contain one entry per call in the original
+   * `SuspendedRun.pendingToolCalls`, matched by `toolCallId`. To signal a
+   * rejection, pass a string or object describing the error as the
+   * `result` — the model sees it as a normal tool failure and adapts.
+   */
+  async resume(
+    state: SerializedAgentState,
+    toolResults: ToolCallResult[]
+  ): Promise<AgentResult | SuspendedRun> {
+    const hydratedMessages: Message[] = [...state.messages]
+    const hydratedToolCalls: ToolCallRecord[] = [...state.allToolCalls]
+
+    for (const r of toolResults) {
+      const originalCall = findToolCallInMessages(hydratedMessages, r.toolCallId)
+
+      hydratedMessages.push({
+        role: 'tool',
+        toolCallId: r.toolCallId,
+        content: typeof r.result === 'string' ? r.result : JSON.stringify(r.result),
+      })
+
+      hydratedToolCalls.push({
+        name: originalCall?.name ?? '',
+        arguments: originalCall?.arguments ?? {},
+        result: r.result,
+        duration: 0,
+      })
+    }
+
+    return this.runFromState({
+      messages: hydratedMessages,
+      allToolCalls: hydratedToolCalls,
+      totalUsage: { ...state.totalUsage },
+      iterations: state.iterations,
+    })
+  }
+
+  /** Shared loop body. Used by both `run()` (fresh state) and `resume()` (restored state). */
+  private async runFromState(
+    initial: SerializedAgentState | null
+  ): Promise<AgentResult | SuspendedRun> {
     const agent = new this.AgentClass()
     const config = BrainManager.config
 
@@ -274,11 +326,13 @@ export class AgentRunner<T extends Agent = Agent> {
     const maxTokens = agent.maxTokens ?? config.maxTokens
     const temperature = agent.temperature ?? config.temperature
 
-    try {
-      await agent.onStart?.(this._input, this._context)
-    } catch (err) {
-      await agent.onError?.(err instanceof Error ? err : new Error(String(err)))
-      throw err
+    if (!initial) {
+      try {
+        await agent.onStart?.(this._input, this._context)
+      } catch (err) {
+        await agent.onError?.(err instanceof Error ? err : new Error(String(err)))
+        throw err
+      }
     }
 
     // Build system prompt with context interpolation
@@ -295,10 +349,14 @@ export class AgentRunner<T extends Agent = Agent> {
       schema = zodToJsonSchema(agent.output)
     }
 
-    const messages: Message[] = [{ role: 'user', content: this._input }]
-    const allToolCalls: ToolCallRecord[] = []
-    const totalUsage: Usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
-    let iterations = 0
+    const messages: Message[] = initial
+      ? [...initial.messages]
+      : [{ role: 'user', content: this._input }]
+    const allToolCalls: ToolCallRecord[] = initial ? [...initial.allToolCalls] : []
+    const totalUsage: Usage = initial
+      ? { ...initial.totalUsage }
+      : { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+    let iterations = initial?.iterations ?? 0
 
     // Tool loop
     while (iterations < maxIterations) {
@@ -374,8 +432,16 @@ export class AgentRunner<T extends Agent = Agent> {
         return result
       }
 
-      // Execute tool calls
-      await this.executeTools(agent, response.toolCalls, messages, allToolCalls)
+      // Execute tool calls (or suspend if the agent vetos)
+      const suspension = await this.executeTools(
+        agent,
+        response.toolCalls,
+        messages,
+        allToolCalls,
+        totalUsage,
+        iterations
+      )
+      if (suspension) return suspension
     }
 
     // Max iterations reached — return what we have
@@ -519,8 +585,28 @@ export class AgentRunner<T extends Agent = Agent> {
         return
       }
 
-      // Execute tools and yield events
-      for (const toolCall of toolCalls) {
+      // Execute tools and yield events (or suspend if the agent vetos)
+      for (let i = 0; i < toolCalls.length; i++) {
+        const toolCall = toolCalls[i]!
+
+        if (agent.shouldSuspend) {
+          const suspend = await agent.shouldSuspend(toolCall, this._context)
+          if (suspend) {
+            const suspended: SuspendedRun = {
+              status: 'suspended',
+              pendingToolCalls: toolCalls.slice(i),
+              state: {
+                messages: [...messages],
+                allToolCalls: [...allToolCalls],
+                totalUsage: { ...totalUsage },
+                iterations,
+              },
+            }
+            yield { type: 'suspended', suspended }
+            return
+          }
+        }
+
         await agent.onToolCall?.(toolCall)
 
         const start = performance.now()
@@ -565,9 +651,31 @@ export class AgentRunner<T extends Agent = Agent> {
     agent: Agent,
     toolCalls: ToolCall[],
     messages: Message[],
-    allToolCalls: ToolCallRecord[]
-  ): Promise<void> {
-    for (const toolCall of toolCalls) {
+    allToolCalls: ToolCallRecord[],
+    totalUsage: Usage,
+    iterations: number
+  ): Promise<SuspendedRun | null> {
+    for (let i = 0; i < toolCalls.length; i++) {
+      const toolCall = toolCalls[i]!
+
+      if (agent.shouldSuspend) {
+        const suspend = await agent.shouldSuspend(toolCall, this._context)
+        if (suspend) {
+          // Capture this call + all remaining calls in the batch so the
+          // provider's tool_use/tool_result contract stays balanced on resume.
+          return {
+            status: 'suspended',
+            pendingToolCalls: toolCalls.slice(i),
+            state: {
+              messages: [...messages],
+              allToolCalls: [...allToolCalls],
+              totalUsage: { ...totalUsage },
+              iterations,
+            },
+          }
+        }
+      }
+
       await agent.onToolCall?.(toolCall)
 
       const start = performance.now()
@@ -585,7 +693,25 @@ export class AgentRunner<T extends Agent = Agent> {
 
       messages.push(message)
     }
+    return null
+  }
+}
+
+// ── Helpers for resume ───────────────────────────────────────────────────────
+
+/**
+ * Walk `messages` backwards and find the `ToolCall` (on an assistant message)
+ * whose id matches `toolCallId`. Returns undefined if not found.
+ */
+function findToolCallInMessages(messages: Message[], toolCallId: string): ToolCall | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]!
+    if (m.role === 'assistant' && m.toolCalls) {
+      const call = m.toolCalls.find(c => c.id === toolCallId)
+      if (call) return call
+    }
   }
+  return undefined
 }
 
 // ── Thread ────────────────────────────────────────────────────────────────────

package/src/index.ts

@@ -34,6 +34,9 @@ export type {
   BeforeHook,
   AfterHook,
   SerializedThread,
+  SerializedAgentState,
+  SuspendedRun,
+  ToolCallResult,
   OutputSchema,
 } from './types.ts'
 export type { ChatOptions, GenerateOptions, GenerateResult, EmbedOptions } from './helpers.ts'

package/src/types.ts

@@ -112,11 +112,51 @@ export interface AgentResult<T = any> {
 }
 
 export interface AgentEvent {
-  type: 'text' | 'tool_start' | 'tool_result' | 'iteration' | 'done'
+  type: 'text' | 'tool_start' | 'tool_result' | 'iteration' | 'done' | 'suspended'
   text?: string
   toolCall?: ToolCallRecord
   iteration?: number
   result?: AgentResult
+  suspended?: SuspendedRun
+}
+
+// ── Suspend / Resume ─────────────────────────────────────────────────────────
+
+/**
+ * A JSON-serializable snapshot of an agent loop at the moment it suspended.
+ *
+ * All fields are plain data — no functions, class instances, or cycles — so
+ * the snapshot can be stringified, stored across a process boundary, and
+ * later passed to `AgentRunner.resume()` to continue the run.
+ */
+export interface SerializedAgentState {
+  messages: Message[]
+  allToolCalls: ToolCallRecord[]
+  totalUsage: Usage
+  iterations: number
+}
+
+/**
+ * Result of an agent run that was suspended before executing one or more
+ * tool calls. The integrator is expected to obtain tool results out-of-band
+ * (human approval, external system, queued job, etc.) and call
+ * `AgentRunner.resume(state, toolResults)` to continue.
+ *
+ * `pendingToolCalls` contains the pending call that triggered suspension
+ * plus any subsequent tool calls from the same batch that have not been
+ * executed. Results must be supplied for each of them on resume so the
+ * conversation remains well-formed for the provider.
+ */
+export interface SuspendedRun {
+  status: 'suspended'
+  pendingToolCalls: ToolCall[]
+  state: SerializedAgentState
+}
+
+/** Result of a pending tool call, supplied to `AgentRunner.resume()`. */
+export interface ToolCallResult {
+  toolCallId: string
+  result: unknown
 }
 
 // ── Workflow ──────────────────────────────────────────────────────────────────

package/src/workflow.ts

@@ -2,7 +2,7 @@ import { Workflow as BaseWorkflow } from '@strav/workflow'
 import type { WorkflowContext as BaseContext } from '@strav/workflow'
 import { AgentRunner } from './helpers.ts'
 import type { Agent } from './agent.ts'
-import type { AgentResult, WorkflowResult, Usage } from './types.ts'
+import type { AgentResult, SuspendedRun, WorkflowResult, Usage } from './types.ts'
 
 // ── AI Workflow Context ─────────────────────────────────────────────────────
 
@@ -27,6 +27,20 @@ function addUsage(total: Usage, add: Usage): void {
   total.totalTokens += add.totalTokens
 }
 
+// Workflow orchestration runs agents to completion; suspension is a standalone
+// primitive on AgentRunner. Surface a clear error rather than silently swallowing.
+function assertCompleted(
+  result: AgentResult | SuspendedRun,
+  stepName: string
+): asserts result is AgentResult {
+  if ((result as SuspendedRun).status === 'suspended') {
+    throw new Error(
+      `Workflow step "${stepName}" suspended — Workflow does not support agent suspension. ` +
+        `Use AgentRunner.run()/resume() directly, or ensure workflow agents don't define shouldSuspend.`
+    )
+  }
+}
+
 // ── Workflow Builder ────────────────────────────────────────────────────────
 
 /**
@@ -60,6 +74,7 @@ export class Workflow {
     this.pipeline.step(name, async (ctx: BaseContext) => {
       const inputText = resolveInput(mapInput, ctx)
       const result = await new AgentRunner(agent).input(inputText).run()
+      assertCompleted(result, name)
       addUsage(this.totalUsage, result.usage)
       return result
     })
@@ -81,6 +96,7 @@ export class Workflow {
         handler: async (ctx: BaseContext) => {
           const inputText = resolveInput(a.mapInput, ctx)
           const result = await new AgentRunner(a.agent).input(inputText).run()
+          assertCompleted(result, `${name}.${a.name}`)
           addUsage(this.totalUsage, result.usage)
           return result
         },
@@ -104,6 +120,7 @@ export class Workflow {
     this.pipeline.step(`${name}:router`, async (ctx: BaseContext) => {
       const inputText = resolveInput(mapInput, ctx)
       const result = await new AgentRunner(router).input(inputText).run()
+      assertCompleted(result, `${name}:router`)
       addUsage(this.totalUsage, result.usage)
       return result
     })
@@ -121,6 +138,7 @@ export class Workflow {
           async (ctx: BaseContext) => {
             const inputText = resolveInput(mapInput, ctx)
             const result = await new AgentRunner(BranchAgent).input(inputText).run()
+            assertCompleted(result, `${name}:${key}`)
             addUsage(this.totalUsage, result.usage)
             return result
           },
@@ -148,6 +166,7 @@ export class Workflow {
       name,
       async (input: unknown, _ctx: BaseContext) => {
         const result = await new AgentRunner(agent).input(String(input)).run()
+        assertCompleted(result, name)
         addUsage(this.totalUsage, result.usage)
         return result
       },