agent-accelerator 0.5.7 → 0.5.8

package/README.md

@@ -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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "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";
@@ -66,7 +66,7 @@ export function resolveEffectiveThinking(
 import { ConfigError, SessionLoadError, 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;
@@ -678,13 +704,13 @@ export class Agent {
     this.context.thoughtSignatures = [];
     this.context.systemPrompt = this.getFullInstructions();
     this.runMarks.length = 0;
-    // Q-25: reset also drops session-scoped provider chaining/routing.
+    // 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 +722,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 +780,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 +794,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) {
@@ -964,7 +991,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 +1043,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 +1107,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 +1260,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 +1301,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 +1360,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 +1392,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 +1482,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 +1531,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 +1601,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 +1654,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,7 +1690,7 @@ 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(
@@ -1662,7 +1699,7 @@ export class Agent {
     }
     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 +1765,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 +1903,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) {

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";