agent-accelerator 0.5.2 → 0.5.4

package/src/session/tool-log.ts

@@ -0,0 +1,62 @@
+/**
+ * One log file per tool call, inside the session folder: `tool-logs/<n>-<tool>.ndjson`. The executor writes its own
+ * steps into it (input, attempts, retries, result or error, duration) and a tool adds its own with `ctx.log(...)`.
+ * Every line is flushed to disk as it is written, so after a crash the file shows how far the call got. The file is for
+ * developers and harnesses: it is never sent to the model, and nothing in the SDK reads it back.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fsyncFolder } from "../utils/durable.ts";
+
+/** The log of one tool call, as the executor sees it. */
+export interface ToolLogWriter {
+  /** Path relative to the session folder (`tool-logs/003-send_email.ndjson`); saved on the call's result. */
+  readonly file: string;
+  /** Appends one line (`timestamp` is added) and flushes it. Never throws. */
+  write(entry: Record<string, unknown>): void;
+  /** Closes the file; later writes (a tool still running after a timeout) are ignored. */
+  close(): void;
+}
+
+/** Hands out the log files of one session folder, numbering them in the order the calls start. */
+export class ToolLogs {
+  private next: number | undefined;
+
+  constructor(private readonly sessionDir: string) {}
+
+  // Opens `tool-logs/<n>-<tool>.ndjson` for one call; the numbering continues after files from earlier runs and restarts; in: a tool call as the executor starts it, out: the writer the executor and `ctx.log` write through.
+  open(call: { name: string }): ToolLogWriter | undefined {
+    const dir = path.join(this.sessionDir, "tool-logs");
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      this.next ??= fs.readdirSync(dir).reduce((max, f) => Math.max(max, Number(/^(\d+)-/.exec(f)?.[1] ?? 0)), 0) + 1;
+      const name = `${String(this.next++).padStart(3, "0")}-${call.name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64)}.ndjson`;
+      const fd = fs.openSync(path.join(dir, name), "a", 0o600);
+      fsyncFolder(dir);
+      let open = true;
+      return {
+        file: `tool-logs/${name}`,
+        write(entry) {
+          if (!open) return;
+          try {
+            fs.writeSync(fd, JSON.stringify({ timestamp: Date.now(), ...entry }) + "\n");
+            fs.fdatasyncSync(fd);
+          } catch {
+            // why: a full disk must never fail the tool call being logged.
+          }
+        },
+        close() {
+          if (!open) return;
+          open = false;
+          try {
+            fs.closeSync(fd);
+          } catch {
+            // why: nothing left to flush.
+          }
+        },
+      };
+    } catch {
+      return undefined; // logging is best effort: the call runs without a log
+    }
+  }
+}

package/src/session/usage.ts

