agent-accelerator 0.5.7 → 0.5.9

package/README.md

@@ -126,7 +126,7 @@ An `Agent` holds:
 | `cache`           | `CacheOption`                                        | `"implicit" \| "5m" \| "30m" \| "1h" \| "12h"`. Prompt-cache lifetime; unsupported values warn and fall back (see [Cache](#cache)).                                                                             |
 | `serviceTier`     | `"flex" \| "priority"`                               | Cost / priority routing where supported. Omit for standard routing.                                                                                        |
 | `maxTurns`        | `number`                                             | Maximum model → tool → model loops per `run`. Infinite by default (`0` or omitted = no limit). Hitting a finite limit with pending tool calls warns and sets `finishReason: "max_turns"`. |
-| `limits`          | `AgentRunLimits`                                     | `{ maxTurns?, deadlineMs?, maxToolCallsPerRun?, maxTotalTokens?, requestTimeoutMs?, firstByteTimeoutMs?, streamIdleTimeoutMs? }`. The first four are unlimited by default. The three network timeouts default to 300 s / 120 s / 300 s so a silent connection fails instead of hanging; set one to `0` or `Infinity` to turn it off. A timeout raises a retryable `TimeoutError`. See [Safety and operations](docs/guides/safety-and-ops.md#network-timeouts). |
+| `limits`          | `AgentRunLimits`                                     | `{ maxTurns?, deadlineMs?, maxToolCallsPerRun?, maxTotalTokens?, requestTimeoutMs?, firstByteTimeoutMs?, streamIdleTimeoutMs? }`. The first four are unlimited by default; hitting `maxTurns` ends the run with `finishReason: "max_turns"`, the other three throw a `BudgetExceededError`. The three network timeouts default to 300 s / 120 s / 300 s so a silent connection fails instead of hanging; set one to `0` or `Infinity` to turn it off. A timeout raises a retryable `TimeoutError`. See [Safety and operations](docs/guides/safety-and-ops.md#network-timeouts). |
 | `budget`          | `Budget`                                             | `{ maxCostUsd?, maxTotalTokens?, maxDurationMs?, maxTotalSubagents? }`, per run, workers included. Unlimited by default; exceeding it throws `BudgetExceededError` with partial usage. |
 | `sessionId`       | `string`                                             | Stable identifier used for cache affinity. Auto-generated when omitted.                                                                                    |
 | `headers`         | `Record<string,string>`                              | Additional headers merged into every request.                                                                                                              |
@@ -136,7 +136,7 @@ An `Agent` holds:
 | `runRetries`      | `number`                                             | A run that FAILED for a transient reason (provider down or overloaded, timeouts, a cut stream, after `retry` gave up) is tried again from where it stopped, waiting 5 s, 15 s, 45 s, then 60 s. Default `3`, `0` = off. Finished tool calls are not repeated; the response reports the failed attempts' tool calls and usage. Never for aborts, 400/401/403/404, bad config, budgets or limits. `run()` and queued runs only, not `stream()`. |
 | `resume`          | `"automatic" \| "explicit"`                         | Crash recovery (needs `persist: { dir }` + the same `sessionId`): `automatic` (default) continues a cut-off run when the Agent is constructed, `explicit` waits for `agent.resume()`. Finished tool calls are never run again. `agent.interrupted()` lists cut-off runs. |
 | `persist`         | `{ dir?: string; file?: string }`                    | Durable sessions, saved after every step (user/assistant/tool/sub-agent). `{ dir }` keeps `sessions/<sessionId>/session.json` (snapshot) plus an append-only `journal.ndjson` (one line per step, so a long chat costs the same per step as a short one), `{ file }` a single `.session.json`, `{}` uses `<home>/sessions`. Writes are durable (fsync, `.bak` of the last good file, atomic rename) and never fail a turn. |
-| `home`            | `string`                                             | Folder for everything the SDK writes to disk (`sessions/`, `scheduled_actions/`, `telemetry/`). Defaults to `setHome(dir)`, then the `AGENT_ACCEL_HOME` env var, then `.agent-accel/` in the working directory. An explicit `persist.dir` / `persist.file` still wins.        |
+| `home`            | `string`                                             | Folder for everything the SDK writes to disk (`sessions/`, `scheduled/`, `telemetry/`). Defaults to `setHome(dir)`, then the `AGENT_ACCEL_HOME` env var, then `.agent-accel/` in the working directory. An explicit `persist.dir` / `persist.file` still wins.        |
 
 When `dynamicSubagents.enabled` is set without a resolvable worker model, construction throws `SubAgentModelError`.
 
@@ -390,10 +390,10 @@ Every function except `createScheduledAction` finds the home folder through `set
 
 **How it behaves**
 
-* **One local clock.** A single timer per home folder (guarded by a one-process lock, `<home>/.lock`) ticks once a second against the machine's own time and only asks what is overdue, so drift or sleep cannot skip a run. There is no timezone or daylight-saving logic. The timer is `unref`'d and runs only while something is pending, so actions run only while your process is alive.
-* **The creating `Agent` runs it.** The task stores the Agent's `name`; each run goes to the live Agent with that name (latest wins), using its worker model and tool pool. The scheduler holds only a weak reference, so keep your `Agent` referenced; if none is alive, the run counts as missed.
+* **One local clock.** A single timer per process and home folder ticks once a second against the machine's own time and only asks what is overdue, so drift or sleep cannot skip a run. There is no timezone or daylight-saving logic. The timer is `unref`'d and runs only while something is pending, so actions run only while your process is alive.
+* **The creating `Agent` runs it.** The task stores the Agent's `name`; each run goes to the live Agent with that name (latest wins), using its worker model and tool pool. The scheduler holds only a weak reference, so keep your `Agent` referenced; if none is alive, the run counts as missed once its delivery time has passed. Several processes may share one home: only the process that registered the Agent starts, delivers and recovers its actions, each action has its own folder and short lock, and a run whose owner died is recovered by another process that owns the Agent.
 * **Each run is fresh.** A new stateless dynamic sub-agent built from the saved fields, on your fixed worker model and tool pool, never touching the Main Agent's session. It inherits the parent's limits, retry policy, `fileAccess` and `captureRaw`.
-* **Files are the truth.** Everything lives in `<home>/scheduled_actions/` (the format is a stable contract with a changelog: [docs/scheduled-action-files.md](docs/scheduled-action-files.md)): `tasks.json` (every action), `deliveries.json` (saved results waiting for their delivery time) and one folder per action with one `.md` file per run (a small header, then the result). The file is re-read and validated before each run, so editing `instructions` or `task` there takes effect on the next run. API keys, the model and tool code are never stored. Don't put secrets in `instructions`.
+* **Files are the truth.** Everything lives in `<home>/scheduled/` (the format is a stable contract with a changelog: [docs/scheduled-action-files.md](docs/scheduled-action-files.md)): one folder per action holding its `task.json`, a `delivery.json` while a saved result waits for its delivery time, and one `.md` file per run (a small header, then the result). The file is re-read and validated before each run, so editing `instructions` or `task` there takes effect on the next run. API keys, the model and tool code are never stored. Don't put secrets in `instructions`.
 * **What a run costs.** Each run file's header records the run's exact spending, the same numbers `usageReport()` keeps for workers: `turns`, `tokens` (input + output), `inputTokens`, `freshInputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`, `thinkingTokens`, `cacheHitRate` (0 to 1), `costUsd`, `costSource` (`provider`, `catalog`, `mixed` or `unknown`) and `unpricedTurns` (only when above 0, then `costUsd` is a lower bound). Unknown pricing is `costUsd: unknown`, never 0. The numbers cover every attempt of the run (`retries` included) and are recorded for failed runs too. The report itself does not list scheduled runs.
 * **Time limit of a run.** An action may carry `timeoutMs` (top level of the action, not inside `scheduled_action`): a run that takes longer is stopped and recorded as failed. By default there is no limit. `dynamicSubagents.workerTimeoutMs` is an optional ceiling: an action cannot ask for more, and it is the limit for actions that set none (`0` and `Infinity` mean no ceiling). The former `dynamicSubagents.timeout`, `modelMaySetTimeout` and the `-1` mode were removed; passing them throws a `ConfigError` that says what to use.
 * **Ready, then delivered.** A finished run is saved immediately (`scheduled_action.ready`); at `timeToDeliver` the SDK emits `scheduled_action.delivered` on `telemetryBus` with `{ id, name, status, file, readyAt, deliverAt, late }`. There is no notification system: what happens next is your code. Other events: `.created`, `.updated`, `.started`, `.failed`, `.missed`, `.skipped`, `.deleted`, plus the warnings `.invalid` and `.store_corrupt`.
@@ -1089,16 +1089,35 @@ Credential headers are always redacted (`Authorization`, `x-goog-api-key`, anyth
 ---
 ## Errors
 
-Provider failures throw `AgentAccelProviderError` — one actionable line,
+Provider failures throw a `ProviderError` — one actionable line,
 never a wire dump:
 
 ```text
 [openrouter/nvidia/nemotron-3.5-lightning:free] request failed (404): No endpoints found that support input video
 ```
 
-Raw details (`statusCode`, `url`, truncated body) stay attached as
+Branch on the class and `err.retryable` (true for HTTP 408/425/429/5xx,
+network errors and a cut stream), never on the message:
+
+```ts
+import { ProviderError, TimeoutError } from "agent-accelerator";
+
+try {
+  await agent.run("...");
+} catch (err) {
+  if (err instanceof ProviderError && err.retryable) retryLater(); // e.g. a 429 or 503
+  else if (err instanceof TimeoutError) retryLater(); // a request / first-byte / idle timeout
+  else throw err;
+}
+```
+
+`err.code` is the SDK kind (`"provider"`, `"incomplete_stream"` for a cut
+stream; `"timeout"`, `"config"`, ... on the other classes); the provider's own
+error code (e.g. `"not_found"`, `"rate_limit_exceeded"`) is `err.providerCode`.
+Raw details (`statusCode`, `url`, truncated body, `providerCode`) stay attached as
 non-enumerable properties: available programmatically, invisible in runtime
-dumps. URL query strings are stripped (keys sometimes live there); headers
+dumps. Input a model cannot take (a modality the catalog says it lacks, video on
+the OpenAI Responses wire) fails before the network with a `ValidationError`. URL query strings are stripped (keys sometimes live there); headers
 and cookies are never attached. Helpers:
 
 * `toConciseProviderError(err, providerId, modelId)` — collapse any provider error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "High-performance SDK for AI agents with a unified API across AI providers. Optimized for high cache hit rates, observability, and seamless agent orchestration. Built to power production-grade agentic systems and harnesses for teams at any scale.",
   "license": "MIT",
   "author": "Sashvat Bharat",

package/src/agent/agent.ts

@@ -22,7 +22,7 @@ import {
 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 { persistTelemetry, registerSessionFolder, unregisterSessionFolder } from "../telemetry-file.ts";
 import { lockFolder } from "../utils/durable.ts";
 import { createScheduledActionsTool, getDatetimeTool } from "../scheduler/tool.ts";
 import { applyEditable, assertModelAllowed, modelKey, toEditableConfig } from "./config-blocks.ts";
@@ -63,10 +63,10 @@ export function resolveEffectiveThinking(
   return { enabled: true, level: overrideLevel as ThinkingConfig["level"] };
 }
 
-import { ConfigError, SessionLoadError, isAbortError } from "../types/errors.ts";
+import { ConfigError, SessionLoadError, ValidationError, isAbortError } from "../types/errors.ts";
 
 /**
- * Disposers for the manual user-signal forward listeners (Q-21 fallback when
+ * Disposers for the manual user-signal forward listeners (fallback when
  * `AbortSignal.any` is unavailable). Keyed by run controller so no expando
  * properties are attached to AbortController instances.
  */
@@ -75,12 +75,12 @@ 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). */
+/** Max named sessions kept per Agent (LRU). */
 const SESSION_LRU_MAX = 100;
-/** Idle TTL for named sessions (Q-19a). */
+/** Idle TTL for named sessions. */
 const SESSION_TTL_MS = 60 * 60 * 1000;
 
-/** Normalized per-run limits (Q-22). Sub-agents inherit these unless overridden. */
+/** Normalized per-run limits. Sub-agents inherit these unless overridden. */
 export interface AgentRunLimits {
   maxTurns?: number;
   deadlineMs?: number;
@@ -91,7 +91,7 @@ export interface AgentRunLimits {
   streamIdleTimeoutMs: number;
 }
 
-/** Resolves `(config as any).limits` with Q-22 defaults (timeouts tolerate reasoning). */
+/** Resolves `(config as any).limits` with defaults (timeouts tolerate reasoning). */
 function resolveAgentLimits(config: { limits?: Record<string, unknown> }): AgentRunLimits {
   const raw = (config as { limits?: Record<string, unknown> }).limits ?? {};
   const num = (v: unknown): number | undefined =>
@@ -181,7 +181,7 @@ export class Agent {
     /** 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/`). */
+  /** Home folder for everything written to disk (`sessions/`, `scheduled/`, `telemetry/`). */
   readonly home: string;
   /** Registered model-callable tools. */
   readonly tools: Record<string, ToolDefinition> = {};
@@ -240,10 +240,10 @@ export class Agent {
   readonly persistConfig?: { dir?: string; file?: string };
   /** Mid-session queue policy for new queries arriving while a run is active. */
   readonly midSessionConfig: Required<Pick<MidSessionConfig, "mode">> & MidSessionConfig & { maxSteers?: number };
-  /** Max buffered steer entries per run (Q-20, default 20). */
+  /** Max buffered steer entries per run (default 20). */
   readonly maxSteers: number;
   /**
-   * Normalized run limits (Q-22). Read from `(config as any).limits`;
+   * Normalized run limits. Read from `(config as any).limits`;
    * sub-agents inherit these unless overridden. `maxTurns`/`deadlineMs`/
    * `maxToolCallsPerRun` default to unlimited; timeouts default to
    * request 300s / first-byte 120s / idle 300s (tolerate reasoning).
@@ -265,9 +265,9 @@ export class Agent {
     /** Put here by `interrupt(message)`: runs before every other waiting prompt. */
     urgent?: boolean;
   }> = [];
-  /** Named session contexts for `sessionId` runs (Q-19a, LRU 100 + TTL). */
+  /** Named session contexts for `sessionId` runs (LRU 100 + TTL). */
   private sessions = new Map<string, { context: AgentContext; lastAccess: number }>();
-  /** Coalesced persistence single-flight flag (Q-28). */
+  /** Coalesced persistence single-flight flag. */
   private persistScheduled = false;
   /** Step journal of the persisted session folder (dir mode only). */
   private journal?: SessionJournal;
@@ -384,11 +384,6 @@ 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;
@@ -402,9 +397,9 @@ export class Agent {
         ? { maxSteers: Math.floor(rawMaxSteers as number) }
         : { maxSteers: 20 }),
     };
-    // Q-20: bound on buffered steer entries (default 20).
+    // Bound on buffered steer entries (default 20).
     this.maxSteers = this.midSessionConfig.maxSteers ?? 20;
-    // Q-22: run limits (sub-agents inherit unless overridden).
+    // Run limits (sub-agents inherit unless overridden).
     this.runLimits = resolveAgentLimits(config as unknown as { limits?: Record<string, unknown> });
 
     // DX4: single thinkingLevel flag — also inherit from ModelProviderInstance when omitted
@@ -463,6 +458,8 @@ export class Agent {
       ? { ...(config.fileAccess.roots ? { roots: [...config.fileAccess.roots] } : {}) }
       : undefined;
     this.stateless = config.stateless ?? false;
+    // One process per session folder: fail fast here, before anything is written (another process may use other sessions of the same home).
+    this.lockSessionFolder();
 
     // Tools registration (unified normalization shared with dynamic pool).
     if (config.tools) {
@@ -498,6 +495,7 @@ export class Agent {
     assertNoToolCollisions(this.tools);
 
     this.context = new AgentContext(this.getFullInstructions());
+    this.registerTelemetryFolder();
     if (dyn?.allowScheduledActions) registerAgent(this);
     if (this.recoverSession() && this.resumeMode === "automatic") {
       // Synchronously, so a run() issued right after construction queues BEHIND the resumed run.
@@ -510,6 +508,34 @@ export class Agent {
     return (this.workerRegistry ??= new WorkerRegistry(this));
   }
 
+  // Takes the one-process lock of the folder this Agent persists to: its own session folder, or the folder of a single `persist.file`; throws ConfigError when another live process holds it; in: the constructor and importSession (a new session id is a new folder), out: a `.lock` file there.
+  private lockSessionFolder(): void {
+    const cfg = this.persistConfig;
+    if (!cfg || this.stateless) return;
+    if (cfg.dir) {
+      let dir: string;
+      try {
+        dir = sessionDirFor(cfg.dir, this.sessionId);
+      } catch {
+        return; // not a usable session id for a folder name, so nothing is saved under it either
+      }
+      lockFolder(dir);
+    } else if (cfg.file) {
+      lockFolder(path.dirname(path.resolve(cfg.file)));
+    }
+  }
+
+  // Tells the telemetry sink where this Agent's session folder is (only for a session persisted to a folder), so its events are written next to its journal; in: the constructor and importSession, out: the telemetry routing map.
+  private registerTelemetryFolder(): void {
+    const root = this.persistConfig?.dir;
+    if (!root || this.stateless) return;
+    try {
+      registerSessionFolder(this.sessionId, sessionDirFor(root, this.sessionId));
+    } catch {
+      // why: not a usable session id for a folder name, so nothing is saved under it either.
+    }
+  }
+
   // 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;
@@ -671,20 +697,22 @@ export class Agent {
     return out || undefined;
   }
 
-  /** Clears conversation messages and provider thought signatures while keeping configuration. */
+  /** Starts a fresh conversation: clears messages, signatures, run marks and the run's saved tool results, keeps config and spending totals. */
   reset(): void {
     const sid = this.sessionId;
     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.
+    this.toolRecords.length = 0; // a cleared conversation has no run to resume, so its finished tool results go too
+    this.activeMark = undefined;
+    // Reset also drops session-scoped provider chaining/routing.
     try { clearInteractionChains(sid); } catch {}
     try { clearSessionRouting(sid); } catch {}
   }
 
   /**
-   * Returns a named session handle (Q-19a). `session()` creates an isolated
+   * Returns a named session handle. `session()` creates an isolated
    * `AgentContext` bound to `id` (separate histories per id); `agent.run`
    * with `{ sessionId }` selects/creates the same entry. Sessions are
    * ephemeral in-memory (LRU 100 + 1h TTL). `agent.run`/`stream` without a
@@ -696,14 +724,15 @@ export class Agent {
     return { id: sid, context: ctx, runController: null };
   }
 
-  /** Drops one named session (Q-19a). No-op for unknown ids. */
+  /** Drops one named session. No-op for unknown ids. */
   disposeSession(id: string): void {
+    unregisterSessionFolder(id);
     try { this.sessions.delete(id); } catch {}
     try { clearInteractionChains(id); } catch {}
     try { clearSessionRouting(id); } catch {}
   }
 
-  /** Drops all named sessions except the default context (Q-19a). */
+  /** Drops all named sessions except the default context. */
   clearSessions(): void {
     try {
       for (const id of [...this.sessions.keys()]) {
@@ -753,7 +782,7 @@ export class Agent {
     return fresh;
   }
 
-  /** Rejects + drops all queued follow-ups (Q-20). Returns the cleared count. */
+  /** Rejects + drops all queued follow-ups. Returns the cleared count. */
   clearQueue(): number {
     const n = this.pendingQueue.length;
     if (n === 0) return 0;
@@ -767,7 +796,7 @@ export class Agent {
     return n;
   }
 
-  /** Throws when the steer inbox is at its Q-20 bound. */
+  /** Throws when the steer inbox is at its bound. */
   private assertSteerRoom(inbox: SteerEntry[]): void {
     const max = this.maxSteers ?? 20;
     if (inbox.length >= max) {
@@ -810,7 +839,7 @@ export class Agent {
   // Throws synchronously on an empty content-part array so run() and stream() fail at the same moment; in: any prompt entry point, out: nothing.
   private assertPromptValid(prompt: string | ContentPart[]): void {
     if (Array.isArray(prompt) && prompt.length === 0) {
-      throw new Error(
+      throw new ValidationError(
         "[Agent Accelerator] Prompt cannot be empty: pass a non-empty string or at least one content part."
       );
     }
@@ -964,7 +993,7 @@ export class Agent {
     const next = this.pendingQueue.shift();
     if (!next) return;
     this.persistNow();
-    // Q-20: reject queued items whose signal aborted before start.
+    // Reject queued items whose signal aborted before start.
     try {
       if ((next.options as { signal?: AbortSignal } | undefined)?.signal?.aborted) {
         const reason = ((next.options as { signal?: AbortSignal }).signal as unknown as { reason?: unknown })?.reason;
@@ -1016,7 +1045,7 @@ export class Agent {
 
   // Ends the active run slot: leftover steers become follow-ups at the FRONT of the queue (behind urgent ones), then the queue is pumped; in: a settled run, out: pendingQueue + persistNow.
   private finishCurrentRun(): void {
-    // Q-20: leftover steer entries become queued follow-ups instead of dropping.
+    // Leftover steer entries become queued follow-ups instead of dropping.
     let leftover: SteerEntry[] = [];
     try { leftover = this.currentRun?.steerInbox?.splice(0) ?? []; } catch { leftover = []; }
     this.currentRun = null;
@@ -1080,7 +1109,7 @@ export class Agent {
       }
       return runController.signal;
     }
-    // Q-21: prefer AbortSignal.any (no expando, no listener leak).
+    // Prefer AbortSignal.any (no expando, no listener leak).
     try {
       const anyFn = (AbortSignal as unknown as { any?: (signals: AbortSignal[]) => AbortSignal }).any;
       if (typeof anyFn === "function") {
@@ -1233,7 +1262,7 @@ export class Agent {
     const steerInbox: SteerEntry[] = [];
     const mergedSignal = this.mergeUserSignal(options?.signal, runController);
     const runOptions = this.withResolvedThinking({ ...options, signal: mergedSignal });
-    // Q-19a: route to the named session context (default = this.context).
+    // Route to the named session context (default = this.context).
     const targetContext = this.getSessionContext(runOptions?.sessionId || this.sessionId);
     const task = (async (): Promise<AgentResponse> => {
       await ensureModelCatalogFresh();
@@ -1274,7 +1303,7 @@ export class Agent {
         ...(resumeMark ? { resume: { stored: this.storedToolResults() } } : {}),
         steerInbox,
         onSteerInjected: () => this.persistNow(),
-        // Q-22: loop enforces these (plus local timeout races).
+        // Loop enforces these (plus local timeout races).
         limits: { ...this.runLimits },
         ...(this.output !== undefined ? { output: this.output } : {}),
       };
@@ -1333,7 +1362,7 @@ export class Agent {
     if (effectiveLevel) {
       validateModelThinking(resolved.provider.id, resolved.modelId, effectiveLevel);
     }
-    // Q-19a: named session routing (default session for compat).
+    // Named session routing (default session for compat).
     const targetContext = this.getSessionContext(options?.sessionId || this.sessionId);
     const mark = this.prepareTurn(prompt, options, targetContext);
     this.persistNow();
@@ -1365,7 +1394,7 @@ export class Agent {
       openToolLog: (call: { name: string }, sid: string | undefined) => this.openToolLog(call, sid),
       steerInbox,
       onSteerInjected: () => this.persistNow(),
-      // Q-22: loop enforces these (plus local timeout races).
+      // Loop enforces these (plus local timeout races).
       limits: { ...this.runLimits },
       ...(this.output !== undefined ? { output: this.output } : {}),
     };
@@ -1455,14 +1484,14 @@ export class Agent {
    * Called automatically after every step during runs; safe to call
    * manually. Never throws (failures route to `onPersistError`).
    *
-   * Q-28: stateless agents skip persistence unless
+   * Stateless agents skip persistence unless
    * `(persist as any).allowStateless` is set. Calls in the same tick are
    * coalesced via a `queueMicrotask` single flight.
    */
   persistNow(): void {
     const cfg = this.persistConfig;
     if (!cfg || (!cfg.dir && !cfg.file)) return;
-    // Q-28: no stateless persist by default.
+    // No stateless persist by default.
     try {
       if (this.stateless && !(cfg as unknown as { allowStateless?: unknown }).allowStateless) return;
     } catch {}
@@ -1504,7 +1533,7 @@ export class Agent {
       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.
+      // Surface via hook instead of swallowing silently.
       try { (cfg as unknown as { onPersistError?: (e: unknown) => void }).onPersistError?.(err); } catch {}
     }
   }
@@ -1574,6 +1603,16 @@ export class Agent {
     this.warnOnLocalMediaPaths(data.messages ?? []);
     const prevSid = this.sessionId;
     if (data.sessionId) (this as any).sessionId = data.sessionId;
+    if (this.sessionId !== prevSid) {
+      try {
+        this.lockSessionFolder();
+      } catch (err) {
+        (this as any).sessionId = prevSid; // the session belongs to another process: keep ours untouched
+        throw err;
+      }
+      unregisterSessionFolder(prevSid);
+      this.registerTelemetryFolder();
+    }
     if ((data as any).parentSessionId) (this as any).parentSessionId = (data as any).parentSessionId;
     if ((data as any).subagents && typeof (data as any).subagents === "object") {
       try {
@@ -1617,7 +1656,7 @@ export class Agent {
     } else {
       this.context.systemPrompt = this.getFullInstructions();
     }
-    // Q-25: importing a snapshot invalidates prior provider chaining/routing
+    // Importing a snapshot invalidates prior provider chaining/routing
     // for both the previous and the restored session.
     try { clearInteractionChains(prevSid); } catch {}
     try { clearSessionRouting(prevSid); } catch {}
@@ -1653,16 +1692,16 @@ export class Agent {
 
   // Adds the user prompt to the target context (fresh context when stateless, stable system prompt, additionalContext as a user prefix) and marks the run start for the default session; in: a run start, out: the new SessionRunMark.
   private prepareTurn(prompt: string | ContentPart[], options?: AgentRunOptions, target?: AgentContext): SessionRunMark | undefined {
-    // Q-20: prompt validation throws synchronously in both run() and
+    // Prompt validation throws synchronously in both run() and
     // stream() (same timing; documented here).
     if (Array.isArray(prompt) && prompt.length === 0) {
-      throw new Error(
+      throw new ValidationError(
         "[Agent Accelerator] Prompt cannot be empty: pass a non-empty string or at least one content part."
       );
     }
     const ctx = target ?? this.getSessionContext(options?.sessionId || this.sessionId);
     if (this.stateless) {
-      // Q-19a: stateless runs use a fresh ephemeral context (never shared).
+      // Stateless runs use a fresh ephemeral context (never shared).
       ctx.messages = [];
       ctx.thoughtSignatures = [];
     }
@@ -1728,7 +1767,7 @@ export class Agent {
     prompt: string | ContentPart[],
     options?: AgentRunOptions
   ): Promise<AgentResponse> | AssistantMessageEventStream {
-    // Q-20: prompt validation throws synchronously in both run() and
+    // Prompt validation throws synchronously in both run() and
     // stream() (same timing; async work starts only after validation).
     this.assertPromptValid(prompt);
     const isStream = options?.stream === true;
@@ -1866,7 +1905,7 @@ export class Agent {
     prompt: string | ContentPart[],
     options?: AgentRunOptions
   ): AssistantMessageEventStream {
-    // Q-20: same sync validation timing as run().
+    // Same sync validation timing as run().
     this.assertPromptValid(prompt);
     // Mid-session: busy agent serializes via steer (same turn) or queue (next turn).
     if (this.currentRun) {
@@ -2217,7 +2256,7 @@ 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.
+// Adds what failed attempts already did (tool calls, results, workers, 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);
@@ -2229,7 +2268,7 @@ function withFailedAttempts(res: AgentResponse, failed: FailedAttempt[]): AgentR
     thoughtSignature: res.thoughtSignature,
     toolCalls: [...failed.flatMap((f) => f.toolCalls ?? []), ...res.toolCalls],
     toolResults: [...failed.flatMap((f) => f.toolResults ?? []), ...res.toolResults],
-    subagents: res.subagents,
+    subagents: [...failed.flatMap((f) => f.subagents ?? []), ...res.subagents],
     usage,
     responseId: res.responseId,
     model: res.model,

package/src/agent/architecture.md

@@ -23,3 +23,4 @@ The agent and everything that runs under it.
 - Exactly-once worker calls rest on the call key (parent run mark id + tool call id) and `meta.last`.
 - Only results branded by `makeSubagentResult` have their usage metadata trusted.
 - Each Agent records only its own model turns; never sum `AgentResponse.usage` for totals.
+- `reset()` clears the conversation (messages, run marks, the run's saved tool results) but never the spending totals.

package/src/agent/context.ts

@@ -170,8 +170,8 @@ export class AgentContext {
   }
 
   /**
-   * Captures a detached snapshot of conversation state for run-level rollback
-   * (Q-19). The snapshot is a structural deep copy (NOT JSON): `Uint8Array` /
+   * Captures a detached snapshot of conversation state for run-level rollback.
+   * The snapshot is a structural deep copy (NOT JSON): `Uint8Array` /
    * `ArrayBuffer` media must survive a rollback byte-for-byte, and large
    * base64 strings are shared by reference rather than re-serialized.
    */
@@ -185,7 +185,7 @@ export class AgentContext {
   /**
    * Restores a checkpoint captured by `checkpoint()`. Malformed checkpoints
    * are ignored (current state kept). When `sessionId` is provided, also
-   * clears session-scoped provider state (Q-25) so a rollback never resumes
+   * clears session-scoped provider state so a rollback never resumes
    * a stale interaction chain.
    */
   rollback(cp: { messages: Message[]; signatures: string[] }, sessionId?: string): void {

package/src/agent/delegation.ts

@@ -74,7 +74,7 @@ export function isSessionDescendant(child: string, parent: string): boolean {
   if (!child || !parent) return false;
   if (child === parent) return true;
   if (child.startsWith(parent + "-")) return true;
-  // Q-34: hash includes() is collision-prone; require delimited match to reduce spoofing. Explicit {rootSessionId,parentSessionId} lineage is Q-61 future.
+  // Hash includes() is collision-prone; require delimited match to reduce spoofing. Explicit {rootSessionId,parentSessionId} lineage is future work.
   const h = hashSessionPart(parent);
   return child.includes(`-${h}-`) || child.endsWith(`-${h}`);
 }
@@ -101,13 +101,13 @@ export interface SubAgentTrace {
 const subagentTraces = new Map<string, SubAgentTrace>();
 const subagentListeners = new Map<string, Set<(trace: SubAgentTrace) => void>>();
 
-/** Max trace keys held (LRU, evicts oldest whole trace on insert) (Q-30). */
+/** Max trace keys held (LRU, evicts oldest whole trace on insert). */
 const MAX_SUBAGENT_TRACES = 500;
-/** Trace TTL: 1h wall-clock, lazily expired on read (Q-30). */
+/** Trace TTL: 1h wall-clock, lazily expired on read. */
 const SUBAGENT_TRACE_TTL_MS = 60 * 60 * 1000;
-/** Max steps retained per trace; oldest steps are dropped beyond this (Q-30). */
+/** Max steps retained per trace; oldest steps are dropped beyond this. */
 const MAX_SUBAGENT_STEPS_PER_TRACE = 100;
-/** Live subscriptions auto-expire after 5min (Q-30). */
+/** Live subscriptions auto-expire after 5min. */
 const SUBAGENT_SUBSCRIBE_TTL_MS = 5 * 60 * 1000;
 
 /** Last-write wall-clock per canonical trackingId (drives TTL; reads do not extend it). */
@@ -135,7 +135,7 @@ function touchTrace(canonical: string, now = Date.now()): void {
 }
 
 /**
- * Evicts expired traces, then oldest whole traces while over budget (Q-30).
+ * Evicts expired traces, then oldest whole traces while over budget.
  * Called on every insert. Whole-trace eviction removes both the canonical
  * key and its display-id alias.
  */
@@ -155,7 +155,7 @@ function pruneTraces(now = Date.now()): void {
   }
 }
 
-/** Drops oldest steps beyond {@link MAX_SUBAGENT_STEPS_PER_TRACE} (Q-30). */
+/** Drops oldest steps beyond {@link MAX_SUBAGENT_STEPS_PER_TRACE}. */
 function trimTraceSteps(trace: SubAgentTrace): void {
   if (trace.steps.length > MAX_SUBAGENT_STEPS_PER_TRACE) {
     trace.steps.splice(0, trace.steps.length - MAX_SUBAGENT_STEPS_PER_TRACE);
@@ -268,7 +268,7 @@ export function subscribeToSubAgentForSessions(
 
 /**
  * Subscribes to live updates of one worker trace. Returns an unsubscribe fn.
- * Subscriptions auto-expire after 5min to avoid listener leaks (Q-30).
+ * Subscriptions auto-expire after 5min to avoid listener leaks.
  */
 export function subscribeToSubAgent(id: string, fn: (trace: SubAgentTrace) => void): () => void {
   const t = lookupTrace(id);
@@ -469,7 +469,7 @@ export function workerMetadata(a: {
 }
 
 // ---------------------------------------------------------------------------
-// Budgets (Q-39): counters + guards. The loop charges usage per turn; the
+// Budgets: counters + guards. The loop charges usage per turn; the
 // worker registry enforces `maxTotalSubagents` through `reserveSpawn`. Durations use the monotonic `nowMs()`
 // clock; TTL timestamps above use wall-clock `Date.now()`.
 // ---------------------------------------------------------------------------
@@ -552,7 +552,7 @@ export function checkBudget(
 }
 
 /**
- * Adds worker usage to the parent's budget counters (Q-39). Never throws;
+ * Adds worker usage to the parent's budget counters. Never throws;
  * call {@link checkBudget} afterwards to enforce.
  */
 export function chargeBudgetUsage(parentAgent: Agent, usage: unknown): BudgetState {
@@ -563,7 +563,7 @@ export function chargeBudgetUsage(parentAgent: Agent, usage: unknown): BudgetSta
 }
 
 /**
- * Reserves `count` spawns against `maxTotalSubagents` (Q-39). Increments the
+ * Reserves `count` spawns against `maxTotalSubagents`. Increments the
  * parent's `budgetState.spawned` and throws {@link BudgetExceededError} when
  * the reservation would exceed the budget. Call before spawning.
  */
@@ -623,7 +623,7 @@ export function agentToTool(
     }),
     execute: async ({ task }, ctx) => {
       const startTime = nowMs();
-      // Q-42 lineage for fixed-delegation calls.
+      // Lineage for fixed-delegation calls.
       const callRunId = newRunId();
       const callTurnId = newTurnId();
       const parentSessionId = ctx?.sessionId || agentInstance.sessionId || "session";