agent-accelerator 0.5.2 → 0.5.4

package/src/agent/agent.ts

@@ -1,16 +1,20 @@
-import type { AgentConfig, AgentRunOptions, MidSessionConfig, ToolChoiceOption, RetryPolicyConfig, Budget, BudgetState } from "../types/agent.ts";
+import type { AgentConfig, AgentRunOptions, MidSessionConfig, ToolChoiceOption, RetryPolicyConfig, Budget, BudgetState, InterruptedRun } from "../types/agent.ts";
 import type { TokenUsage } from "../types/core.ts";
 import type { ProviderRequestOptions } from "../types/model.ts";
 import { normalizeThinkingV2, resolveWhenBusy, normalizeWorkerTimeout } from "../tools/tool.ts";
-import type { ToolDefinition } from "../types/tool.ts";
+import type { ToolDefinition, ToolResultRecord } from "../types/tool.ts";
+import { isSubagentResult } from "../tools/subagent-result.ts";
 import { CACHE_OPTIONS, type ThinkingLevel, type ThinkingConfig, type CacheOption, type ServiceTier } from "../types/core.ts";
 import type { ContentPart } from "../types/message.ts";
 import { AgentResponse, type StreamEvent } from "../types/response.ts";
 import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 import { AgentContext } from "./context.ts";
 import { resolveModel } from "../providers/registry.ts";