@@ -0,0 +1,201 @@
+/**
+ * What one agent spent on ITS OWN model calls, kept exactly: tokens as the provider reported them, cost in integer
+ * micro-USD priced per turn (so cache hits, cache writes and price tiers are right), plus where each turn's price came
+ * from. Every agent records its own turns and saves them in its session; `usageReport()` then adds the agent and its
+ * workers up WITHOUT counting anything twice (a parent's `AgentResponse.usage` already contains its workers' usage, so
+ * responses are never summed). Pure functions, no Agent import.
+ */
+import type { TokenUsage } from "../types/core.ts";
+import type { PricedCost } from "./store.ts";
+
+/** Raw totals of one agent's own model calls, as saved in its session (`usage`). */
+export interface UsageTotals {
+  /** Model calls made. */
+  turns: number;
+  /** Input tokens; they INCLUDE the cache reads and writes. */
+  inputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  /** Output tokens; they INCLUDE the thinking tokens. */
+  outputTokens: number;
+  thinkingTokens: number;
+  /** Integer micro-USD, summed over the turns that had a price. */
+  costMicroUSD: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };
+  /** Turns by where their price came from: the provider's reported cost, the catalog, or nowhere (unknown pricing). */
+  turnsBy: { provider: number; catalog: number; unpriced: number };
+}
+
+/** A zeroed {@link UsageTotals}. */
+export function emptyUsage(): UsageTotals {
+  return {
+    turns: 0,
+    inputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens: 0,
+    thinkingTokens: 0,
+    costMicroUSD: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    turnsBy: { provider: 0, catalog: 0, unpriced: 0 },
+  };
+}
+
+const count = (n: unknown): number => (typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : 0);
+
+/** A model reference (string or catalog spec) as a plain string for a report line. */
+export function modelName(model: unknown): string {
+  return typeof model === "string" ? model : String((model as { id?: unknown } | null | undefined)?.id ?? "unknown");
+}
+
+/** Adds one model call (`priced` from `priceUsage`; undefined = unknown pricing, which is counted but never turned into $0). */
+export function addTurn(totals: UsageTotals, usage: TokenUsage, priced: PricedCost | undefined): void {
+  const input = count(usage.inputTokens);
+  const output = count(usage.outputTokens);
+  totals.turns += 1;
+  totals.inputTokens += input;
+  totals.outputTokens += output;
+  totals.cacheReadTokens += Math.min(count(usage.cachedTokens ?? usage.cacheReadTokens), input);
+  totals.cacheWriteTokens += Math.min(count(usage.cacheWriteTokens), input);
+  totals.thinkingTokens += Math.min(count(usage.thinkingTokens), output);
+  if (!priced) {
+    totals.turnsBy.unpriced += 1;
+    return;
+  }
+  totals.turnsBy[priced.source === "provider" ? "provider" : "catalog"] += 1;
+  const b = priced.breakdown;
+  totals.costMicroUSD.input += b.inputMicroUSD;
+  totals.costMicroUSD.output += b.outputMicroUSD + b.audioMicroUSD;
+  totals.costMicroUSD.cacheRead += b.cacheReadMicroUSD;
+  totals.costMicroUSD.cacheWrite += b.cacheWriteMicroUSD;
+  totals.costMicroUSD.total += b.totalMicroUSD;
+}
+
+/** Adds `other` into `into` (workers into a total). */
+export function mergeUsage(into: UsageTotals, other: UsageTotals): void {
+  for (const k of ["turns", "inputTokens", "cacheReadTokens", "cacheWriteTokens", "outputTokens", "thinkingTokens"] as const) into[k] += other[k];
+  for (const k of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) into.costMicroUSD[k] += other.costMicroUSD[k];
+  for (const k of ["provider", "catalog", "unpriced"] as const) into.turnsBy[k] += other.turnsBy[k];
+}
+
+/** Reads saved totals back defensively (a hand-edited or older file never breaks a load); unusable input gives zeros. */
+export function readUsage(saved: unknown): UsageTotals {
+  const out = emptyUsage();
+  const s = saved as Partial<UsageTotals> | null | undefined;
+  if (!s || typeof s !== "object") return out;
+  for (const k of ["turns", "inputTokens", "cacheReadTokens", "cacheWriteTokens", "outputTokens", "thinkingTokens"] as const) out[k] = count(s[k]);
+  for (const k of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) out.costMicroUSD[k] = count(s.costMicroUSD?.[k]);
+  for (const k of ["provider", "catalog", "unpriced"] as const) out.turnsBy[k] = count(s.turnsBy?.[k]);
+  return out;
+}
+
+/** Where a total's price came from: `provider` (the provider's reported cost), `catalog`, `mixed` (both), or `unknown` (no turn had a price). */
+export type CostSource = "provider" | "catalog" | "mixed" | "unknown";
+
+/** One agent's (or the whole session's) spending in a form made to be read: tokens, cache hit rate, cost. */
+export interface UsageLine {
+  /** Model calls made. */
+  turns: number;
+  tokens: {
+    /** Everything sent: `freshInput + cacheRead + cacheWrite`. */
+    input: number;
+    /** Input that was neither read from nor written to the cache. */
+    freshInput: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** Everything generated, thinking included. */
+    output: number;
+    /** The part of `output` that was thinking. */
+    thinking: number;
+    total: number;
+  };
+  /** `cacheRead / input` from 0 to 1; `null` when nothing was sent. */
+  cacheHitRate: number | null;
+  cost: {
+    source: CostSource;
+    /** Turns with no known price: when above 0 the totals are a lower bound. */
+    unpricedTurns: number;
+    /** USD; `null` when no turn had a price (unknown is never shown as 0). */
+    totalUsd: number | null;
+    /** The parts, in USD. For turns whose cost the provider reported, only the total is exact: the parts then add up to less than `totalUsd`. Absent when unknown. */
+    parts?: { inputUsd: number; outputUsd: number; cacheReadUsd: number; cacheWriteUsd: number };
+  };
+}
+
+/** Turns raw totals into a readable {@link UsageLine}. */
+export function usageLine(t: UsageTotals): UsageLine {
+  const priced = t.turnsBy.provider + t.turnsBy.catalog;
+  const source: CostSource = priced === 0 ? "unknown" : t.turnsBy.provider > 0 && t.turnsBy.catalog > 0 ? "mixed" : t.turnsBy.provider > 0 ? "provider" : "catalog";
+  const usd = (micro: number): number => micro / 1_000_000;
+  const c = t.costMicroUSD;
+  return {
+    turns: t.turns,
+    tokens: {
+      input: t.inputTokens,
+      freshInput: Math.max(0, t.inputTokens - t.cacheReadTokens - t.cacheWriteTokens),
+      cacheRead: t.cacheReadTokens,
+      cacheWrite: t.cacheWriteTokens,
+      output: t.outputTokens,
+      thinking: t.thinkingTokens,
+      total: t.inputTokens + t.outputTokens,
+    },
+    cacheHitRate: t.inputTokens > 0 ? t.cacheReadTokens / t.inputTokens : null,
+    cost: {
+      source,
+      unpricedTurns: t.turnsBy.unpriced,
+      totalUsd: priced === 0 ? null : usd(c.total),
+      ...(priced === 0 ? {} : { parts: { inputUsd: usd(c.input), outputUsd: usd(c.output), cacheReadUsd: usd(c.cacheRead), cacheWriteUsd: usd(c.cacheWrite) } }),
+    },
+  };
+}
+
+/** One worker in the usage tree, with raw totals (the report turns them into lines). */
+export interface UsageNode {
+  id: string;
+  name: string;
+  role?: string;
+  model: string;
+  status: "open" | "closed" | "fixed";
+  totals: UsageTotals;
+  workers: UsageNode[];
+}
+
+/** An agent or worker line of a {@link UsageReport}. */
+export interface AgentUsage extends UsageLine {
+  id: string;
+  name: string;
+  model: string;
+}
+
+/** A worker line, with the workers it started (`open` and `closed` are `subagents`/`agent.workers` workers, `fixed` is a `subagents: [...]` worker). */
+export interface WorkerUsage extends AgentUsage {
+  role?: string;
+  status: "open" | "closed" | "fixed";
+  workers: WorkerUsage[];
+}
+
+/** What `agent.usageReport()` returns. `agent` is the agent's own model calls only; `total` is the agent plus every worker below it. */
+export interface UsageReport {
+  agent: AgentUsage;
+  workers: WorkerUsage[];
+  total: UsageLine;
+}
+
+// Adds a node and everything below it into `into`; in: a usage tree, out: the whole-session total.
+function sumTree(into: UsageTotals, nodes: UsageNode[]): void {
+  for (const n of nodes) {
+    mergeUsage(into, n.totals);
+    sumTree(into, n.workers);
+  }
+}
+
+// One node as a report line, children included; in: a usage node, out: UsageReport.workers.
+function nodeLine(n: UsageNode): WorkerUsage {
+  return { id: n.id, name: n.name, ...(n.role ? { role: n.role } : {}), model: n.model, status: n.status, ...usageLine(n.totals), workers: n.workers.map(nodeLine) };
+}
+
+/** Builds the report from the agent's own totals and its worker tree. */
+export function buildUsageReport(own: { id: string; name: string; model: string; totals: UsageTotals }, workers: UsageNode[]): UsageReport {
+  const total = emptyUsage();
+  mergeUsage(total, own.totals);
+  sumTree(total, workers);
+  return { agent: { id: own.id, name: own.name, model: own.model, ...usageLine(own.totals) }, workers: workers.map(nodeLine), total: usageLine(total) };
+}

package/src/telemetry-file.ts

@@ -4,12 +4,14 @@
  * Each event is a single synchronous append, so a process crash keeps every
  * event already emitted: a `tool.call_started` with no ending event was in
  * flight, and the last `tool.progress` shows how far it got. Power loss is not
- * covered (no fsync). `turn.thinking` (full reasoning text) is never written.
+ * covered (no fsync, by design: this is observability, not state). `turn.thinking`
+ * (full reasoning text) is never written. Takes the home's one-process lock.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { telemetryBus } from "./telemetry.ts";
 import { safeStringify } from "./utils/serialization.ts";
+import { lockFolder } from "./utils/durable.ts";
 
 const sinks = new Set<string>();
 
@@ -17,6 +19,7 @@ const sinks = new Set<string>();
 export function persistTelemetry(home: string): void {
   const dir = path.join(home, "telemetry");
   if (sinks.has(dir)) return;
+  lockFolder(home);
   sinks.add(dir);
   telemetryBus.onEvent((event) => {
     if (event.code === "turn.thinking") return;

package/src/tools/executor.ts

@@ -9,6 +9,7 @@ import { ConfigError } from "../types/errors.ts";
 import { isSubagentResult } from "./subagent-result.ts";
 import { isTruncatedArguments } from "../types/tool.ts";
 import { telemetryBus } from "../telemetry.ts";
+import type { ToolLogWriter } from "../session/tool-log.ts";
 
 export interface ExecuteToolsOptions {
   tools: Record<string, ToolDefinition>;
@@ -17,6 +18,10 @@ export interface ExecuteToolsOptions {
   parallel?: boolean;
   signal?: AbortSignal;
   sessionId?: string;
+  /** Called the moment EACH call finishes (before the whole batch does), so a caller can save a result before the next tool is done. Never throws into the run. */
+  onResult?: (result: ToolResultRecord) => void;
+  /** Opens the log file of one call (only when the Agent persists to a folder); the executor writes its steps into it and `ctx.log` writes through it. */
+  openToolLog?: (call: ToolCallRecord, sessionId: string | undefined) => ToolLogWriter | undefined;
   /** Forwards live sub-agent deltas (realtime worker thinking/text) to the caller. */
   onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }
@@ -52,6 +57,14 @@ export function normalizeToolName(name: string): string {
     .toLowerCase();
 }
 
+// Thrown by `ctx.stop(reason)` to unwind the tool's code at once; the executor turns it into a stopped result and never retries it.
+class ToolStopSignal extends Error {
+  constructor() {
+    super("The tool ended the run with ctx.stop()");
+    this.name = "ToolStopSignal";
+  }
+}
+
 /** Default cap for string tool results kept for model context. */
 export const DEFAULT_MAX_RESULT_CHARS = 20000;
 
@@ -467,7 +480,7 @@ async function executeAttempt(
 export async function executeToolCalls(
   options: ExecuteToolsOptions
 ): Promise<ToolResultRecord[]> {
-  const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent } = options;
+  const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent, onResult, openToolLog } = options;
   assertNoToolCollisions(tools);
   const globalSemaphore = new Semaphore(DEFAULT_TOOL_CONCURRENCY);
   const perToolSemaphores = new Map<string, Semaphore>();
@@ -485,8 +498,14 @@ export async function executeToolCalls(
   };
 
   const scope = { agentName, sessionId };
-  const runSingle = async (call: ToolCallRecord): Promise<ToolResultRecord> => {
+  const runSingle = async (call: ToolCallRecord, log: ToolLogWriter | undefined): Promise<ToolResultRecord> => {
     const startTime = nowMs();
+    // Every lifecycle step goes to the telemetry bus AND this call's log file.
+    const trace = (phase: string, level: "info" | "warn" | "error", data: Record<string, unknown> = {}): void => {
+      traceToolEvent(phase, level, call, scope, data);
+      log?.write({ phase, level, ...data });
+    };
+    log?.write({ phase: "input", name: call.name, input: toJsonSafe(call.arguments) });
     // Latest `ctx.emit({ type: "progress", ... })` snapshot: what the tool had finished before any failure.
     let progress: unknown;
     let attempts = 0;
@@ -497,7 +516,7 @@ export async function executeToolCalls(
     // finishReason here — return a synthetic error so the model retries with
     // complete JSON.
     if (isTruncatedToolCall(call)) {
-      traceToolEvent("call_blocked", "warn", call, scope, { reason: "truncated_arguments" });
+      trace("call_blocked", "warn", { reason: "truncated_arguments" });
       return {
         id: call.id,
         name: call.name,
@@ -513,7 +532,7 @@ export async function executeToolCalls(
     const toolDef = resolved.definition;
 
     if (!toolDef) {
-      traceToolEvent("call_blocked", "warn", call, scope, { reason: "tool_not_found", suggestion: resolved.suggestion });
+      trace("call_blocked", "warn", { reason: "tool_not_found", suggestion: resolved.suggestion });
       const suffix = resolved.suggestion ? ` Did you mean '${resolved.suggestion}'?` : "";
       return {
         id: call.id,
@@ -527,6 +546,12 @@ export async function executeToolCalls(
     let releaseGlobal: (() => void) | undefined;
     let releaseTool: (() => void) | undefined;
     let executionStartTime = startTime;
+    // Set by `ctx.stop(reason)`: the call's result becomes the reason and the run ends after this batch.
+    let stopReason: string | undefined;
+    const stoppedResult = (): ToolResultRecord => {
+      trace("call_stopped", "warn", { reason: stopReason, attempts, durationMs: elapsedMs(executionStartTime) });
+      return { id: call.id, name: resolved.name, result: stopReason, isError: false, stopped: true, durationMs: elapsedMs(executionStartTime) };
+    };
 
     try {
       if (signal?.aborted) {
@@ -542,9 +567,14 @@ export async function executeToolCalls(
         signal,
         sessionId,
         onSubagentEvent,
+        stop: (reason: string): never => {
+          stopReason ??= String(reason);
+          throw new ToolStopSignal();
+        },
+        log: (message, data) => log?.write({ phase: "log", message, ...(data !== undefined ? { data: toJsonSafe(data) } : {}) }),
         emit: (event) => {
           if (event?.type === "progress") progress = event;
-          traceToolEvent(event?.type === "progress" ? "progress" : "event", "info", call, scope, { event: capJson(event) });
+          trace(event?.type === "progress" ? "progress" : "event", "info", { event: capJson(event) });
         },
       };
 
@@ -565,7 +595,7 @@ export async function executeToolCalls(
           const hint = expectedParams
             ? ` Expected parameters: ${expectedParams}.`
             : "";
-          traceToolEvent("call_blocked", "warn", call, scope, { reason: "schema_validation", detail: parseRes.error.message });
+          trace("call_blocked", "warn", { reason: "schema_validation", detail: parseRes.error.message });
           return {
             id: call.id,
             name: call.name,
@@ -597,20 +627,21 @@ export async function executeToolCalls(
       executionStartTime = nowMs();
       let rawResult: unknown;
       let attempt = 0;
-      traceToolEvent("call_started", "info", call, scope, { maxAttempts, timeoutMs });
+      trace("call_started", "info", { maxAttempts, timeoutMs });
       while (true) {
         attempt++;
         attempts = attempt;
-        traceToolEvent("attempt_started", "info", call, scope, { attempt, maxAttempts });
+        trace("attempt_started", "info", { attempt, maxAttempts });
         try {
           rawResult = await executeAttempt(toolDef, parsedInput, context, timeoutMs);
           break;
         } catch (err: any) {
           if (signal?.aborted) throw new Error("Tool execution aborted");
+          if (stopReason !== undefined) throw err; // ctx.stop: not a failure, never retried
           timedOut = err?.toolTimeout === true;
           const willRetry =
             isTransientError(err) && attempt < maxAttempts && !(err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0));
-          traceToolEvent("attempt_failed", "warn", call, scope, { attempt, maxAttempts, willRetry, error: describeError(err), progress: capJson(progress) });
+          trace("attempt_failed", "warn", { attempt, maxAttempts, willRetry, error: describeError(err), progress: capJson(progress) });
           if (!isTransientError(err) || attempt >= maxAttempts) throw err;
           // A timeout is a deliberate per-attempt deadline, not a parent
           // cancellation (which rejects via the abort signal instead and is
@@ -620,15 +651,19 @@ export async function executeToolCalls(
           // tool body, but a tool that ignores the signal still resolves.
           if (err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0)) throw err;
           const delayMs = Math.min(30_000, 250 * 2 ** Math.min(attempt - 1, 7));
-          traceToolEvent("retry_scheduled", "info", call, scope, { attempt, nextAttempt: attempt + 1, delayMs });
+          trace("retry_scheduled", "info", { attempt, nextAttempt: attempt + 1, delayMs });
           await waitForRetry(delayMs, signal);
         }
       }
 
+      if (stopReason !== undefined) return stoppedResult(); // the tool caught the stop signal but the run still stops
+
       // Undefined means "no value", serialized null-safe as "null" (changed
       // from the legacy "Success" marker so model context stays valid JSON).
+      // The log keeps the full result (the model gets a capped copy below).
+      log?.write({ phase: "result", result: isSubagentResult(rawResult) ? rawResult.xml : toJsonSafe(rawResult) });
       const finishOk = (resultChars: number): void =>
-        traceToolEvent("call_succeeded", "info", call, scope, { attempts: attempt, durationMs: elapsedMs(executionStartTime), resultChars });
+        trace("call_succeeded", "info", { attempts: attempt, durationMs: elapsedMs(executionStartTime), resultChars });
       if (rawResult === undefined) {
         finishOk(4);
         return {
@@ -676,8 +711,9 @@ export async function executeToolCalls(
       // scrubbed message plus what the tool finished before failing, so it repairs
       // only the remainder instead of repeating completed side effects.
       const aborted = signal?.aborted === true;
+      if (stopReason !== undefined && !aborted) return stoppedResult();
       const done = err?.context?.progress ?? progress;
-      traceToolEvent(aborted ? "call_aborted" : timedOut ? "call_timed_out" : "call_failed", "error", call, scope, {
+      trace(aborted ? "call_aborted" : timedOut ? "call_timed_out" : "call_failed", "error", {
         attempts,
         durationMs: elapsedMs(executionStartTime),
         error: describeError(err),
@@ -726,14 +762,35 @@ export async function executeToolCalls(
     }
   };
 
+  // Runs one call and reports its result at once; a throwing observer must not fail the run.
+  const runAndReport = async (call: ToolCallRecord): Promise<ToolResultRecord> => {
+    let log: ToolLogWriter | undefined;
+    try {
+      log = openToolLog?.(call, sessionId);
+    } catch {
+      log = undefined; // logging is best effort: the call runs without a log
+    }
+    let result: ToolResultRecord;
+    try {
+      result = await runSingle(call, log);
+    } finally {
+      log?.close();
+    }
+    if (log) result.logFile = log.file;
+    try {
+      onResult?.(result);
+    } catch {
+      // why: observers (persistence) are best-effort.
+    }
+    return result;
+  };
   if (parallel && toolCalls.length > 1) {
-    const results = await Promise.all(toolCalls.map((tc) => runSingle(tc)));
-    return results;
+    return Promise.all(toolCalls.map((tc) => runAndReport(tc)));
   }
 
   const results: ToolResultRecord[] = [];
   for (const tc of toolCalls) {
-    results.push(await runSingle(tc));
+    results.push(await runAndReport(tc));
   }
   return results;
 }

package/src/tools/subagent-result.ts

@@ -2,7 +2,7 @@ import type { SubAgentExecutionMetadata } from "../types/response.ts";
 
 /**
  * Module-private brand proving a tool result was produced by the SDK's own
- * delegation tools (`agentToTool` / `spawn_subagents`). Symbols cannot be
+ * delegation tools (`agentToTool` / the `subagents` tool). Symbols cannot be
  * forged by JSON a tool fetched from the web, so only branded results get
  * their `_subagentMetadata` trusted (usage/cost rolled up, XML shown to the
  * model).

package/src/tools/tool.ts

@@ -143,11 +143,6 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
   retry?: { maxRetries?: number; baseDelayMs?: number; maxDelayMs?: number };
   /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */
   tags?: string[];
-  /**
-   * When true, the host must approve this call before execution. Stored only;
-   * enforcement is wired by the host, default open.
-   */
-  needsApproval?: boolean;
   /**
    * Optional output schema (Zod or JSON Schema, stored as `unknown` so `zod`
    * stays optional for type-only consumers).
@@ -208,7 +203,6 @@ export function tool<TInput = any, TOutput = any>(
     ...(options.redact !== undefined ? { redact: options.redact } : {}),
     ...(options.retry !== undefined ? { retry: options.retry } : {}),
     ...(options.tags !== undefined ? { tags: options.tags } : {}),
-    ...(options.needsApproval !== undefined ? { needsApproval: options.needsApproval } : {}),
     ...(options.output !== undefined ? { output: options.output } : {}),
     ...(options.maxAttempts !== undefined ? { maxAttempts: options.maxAttempts } : {}),
   } as ToolDefinition<TInput, TOutput>;

package/src/types/agent.ts

@@ -133,6 +133,21 @@ export interface AgentConfig {
    * Writes are atomic and never fail a turn.
    */
   persist?: { dir?: string; file?: string };
+  /**
+   * How many times a run that FAILED for a transient reason (provider down or overloaded, timeouts, a cut stream, after
+   * the provider layer's own `retry` gave up) is tried again from where it stopped, with a growing wait (5 s, 15 s, 45 s,
+   * then 60 s). Default 3; `0` turns it off. Finished tool calls are not repeated. Never for aborts, bad config or input
+   * (401/400/...), budgets or limits. Applies to `run()` and queued runs, not to `stream()`. The final response also reports the
+   * tool calls, results, turns and token usage of the failed attempts (they happened and cost money).
+   */
+  runRetries?: number;
+  /**
+   * What happens to a run a crash cut off (needs `persist: { dir }` and the SAME `sessionId` after the restart).
+   * `"automatic"` (default): the Agent continues it as soon as it is constructed (tool calls that already have a saved
+   * result are not run again), then runs any prompts that were waiting. `"explicit"`: nothing runs until you call
+   * `agent.resume()`; `agent.interrupted()` lists what was cut off.
+   */
+  resume?: "automatic" | "explicit";
   /**
    * Folder for everything Agent Accelerator writes to disk (`sessions/`,
    * `scheduled_actions/`, `telemetry/`). Defaults to `setHome()`, then the `AGENT_ACCEL_HOME` env var, then `.agent-accel/` in the working directory.
@@ -214,6 +229,17 @@ export interface AgentConfig {
   limits?: AgentRunLimits;
 }
 
+/** A run that a crash cut off (see {@link Agent.interrupted}). */
+export interface InterruptedRun {
+  runId: string;
+  /** Epoch ms when the run began. */
+  startedAt: number;
+  /** Preview of the prompt that started it. */
+  prompt: string;
+  /** Names of tool calls it had asked for that have no result yet. */
+  pendingToolCalls: string[];
+}
+
 /** Per-request + run limits (Q-22). */
 export interface AgentRunLimits {
   maxTurns?: number;
@@ -252,7 +278,7 @@ export interface MidSessionConfig {
 
 /** Developer-configured policy for LLM-spawned dynamic sub-agents. */
 export interface DynamicSubagentsConfig {
-  /** Enables the automatic `spawn_subagents` tool. Defaults to true when the object is present. */
+  /** Adds the `subagents` tool (spawn, message, close, list persistent workers). Defaults to true when the object is present; `agent.workers` works either way. */
   enabled?: boolean;
   /**
    * Lets the Main Agent schedule dynamic sub-agents to run later (once or on
@@ -262,22 +288,35 @@ export interface DynamicSubagentsConfig {
   allowScheduledActions?: boolean;
   /** Developer-only worker model override. Never choosable by the Main Agent LLM. Falls back to top-level `subagentModel`, then `SUB_AGENT_MODEL` env, then the parent model. */
   model?: string | ModelSpec | ModelProviderInstance;
-  /** Max workers the Main Agent may spawn in a single `spawn_subagents` call. Extras are trimmed safely. Defaults to 4. */
+  /** Max workers that may be open at once on this agent (the model must close one before spawning another). Defaults to 4. */
   maxSpawn?: number;
   /** Fixed reasoning level for all dynamic workers. The Main Agent cannot override it. Falls back to the parent level when omitted. */
   thinkingLevel?: ThinkingLevel;
+  /**
+   * Spending cap of EACH worker (the `subagents` tool, `agent.workers` and scheduled actions), set as that worker's own
+   * per-run `budget`: a spawn, a message or a scheduled run is one run, and the usage of the worker's own workers counts
+   * toward it. Exceeding it fails that call with a budget error and leaves the worker open. Default: unlimited. Models
+   * with unknown pricing count $0 toward `maxCostUsd`. Passed down to the workers' own workers.
+   */
+  workerBudget?: Pick<Budget, "maxCostUsd" | "maxTotalTokens">;
+  /**
+   * How many levels of workers may exist below this agent (default 3). `1` = workers cannot start workers of their own;
+   * `3` = a worker may start workers that start workers. A worker with levels left gets its own `subagents` tool, and
+   * its children can only be granted the tools the worker itself was granted. Whole number >= 1.
+   */
+  maxDepth?: number;
   /** Tool pool available to dynamic workers. Workers receive zero tools unless the Main Agent grants a per-task `tools` subset by name. */
   tools?: Record<string, ToolDefinition> | ToolDefinition[];
-  /** Per-worker timeout in ms. `0` (default) = no limit. `-1` = the Main Agent sets a per-task `timeoutMs`. `>0` = fixed timeout for every worker. */
+  /** Per-run timeout in ms of a SCHEDULED ACTION's worker (the `subagents` tool and `agent.workers` have no timeouts). `0` (default) = no limit. `-1` = the action sets its own `timeoutMs`. `>0` = fixed. */
   timeout?: number;
   /**
-   * Canonical per-worker timeout in ms (Q-52, preferred over `timeout`).
+   * Canonical timeout in ms for scheduled-action workers (Q-52, preferred over `timeout`).
    * Maps to `timeout`: `workerTimeoutMs ?? timeout ?? 0`. See
    * `normalizeWorkerTimeout` (re-exported from the root entry).
    */
   workerTimeoutMs?: number;
   /**
-   * When true, the Main Agent sets a per-task `timeoutMs` (maps to
+   * Scheduled actions only: when true, each action sets its own `timeoutMs` (maps to
    * `timeout: -1`). When both are set, an explicit `timeout`/`workerTimeoutMs`
    * wins over `modelMaySetTimeout`.
    */
@@ -363,7 +402,7 @@ export interface Budget {
   maxTotalTokens?: number;
   /** Maximum wall/monotonic duration in ms since budget tracking started. */
   maxDurationMs?: number;
-  /** Maximum total dynamic sub-agents spawned via `spawn_subagents`. */
+  /** Maximum total dynamic sub-agents spawned in one run (`subagents` tool or `agent.workers.spawn`). */
   maxTotalSubagents?: number;
 }
 

package/src/types/message.ts

@@ -85,6 +85,10 @@ export interface ToolResultPart {
   name: string;
   result: unknown;
   isError?: boolean;
+  /** This call's log file, relative to the session folder (see `ToolExecutionContext.log`). */
+  logFile?: string;
+  /** The tool ended the run with `ctx.stop(reason)` (see `ToolExecutionContext.stop`). */
+  stopped?: boolean;
 }
 
 /** Provider reasoning/thinking content. */

package/src/types/response.ts

@@ -60,6 +60,7 @@ export type FinishReason =
   | "content_filter"
   | "refusal"
   | "max_turns"
+  | "stopped"
   | "error"
   | (string & {});
 
@@ -88,6 +89,7 @@ export function normalizeFinishReason(raw?: string): {
     length: "length",
     max_tokens: "length",
     max_turns: "max_turns",
+    stopped: "stopped",
     content_filter: "content_filter",
     refusal: "refusal",
     refused: "refusal",