-import { buildAgentTools, createSubagentSpawnTool } from "./delegation.ts";
+import { buildAgentTools } from "./delegation.ts";
+import { createSubagentsTool } from "./subagents-tool.ts";
+import { WorkerRegistry } from "./workers.ts";
 import {
+  DEFAULT_MAX_DEPTH,
   normalizeToolMap,
   resolveDynamicModelInput,
   resolveMainModel,
@@ -19,10 +23,12 @@ import * as path from "node:path";
 import { registerAgent } from "../scheduler/scheduler.ts";
 import { resolveHome } from "../scheduler/store.ts";
 import { persistTelemetry } from "../telemetry-file.ts";
+import { lockFolder } from "../utils/durable.ts";
 import { createScheduledActionsTool, getDatetimeTool } from "../scheduler/tool.ts";
 import { assertNoToolCollisions } from "../tools/executor.ts";
-import { runAgentLoop, streamAgentLoop, type SteerEntry } from "./loop.ts";
-import { createSessionId, nowMs } from "../utils/session.ts";
+import { runAgentLoop, streamAgentLoop, unfinishedToolCalls, endsWithStop, accumulateUsage, type SteerEntry } from "./loop.ts";
+import { isRetryableRun, readRetryAfterMs, sleep } from "../utils/retry.ts";
+import { createSessionId, nowMs, newRunId } from "../utils/session.ts";
 import {
   chargeBudgetUsage,
   checkBudget,
@@ -31,7 +37,10 @@ import {
   listSubAgentTraceIdsForSessions,
   type SubAgentTrace,
 } from "./delegation.ts";
-import { saveSessionDir, saveSessionFile, findInvalidMessage, telemetryBus } from "../session/store.ts";
+import { addTurn, buildUsageReport, emptyUsage, mergeUsage, modelName, readUsage, type UsageNode, type UsageReport, type UsageTotals } from "../session/usage.ts";
+import { saveSessionFile, sessionDirFor, loadSessionDir, findInvalidMessage, priceUsage, telemetryBus, type SessionRunMark, type SessionRunEnd, type SessionPending, type SessionToolRecord } from "../session/store.ts";
+import { SessionJournal } from "../session/journal.ts";
+import { ToolLogs, type ToolLogWriter } from "../session/tool-log.ts";
 import { isLocalPathInput } from "../utils/safe-io.ts";
 import { clearSessionRouting, normalizeStructuredOutput, normalizeStop } from "../providers.ts";
 import type { StructuredOutputSpec } from "../types/model.ts";
@@ -53,7 +62,7 @@ export function resolveEffectiveThinking(
   return { enabled: true, level: overrideLevel as ThinkingConfig["level"] };
 }
 
-import { ConfigError, SessionLoadError } from "../types/errors.ts";
+import { ConfigError, SessionLoadError, isAbortError } from "../types/errors.ts";
 
 /**
  * Disposers for the manual user-signal forward listeners (Q-21 fallback when
@@ -62,6 +71,9 @@ import { ConfigError, SessionLoadError } from "../types/errors.ts";
  */
 const mergeDisposers = new WeakMap<AbortController, () => void>();
 
+/** Waits before run retry 1, 2, 3 ... (the last one repeats). Module-level so tests can shrink it; not public API. */
+export const RUN_RETRY_DELAYS_MS: number[] = [5_000, 15_000, 45_000, 60_000];
+
 /** Max named sessions kept per Agent (Q-19a LRU). */
 const SESSION_LRU_MAX = 100;
 /** Idle TTL for named sessions (Q-19a). */
@@ -159,6 +171,10 @@ export class Agent {
     timeout: number;
     /** Scheduled actions (`scheduled_actions` + `get_datetime` tools) are on. */
     allowScheduledActions: boolean;
+    /** Levels of workers allowed below this agent. */
+    maxDepth: number;
+    /** Per-run spending cap of each worker (unset = unlimited). */
+    workerBudget?: { maxCostUsd?: number; maxTotalTokens?: number };
   };
   /** Home folder for everything written to disk (`sessions/`, `scheduled_actions/`, `telemetry/`). */
   readonly home: string;
@@ -246,6 +262,26 @@ export class Agent {
   private sessions = new Map<string, { context: AgentContext; lastAccess: number }>();
   /** Coalesced persistence single-flight flag (Q-28). */
   private persistScheduled = false;
+  /** Step journal of the persisted session folder (dir mode only). */
+  private journal?: SessionJournal;
+  /** Log files of tool calls in the persisted session folder (dir mode only). */
+  private toolLogs?: ToolLogs;
+  private toolLogsDir?: string;
+  /** Where each run of the default session began (saved with the session). @internal */
+  readonly runMarks: SessionRunMark[] = [];
+  /** Tool calls finished in the current run; saved the moment each finishes so a crash never repeats them. @internal */
+  readonly toolRecords: SessionToolRecord[] = [];
+  /** What this agent spent on its OWN model calls (workers keep their own); saved with the session. @internal */
+  readonly usageTotals: UsageTotals = emptyUsage();
+  /** The run in flight (its mark has no ending yet, but it is not "interrupted"). */
+  private activeMark?: SessionRunMark;
+  /** What to do with a cut-off run at construction (see `AgentConfig.resume`). */
+  private readonly resumeMode: "automatic" | "explicit";
+  /** How often a failed run is tried again (see `AgentConfig.runRetries`). */
+  private readonly runRetries: number;
+  /** The resume in flight, so a second `resume()` returns the same promise. */
+  private resuming?: Promise<AgentResponse | undefined>;
+  private workerRegistry?: WorkerRegistry;
 
   /**
    * Creates an agent and registers its model, tools, cache, and delegation settings.
@@ -282,6 +318,17 @@ export class Agent {
     const dynEnabled = dynRaw ? (dynRaw.enabled ?? true) : false;
     if (dynRaw) {
       const dynTools = normalizeToolMap((dynRaw as { tools?: Record<string, ToolDefinition> | ToolDefinition[] }).tools);
+      const rawDepth = (dynRaw as { maxDepth?: unknown }).maxDepth;
+      if (rawDepth !== undefined && !(Number.isInteger(rawDepth) && (rawDepth as number) >= 1)) {
+        throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.maxDepth ${JSON.stringify(rawDepth)}: expected a whole number >= 1 (default ${DEFAULT_MAX_DEPTH}); set dynamicSubagents.enabled: false to turn workers off.`);
+      }
+      const rawBudget = (dynRaw as { workerBudget?: { maxCostUsd?: unknown; maxTotalTokens?: unknown } }).workerBudget;
+      for (const key of ["maxCostUsd", "maxTotalTokens"] as const) {
+        const v = rawBudget?.[key];
+        if (v !== undefined && !(typeof v === "number" && Number.isFinite(v) && v > 0)) {
+          throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.workerBudget.${key} ${JSON.stringify(v)}: expected a number greater than 0, or omit it for no limit.`);
+        }
+      }
       const rawMax = (dynRaw as any)?.maxSpawn;
       const maxSpawn = Number.isFinite(rawMax) ? Math.max(1, Math.floor(rawMax as number)) : 4;
       // `workerTimeoutMs ?? timeout`, or -1 when `modelMaySetTimeout` (see normalizeWorkerTimeout).
@@ -294,6 +341,8 @@ export class Agent {
         tools: dynTools,
         timeout,
         allowScheduledActions: dynRaw.allowScheduledActions === true,
+        maxDepth: (rawDepth as number | undefined) ?? DEFAULT_MAX_DEPTH,
+        ...(rawBudget ? { workerBudget: { ...(rawBudget as { maxCostUsd?: number; maxTotalTokens?: number }) } } : {}),
       };
     }
     this.apiKey = (rawModel as any)?.apiKey || config.apiKey;
@@ -313,6 +362,11 @@ export class Agent {
       config.persist && !config.persist.dir && !config.persist.file
         ? { ...config.persist, dir: path.join(this.home, "sessions") }
         : config.persist;
+    // One process per folder: fail fast here, before anything is written (the home for `persist: {}`, else the folder named).
+    if (config.persist) {
+      const { dir, file } = config.persist;
+      lockFolder(dir ?? (file ? path.dirname(path.resolve(file)) : this.home));
+    }
     // `whenBusy` (canonical) wins over legacy `mode`; anything else is "auto".
     const normalizedMode = resolveWhenBusy(config.midSession);
     const rawMaxQueued = (config.midSession as any)?.maxQueued;
@@ -347,6 +401,14 @@ export class Agent {
       );
     }
     this.cache = config.cache;
+    if (config.resume !== undefined && config.resume !== "automatic" && config.resume !== "explicit") {
+      throw new ConfigError(`[Agent Accelerator] Invalid resume ${JSON.stringify(config.resume)}: expected "automatic" (default) or "explicit".`);
+    }
+    this.resumeMode = config.resume ?? "automatic";
+    if (config.runRetries !== undefined && !(Number.isInteger(config.runRetries) && config.runRetries >= 0)) {
+      throw new ConfigError(`[Agent Accelerator] Invalid runRetries ${JSON.stringify(config.runRetries)}: expected a whole number >= 0 (default 3, 0 turns it off).`);
+    }
+    this.runRetries = config.runRetries ?? 3;
 
     this.serviceTier = config.serviceTier;
     this.onFailure =
@@ -400,8 +462,8 @@ export class Agent {
       );
     }
     if (dyn?.enabled === true) {
-      const spawnTool = createSubagentSpawnTool(this);
-      this.tools[spawnTool.name || "spawn_subagents"] = spawnTool;
+      const subagentsTool = createSubagentsTool(this);
+      this.tools[subagentsTool.name || "subagents"] = subagentsTool;
     }
     if (dyn?.allowScheduledActions) {
       // Fixed by config, so the tool set (and the prompt cache) stays stable.
@@ -415,6 +477,157 @@ export class Agent {
 
     this.context = new AgentContext(this.getFullInstructions());
     if (dyn?.allowScheduledActions) registerAgent(this);
+    if (this.recoverSession() && this.resumeMode === "automatic") {
+      // Synchronously, so a run() issued right after construction queues BEHIND the resumed run.
+      this.resume().catch((err) => this.reportResumeFailure(err));
+    }
+  }
+
+  /** The persistent sub-agent workers of this agent: `spawn`, `message`, `close`, `list`, `turns` (see `WorkerRegistry`). */
+  get workers(): WorkerRegistry {
+    return (this.workerRegistry ??= new WorkerRegistry(this));
+  }
+
+  // Loads a persisted session that a crash cut off (a run without an ending) or that still had waiting prompts, so it can be resumed; true when there is something to resume; in: the session folder of `persist.dir`, out: context, runMarks, toolRecords, pendingQueue.
+  private recoverSession(): boolean {
+    const root = this.persistConfig?.dir;
+    if (!root || this.stateless) return false;
+    let dir: string;
+    try {
+      dir = sessionDirFor(root, this.sessionId);
+    } catch {
+      return false; // not a usable session id for a folder name: nothing was ever saved under it
+    }
+    const session = loadSessionDir(dir)?.session; // a session over the load limits throws SessionLoadError: better than overwriting it
+    if (!session) return false;
+    const waiting = [...(session.pending?.steer ?? []), ...(session.pending?.queue ?? [])];
+    if (!(session.runs ?? []).some((r) => !r.end) && waiting.length === 0) return false;
+    this.context.messages = session.messages;
+    this.runMarks.splice(0, this.runMarks.length, ...(session.runs ?? []));
+    this.restoreUsage(session.usage);
+    const open = new Set(unfinishedToolCalls(this.context.messages).map((c) => c.id));
+    this.toolRecords.splice(0, this.toolRecords.length, ...(session.tools ?? []).filter((t) => open.has(t.id)));
+    for (const w of waiting) {
+      this.pendingQueue.push({
+        prompt: w.prompt,
+        options: w.additionalContext ? { additionalContext: w.additionalContext } : undefined,
+        isStream: false,
+        resolve: () => {},
+        reject: (err) => this.reportResumeFailure(err),
+      });
+    }
+    return true;
+  }
+
+  // Puts saved spending totals back after a restart or import (zeros when the file has none); in: a loaded session's `usage`, out: this.usageTotals.
+  private restoreUsage(saved: unknown): void {
+    Object.assign(this.usageTotals, readUsage(saved));
+  }
+
+  // Records one model call of THIS agent (priced per turn, with the service tier); in: the loop's onTurnUsage, out: this.usageTotals (saved by the next persist).
+  private recordTurnUsage(usage: TokenUsage, spec: Parameters<typeof priceUsage>[1]): void {
+    addTurn(this.usageTotals, usage, priceUsage(usage, spec, this.serviceTier ? { serviceTier: this.serviceTier } : undefined));
+  }
+
+  /** Adds another agent's spending to this one (a fixed worker's per-call copy into its template). @internal */
+  absorbUsage(other: UsageTotals): void {
+    mergeUsage(this.usageTotals, other);
+  }
+
+  /**
+   * What this agent and every worker below it spent: per agent and per worker (tokens, cache hits, thinking, exact
+   * cost per turn) plus a whole-session total, with nothing counted twice. `agent` is this agent's own model calls;
+   * workers (open, closed, nested, and rebuilt from disk after a restart) and fixed `subagents` workers are listed
+   * below it. Spending of one-shot scheduled-action workers is in their run files, not here.
+   */
+  usageReport(): UsageReport {
+    return buildUsageReport({ id: this.sessionId, name: this.name, model: modelName(this.modelStringOrSpec), totals: this.usageTotals }, [...this.workers.usageNodes(), ...this.fixedWorkerNodes()]);
+  }
+
+  // The `subagents: [...]` workers as usage nodes (their per-call copies' spending is merged into them); in: the constructor config, out: usageReport.
+  private fixedWorkerNodes(): UsageNode[] {
+    const nodes: UsageNode[] = [];
+    for (const entry of this.forkConfig.subagents ?? []) {
+      const worker = "agent" in entry ? entry.agent : entry;
+      const name = "agent" in entry ? entry.name : worker.name;
+      nodes.push({ id: name, name, model: modelName(worker.modelStringOrSpec), status: "fixed", totals: worker.usageTotals, workers: [] });
+    }
+    return nodes;
+  }
+
+  // Says on the telemetry bus that resuming (or a prompt that was waiting) failed; in: a rejected resume, out: telemetryBus.
+  private reportResumeFailure(err: unknown): void {
+    telemetryBus.emitWarning("agent.resume_failed", `[Agent Accelerator] Resuming session ${this.sessionId} failed: ${err instanceof Error ? err.message : String(err)}`, { sessionId: this.sessionId });
+  }
+
+  /** Runs that a crash cut off (they began, never ended and are not running now), oldest first. Needs `persist: { dir }` and the same `sessionId` as before the restart. */
+  interrupted(): InterruptedRun[] {
+    const calls = unfinishedToolCalls(this.context.messages).map((c) => c.name);
+    return this.runMarks
+      .filter((m) => !m.end && m !== this.activeMark)
+      .map((m) => ({
+        runId: m.id,
+        startedAt: m.at,
+        prompt: this.previewPrompt((this.context.messages[m.i]?.content ?? "") as string | ContentPart[]),
+        pendingToolCalls: calls,
+      }));
+  }
+
+  /**
+   * Continues the run a crash cut off, without a new prompt: tool calls that already have a saved result are NOT run
+   * again (only calls with no result are), then the model carries on from the saved conversation, and prompts that
+   * were waiting run afterwards. Resolves to that run's response, or `undefined` when nothing was cut off. Returns the
+   * same promise while a resume is in flight. With `resume: "automatic"` (default) the constructor already did this.
+   */
+  resume(): Promise<AgentResponse | undefined> {
+    if (this.resuming) return this.resuming;
+    if (this.currentRun) throw new Error("[Agent Accelerator] resume() needs an idle agent: a run is already active.");
+    const mark = this.runMarks.filter((m) => !m.end && m !== this.activeMark).pop();
+    const last = this.context.messages[this.context.messages.length - 1];
+    const nothingOpen = unfinishedToolCalls(this.context.messages).length === 0;
+    if (!mark || (nothingOpen && (last?.role === "assistant" || endsWithStop(this.context.messages)))) {
+      // The answer was complete (or a tool had ended the run); only the note that it ended was lost.
+      if (mark) this.endRun(mark, endsWithStop(this.context.messages) ? "stopped" : "done");
+      this.pumpQueue();
+      return Promise.resolve(undefined);
+    }
+    telemetryBus.emit({
+      code: "agent.resumed",
+      message: `[Agent Accelerator] resuming run ${mark.id} of session ${this.sessionId}`,
+      data: { sessionId: this.sessionId, runId: mark.id, pendingToolCalls: unfinishedToolCalls(this.context.messages).map((c) => c.name) },
+    });
+    const run = this.startNonStreamingRun("", undefined, mark);
+    const clear = (): void => {
+      if (this.resuming === run) this.resuming = undefined;
+    };
+    this.resuming = run;
+    run.then(clear, clear);
+    return run;
+  }
+
+  // The finished tool calls of the current run as results the loop can reuse; in: toolRecords, out: loopConfig.resume.stored.
+  private storedToolResults(): Map<string, ToolResultRecord> {
+    return new Map(this.toolRecords.map((t) => [t.id, { id: t.id, name: t.name, result: t.result, ...(t.isError ? { isError: true } : {}), ...(t.stopped ? { stopped: true } : {}) } as ToolResultRecord]));
+  }
+
+  // Closes a run's mark with how it ended and saves that at once (not on the next tick), so the disk is up to date when `await run()` returns; in: the run's promise handlers, out: runMarks + journal.
+  private endRun(mark: SessionRunMark | undefined, status: SessionRunEnd): void {
+    if (!mark) return;
+    if (!mark.end) mark.end = status;
+    if (this.activeMark === mark) this.activeMark = undefined;
+    this.doPersist();
+  }
+
+  // Remembers a finished tool call and saves it at once (synchronously): the work is on disk before anything else can happen; in: the executor's per-call callback, out: toolRecords + journal.
+  private recordTool(result: ToolResultRecord): void {
+    this.toolRecords.push({
+      id: result.id,
+      name: result.name,
+      result: isSubagentResult(result.result) ? result.result.xml : result.result,
+      ...(result.isError ? { isError: true } : {}),
+      ...(result.stopped ? { stopped: true } : {}),
+    });
+    this.doPersist();
   }
 
   private getFullInstructions(): string | undefined {
@@ -432,26 +645,6 @@ export class Agent {
         "3. Once your reasoning is complete, output your final response or function calls directly in the standard response output.";
       out = out ? `${out}\n\n${guidance}` : guidance;
     }
-    if (this.dynamicSubagents?.enabled === true && !out.includes("[Dynamic Sub-Agents]")) {
-      const dyn = this.dynamicSubagents;
-      const toolNames = Object.keys(dyn.tools);
-      const timeoutNote =
-        dyn.timeout === -1
-          ? "Timeout policy: set a per-sub-agent timeoutMs (ms) for each task; omit it for no limit."
-          : dyn.timeout === 0
-            ? "Timeout policy: workers run with no time limit."
-            : `Timeout policy: every worker is limited to ${dyn.timeout}ms; per-task timeouts are ignored.`;
-      const policy =
-        "[Dynamic Sub-Agents]\n" +
-        `1. You may spawn at most ${dyn.maxSpawn} sub-agent(s) per spawn_subagents call. Extra tasks beyond ${dyn.maxSpawn} are ignored.\n` +
-        "2. Workers are stateless: each receives one task, returns its result, then shuts down. No conversation history is kept.\n" +
-        "3. You cannot choose worker models or reasoning levels — they are fixed by the developer.\n" +
-        (toolNames.length > 0
-          ? `4. Worker-available tools: ${toolNames.join(", ")}. Grant each worker ONLY the tools its task needs via the per-task tools list; omit it for no tools.\n`
-          : "4. No worker tools are available; omit the per-task tools list.\n") +
-        `5. ${timeoutNote}`;
-      out = out ? `${out}\n\n${policy}` : policy;
-    }
     return out || undefined;
   }
 
@@ -461,6 +654,7 @@ export class Agent {
     this.context.messages = [];
     this.context.thoughtSignatures = [];
     this.context.systemPrompt = this.getFullInstructions();
+    this.runMarks.length = 0;
     // Q-25: reset also drops session-scoped provider chaining/routing.
     try { clearInteractionChains(sid); } catch {}
     try { clearSessionRouting(sid); } catch {}
@@ -546,6 +740,7 @@ export class Agent {
       try { entry.reject(err); } catch {}
       try { entry.deferredStream?.fail(err instanceof Error ? err : new Error(String(err))); } catch {}
     }
+    this.persistNow();
     return n;
   }
 
@@ -716,6 +911,7 @@ export class Agent {
     }
     return new Promise<AgentResponse>((resolve, reject) => {
       this.pendingQueue.push({ prompt, options, isStream: false, resolve, reject });
+      this.persistNow();
       try {
         this.currentRun?.outerStream?.push({
           type: "queued",
@@ -730,6 +926,7 @@ export class Agent {
     if (this.currentRun !== null) return;
     const next = this.pendingQueue.shift();
     if (!next) return;
+    this.persistNow();
     // Q-20: reject queued items whose signal aborted before start.
     try {
       if ((next.options as { signal?: AbortSignal } | undefined)?.signal?.aborted) {
@@ -788,6 +985,8 @@ export class Agent {
     if (leftover.length > 0) {
       try {
         const max = this.midSessionConfig.maxQueued ?? 20;
+        // Late steers were typed BEFORE anything already queued: they go to the front, in the order they arrived.
+        const lateSteers: Agent["pendingQueue"] = [];
         for (const entry of leftover) {
           try {
             if ((entry.options as { signal?: AbortSignal } | undefined)?.signal?.aborted) {
@@ -795,14 +994,14 @@ export class Agent {
               continue;
             }
           } catch { continue; }
-          if (this.pendingQueue.length >= max) {
+          if (this.pendingQueue.length + lateSteers.length >= max) {
             entry.settle?.reject(new Error("[Agent Accelerator] Steer dropped: the follow-up queue is full."));
             continue;
           }
           // The steer was never injected: it now runs as a follow-up, and the
           // caller's promise resolves with that run's response.
           if (entry.settle) entry.settle.deferredToQueue = true;
-          this.pendingQueue.push({
+          lateSteers.push({
             prompt: entry.prompt,
             options: entry.options,
             isStream: false,
@@ -810,8 +1009,10 @@ export class Agent {
             reject: entry.settle?.reject ?? (() => {}),
           });
         }
+        this.pendingQueue.unshift(...lateSteers);
       } catch {}
     }
+    this.persistNow();
     // Defer pump so the completing run's .then handlers settle first.
     queueMicrotask(() => this.pumpQueue());
   }
@@ -962,9 +1163,11 @@ export class Agent {
 
   private startNonStreamingRun(
     prompt: string | ContentPart[],
-    options?: AgentRunOptions
+    options?: AgentRunOptions,
+    resumeMark?: SessionRunMark
   ): Promise<AgentResponse> {
     this.resetBudgetState();
+    let mark: SessionRunMark | undefined;
     const runController = new AbortController();
     const steerInbox: SteerEntry[] = [];
     const mergedSignal = this.mergeUserSignal(options?.signal, runController);
@@ -978,7 +1181,14 @@ export class Agent {
       if (effectiveLevel) {
         validateModelThinking(resolved.provider.id, resolved.modelId, effectiveLevel);
       }
-      this.prepareTurn(prompt, runOptions, targetContext);
+      if (resumeMark) {
+        // Continuing a cut-off run: no new prompt, the saved conversation is the input.
+        mark = resumeMark;
+        this.activeMark = mark;
+        targetContext.systemPrompt = this.getFullInstructions();
+      } else {
+        mark = this.prepareTurn(prompt, runOptions, targetContext);
+      }
       this.persistNow();
 
       const providerOptions = this.buildProviderOptions(runOptions);
@@ -997,6 +1207,10 @@ export class Agent {
         ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
         ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
         onProgress: () => this.persistNow(),
+        onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
+        onToolResult: (r: ToolResultRecord) => this.recordTool(r),
+        openToolLog: (call: { name: string }, sid: string | undefined) => this.openToolLog(call, sid),
+        ...(resumeMark ? { resume: { stored: this.storedToolResults() } } : {}),
         steerInbox,
         onSteerInjected: () => this.persistNow(),
         // Q-22: loop enforces these (plus local timeout races).
@@ -1004,7 +1218,28 @@ export class Agent {
         ...(this.output !== undefined ? { output: this.output } : {}),
       };
 
-      const res = await runAgentLoop(loopConfig);
+      // A run that failed for a transient reason is tried again from where it stopped (the prompt is already in history,
+      // finished tool calls are kept), holding the agent busy meanwhile; anything else fails at once.
+      let res: AgentResponse;
+      const failedAttempts: FailedAttempt[] = [];
+      for (let attempt = 0; ; attempt++) {
+        try {
+          res = await runAgentLoop(attempt === 0 ? loopConfig : { ...loopConfig, resume: { stored: this.storedToolResults() } });
+          break;
+        } catch (err) {
+          if (attempt >= this.runRetries || runOptions?.signal?.aborted || !isRetryableRun(err)) throw err;
+          const partial = (err as { partial?: FailedAttempt }).partial;
+          if (partial?.usage) failedAttempts.push(partial);
+          const delayMs = Math.max(RUN_RETRY_DELAYS_MS[Math.min(attempt, RUN_RETRY_DELAYS_MS.length - 1)]!, readRetryAfterMs(err) ?? 0);
+          telemetryBus.emitWarning(
+            "agent.run_retry",
+            `[Agent Accelerator] Run failed (${err instanceof Error ? err.message : String(err)}); retry ${attempt + 1} of ${this.runRetries} in ${delayMs} ms.`,
+            { sessionId: this.sessionId, attempt: attempt + 1, of: this.runRetries, delayMs }
+          );
+          await sleep(delayMs, runOptions?.signal);
+        }
+      }
+      if (failedAttempts.length > 0) res = withFailedAttempts(res, failedAttempts);
       this.mergeSubagentTraces(res.subagents as any);
       this.persistNow();
       if (this.stateless) {
@@ -1015,6 +1250,10 @@ export class Agent {
     })();
 
     this.currentRun = { steerInbox, abortController: runController, runPromise: task };
+    task.then(
+      (res) => this.endRun(mark, res.finishReason === "stopped" ? "stopped" : "done"),
+      (err) => this.endRun(mark, isAbortError(err) ? "aborted" : "failed")
+    );
     const cleanup = () => {
       try { this.cleanupMerge(runController); } catch {}
       if (this.currentRun?.runPromise === task) this.finishCurrentRun();
@@ -1034,7 +1273,7 @@ export class Agent {
     }
     // Q-19a: named session routing (default session for compat).
     const targetContext = this.getSessionContext(options?.sessionId || this.sessionId);
-    this.prepareTurn(prompt, options, targetContext);
+    const mark = this.prepareTurn(prompt, options, targetContext);
     this.persistNow();
 
     this.resetBudgetState();
@@ -1059,6 +1298,9 @@ export class Agent {
       ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
       ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
       onProgress: () => this.persistNow(),
+      onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
+      onToolResult: (r: ToolResultRecord) => this.recordTool(r),
+      openToolLog: (call: { name: string }, sid: string | undefined) => this.openToolLog(call, sid),
       steerInbox,
       onSteerInjected: () => this.persistNow(),
       // Q-22: loop enforces these (plus local timeout races).
@@ -1070,6 +1312,7 @@ export class Agent {
     this.currentRun = { steerInbox, outerStream: s, abortController: runController };
     s.result().then(
       (res) => {
+        this.endRun(mark, res.finishReason === "stopped" ? "stopped" : "done");
         try {
           this.mergeSubagentTraces(res.subagents as any);
           this.persistNow();
@@ -1081,7 +1324,8 @@ export class Agent {
         }
         if (this.currentRun?.outerStream === s) this.finishCurrentRun();
       },
-      () => {
+      (err) => {
+        this.endRun(mark, isAbortError(err) ? "aborted" : "failed");
         try { this.cleanupMerge(runController); } catch {}
         if (this.currentRun?.outerStream === s) this.finishCurrentRun();
       }
@@ -1168,6 +1412,25 @@ export class Agent {
     });
   }
 
+  // Opens the log file of one tool call when this Agent persists its default session to a folder, else nothing; in: the executor, once per call, out: a writer for `tool-logs/<n>-<tool>.ndjson`.
+  private openToolLog(call: { name: string }, sessionId: string | undefined): ToolLogWriter | undefined {
+    const root = this.persistConfig?.dir;
+    if (!root || this.stateless || sessionId !== this.sessionId) return undefined;
+    const dir = sessionDirFor(root, this.sessionId);
+    if (this.toolLogsDir !== dir) {
+      this.toolLogs = new ToolLogs(dir);
+      this.toolLogsDir = dir;
+    }
+    return this.toolLogs!.open(call);
+  }
+
+  /** The step journal of this session's folder (recreated when `sessionId` changes). */
+  private journalFor(root: string): SessionJournal {
+    const dir = sessionDirFor(root, this.sessionId);
+    if (this.journal?.dir !== dir) this.journal = new SessionJournal(dir);
+    return this.journal;
+  }
+
   /** Synchronous persistence write behind the coalesced `persistNow()` gate. */
   private doPersist(): void {
     const cfg = this.persistConfig;
@@ -1176,7 +1439,7 @@ export class Agent {
       if (this.stateless && !(cfg as unknown as { allowStateless?: unknown }).allowStateless) return;
     } catch {}
     try {
-      if (cfg.dir) saveSessionDir(cfg.dir, this as any, null);
+      if (cfg.dir) this.journalFor(cfg.dir).sync(this as any);
       else if (cfg.file) saveSessionFile(cfg.file, this as any, null);
     } catch (err) {
       // Q-28: surface via hook instead of swallowing silently.
@@ -1285,6 +1548,8 @@ export class Agent {
       this.context.messages = Array.isArray(data.messages) ? [...data.messages] : [];
     }
     this.context.thoughtSignatures = [];
+    this.runMarks.splice(0, this.runMarks.length, ...(data.runs ?? []).filter((r) => r.i < this.context.messages.length));
+    this.restoreUsage(data.usage);
     if (data.systemPrompt) {
       this.context.systemPrompt = data.systemPrompt;
     } else {
@@ -1324,7 +1589,7 @@ export class Agent {
     } catch {}
   }
 
-  private prepareTurn(prompt: string | ContentPart[], options?: AgentRunOptions, target?: AgentContext): void {
+  private prepareTurn(prompt: string | ContentPart[], options?: AgentRunOptions, target?: AgentContext): SessionRunMark | undefined {
     // Q-20: prompt validation throws synchronously in both run() and
     // stream() (same timing; documented here).
     if (Array.isArray(prompt) && prompt.length === 0) {
@@ -1352,7 +1617,28 @@ export class Agent {
     } else if (ctx.systemPrompt !== fullInstructions) {
       ctx.systemPrompt = fullInstructions;
     }
+    const mark = ctx === this.context ? this.markRunStart(ctx.messages.length) : undefined;
     ctx.addUserMessage(prompt);
+    return mark;
+  }
+
+  // Records where a run of the default session begins; in: prepareTurn, out: runMarks, saved by the session journal.
+  private markRunStart(index: number): SessionRunMark {
+    for (const old of this.runMarks) if (!old.end) old.end = "abandoned"; // a newer run replaces a cut-off one
+    this.toolRecords.length = 0;
+    const mark: SessionRunMark = { id: newRunId(), i: index, at: Date.now() };
+    this.runMarks.push(mark);
+    this.activeMark = mark;
+    return mark;
+  }
+
+  /** Prompts still waiting (steers not yet injected, queued follow-ups), as the session journal saves them. @internal */
+  pendingPrompts(): SessionPending {
+    const pack = (e: { prompt: string | ContentPart[]; options?: AgentRunOptions }) => ({
+      prompt: e.prompt,
+      ...(e.options?.additionalContext ? { additionalContext: e.options.additionalContext } : {}),
+    });
+    return { steer: (this.currentRun?.steerInbox ?? []).map(pack), queue: this.pendingQueue.map(pack) };
   }
 
   /**
@@ -1432,6 +1718,7 @@ export class Agent {
         }
         return new Promise<AgentResponse>((resolve, reject) => {
           this.pendingQueue.push({ prompt, options, isStream: false, resolve, reject });
+          this.persistNow();
           try {
             this.currentRun?.outerStream?.push({
               type: "queued",
@@ -1615,6 +1902,7 @@ export class Agent {
         } catch {}
       });
       this.pendingQueue.push(queuedEntry as any);
+      this.persistNow();
       // Attach deferred completion to queued promise without exposing it.
       // Real events are piped in pumpQueue() when the turn starts.
       void done.then(
@@ -1852,6 +2140,35 @@ export class Agent {
   }
 }
 
+/** What a failed run attempt got done before it failed (the `partial` the loop attaches to its error). */
+type FailedAttempt = Partial<AgentResponse> & { usage: TokenUsage };
+
+// Adds what failed attempts already did (tool calls, results, turns, token usage) to the response of the attempt that finally worked, so a retry never hides side effects or cost; in: the final response + each failed attempt's `err.partial`, out: the run's AgentResponse.
+function withFailedAttempts(res: AgentResponse, failed: FailedAttempt[]): AgentResponse {
+  const usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+  for (const f of failed) accumulateUsage(usage, f.usage);
+  accumulateUsage(usage, res.usage);
+  return new AgentResponse({
+    text: res.text,
+    ...(res.parsed !== undefined ? { parsed: res.parsed } : {}),
+    thinking: res.thinking,
+    thoughtSignature: res.thoughtSignature,
+    toolCalls: [...failed.flatMap((f) => f.toolCalls ?? []), ...res.toolCalls],
+    toolResults: [...failed.flatMap((f) => f.toolResults ?? []), ...res.toolResults],
+    subagents: res.subagents,
+    usage,
+    responseId: res.responseId,
+    model: res.model,
+    provider: res.provider,
+    finishReason: res.finishReason,
+    rawFinishReason: res.rawFinishReason,
+    durationMs: res.durationMs,
+    raw: res.raw,
+    turns: res.turns + failed.reduce((n, f) => n + (typeof f.turns === "number" ? f.turns : 0), 0),
+    providerSteps: res.providerSteps,
+  });
+}
+
 /** Normalizes the public `thinkingLevel` flag into provider-neutral thinking settings. */
 export function normalizeThinking(config: AgentConfig, fallbackLevel?: string): ThinkingConfig | undefined {
   // DX4: only thinkingLevel, values: none, dynamic, minimal, low, medium, high, xhigh, max