agent-accelerator 0.5.6 → 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`.
 
@@ -386,12 +386,14 @@ telemetryBus.onEvent((e) => {
 | `skipScheduledAction(id, { home? })` | Ignore a missed run and wait for the next scheduled time. |
 | `deleteScheduledAction(id, { force?, purge?, home? })` | Delete for good. While it is cooking nothing changes unless `force: true`; `purge: true` also deletes past run files. |
 
+Every function except `createScheduledAction` finds the home folder through `setHome()`, `AGENT_ACCEL_HOME`, or `.agent-accel/` in the working directory. If you built the Agent with its own `home`, pass the same `{ home }` to these calls (the model's `scheduled_actions` tool already does).
+
 **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`.
@@ -657,7 +659,7 @@ Implement the `Provider` interface when adding a fully custom transport.
 
 ### Google
 
-`GoogleInteractionsProvider` (aliased as `GoogleAIStudioProvider`) and `GOOGLE_MODELS` provide Google support over the Interactions API (`POST {baseUrl}/interactions`, streaming via `?alt=sse`).
+`GoogleInteractionsProvider` and `GOOGLE_MODELS` provide Google support over the Interactions API (`POST {baseUrl}/interactions`, streaming via `?alt=sse`).
 
 Turns chain statefully through `previous_interaction_id` per session, falling back to stateless full-history sends when the session switches providers or models.
 
@@ -683,7 +685,7 @@ Helpers:
 
 ### OpenAI
 
-`OpenAIResponsesProvider` (aliased as `OpenAIProvider`) and `OPENAI_MODELS` provide OpenAI support over the Responses API (`POST {baseUrl}/responses`).
+`OpenAIResponsesProvider` and `OPENAI_MODELS` provide OpenAI support over the Responses API (`POST {baseUrl}/responses`).
 
 Every turn is stateless: the full history is sent explicitly with `store: false`, so no `previous_response_id`, `background`, or conversation chaining is ever used.
 
@@ -702,7 +704,7 @@ It also:
 
 ### OpenRouter
 
-`OpenRouterChatCompletionsProvider` (aliased as `OpenRouterProvider` / `OpenRouter`) and `OPENROUTER_MODELS` provide OpenRouter support over Chat Completions (`POST {baseUrl}/chat/completions`).
+`OpenRouterChatCompletionsProvider` and `OPENROUTER_MODELS` provide OpenRouter support over Chat Completions (`POST {baseUrl}/chat/completions`).
 
 Every turn is stateless: the full `messages[]` array is sent explicitly — no chaining primitives exist on this endpoint.
 
@@ -731,7 +733,7 @@ setAttribution({ referer: "https://my.app", title: "My App" });
 
 ### Custom
 
-`OpenAICompatibleProvider` is also exposed through the `CustomProvider`, `createCustomProvider`, and `createOpenAICompatibleProvider(prefix, opts?)` aliases.
+`OpenAICompatibleChatProvider` is also exposed through the `CustomProvider`, `createCustomProvider`, and `createOpenAICompatibleProvider(prefix, opts?)` aliases.
 
 `CustomProviderOptions`:
 
@@ -931,15 +933,6 @@ Use:
 Breaking out of `for await` cancels the stream. Your `AbortSignal` and stream cancellation share one linked controller, so `controller.abort()` and `stream.cancel()` both stop the HTTP request. Abort rejects with `AbortError` (never retried) and never resolves partial results. `agent.run(prompt, { stream: true, signal })` exposes the same
 `cancel` handle.
 
-`SSEParser` provides:
-
-```ts
-feed(chunk)
-flush()
-```
-
-It parses provider SSE streams and is only needed when implementing custom transports.
-
 ---
 ## Response, Usage, and Raw Data
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.5.6",
+  "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,14 +22,14 @@ 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";
 import { assertNoToolCollisions } from "../tools/executor.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 { createSessionId, nowMs, newRunId, previewPrompt } from "../utils/session.ts";
 import {
   chargeBudgetUsage,
   checkBudget,
@@ -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;
@@ -590,7 +616,7 @@ export class Agent {
       .map((m) => ({
         runId: m.id,
         startedAt: m.at,
-        prompt: this.previewPrompt((this.context.messages[m.i]?.content ?? "") as string | ContentPart[]),
+        prompt: previewPrompt((this.context.messages[m.i]?.content ?? "") as string | ContentPart[]),
         pendingToolCalls: calls,
       }));
   }
@@ -652,6 +678,7 @@ export class Agent {
     this.doPersist();
   }
 
+  // Builds the system prompt: the developer's instructions plus, when thinking is on, the fixed Reasoning Directive; in: this.instructions + thinkingConfig, out: every AgentContext.systemPrompt.
   private getFullInstructions(): string | undefined {
     const base = this.instructions || "";
     let out = base;
@@ -677,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
@@ -695,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()]) {
@@ -752,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;
@@ -766,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) {
@@ -799,12 +827,14 @@ export class Agent {
     return this.midSessionConfig.mode;
   }
 
+  // Picks steer or queue for a call that arrives while busy: the developer's enforced midSession mode wins over the per-call request; in: run()/stream() `enqueue`, out: their busy branch.
   private resolveEnqueueMode(requested?: "steer" | "queue"): "steer" | "queue" {
     const enforced = this.midSessionConfig.mode;
     if (enforced === "steer" || enforced === "queue") return enforced;
     return requested === "steer" ? "steer" : "queue";
   }
 
+  // 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(
@@ -813,19 +843,6 @@ export class Agent {
     }
   }
 
-  private previewPrompt(prompt: string | ContentPart[]): string {
-    if (typeof prompt === "string") return prompt.slice(0, 500);
-    try {
-      const texts = prompt
-        .filter((p) => (p as { type?: unknown }).type === "text")
-        .map((p) => (p as { text?: string }).text ?? "")
-        .join("\n");
-      return (texts || "[multipart]").slice(0, 500);
-    } catch {
-      return "[multipart]";
-    }
-  }
-
   /**
    * Stops the active run now (STOP.) and, given a message, starts it next (STOP. Do this instead). The provider
    * request is aborted (connection closed, so the provider stops generating where it can), the stream is cancelled, and
@@ -961,19 +978,20 @@ export class Agent {
       try {
         this.currentRun?.outerStream?.push({
           type: "queued",
-          queuedPrompt: this.previewPrompt(prompt),
+          queuedPrompt: previewPrompt(prompt),
           queueLength: this.pendingQueue.length,
         } as any);
       } catch {}
     });
   }
 
+  // Starts the next waiting prompt (urgent ones first, aborted ones rejected) as a streaming or non-streaming run once the agent is idle; in: finishCurrentRun and queue changes, out: a new run whose result settles the queued caller.
   private pumpQueue(): void {
     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.
+    // 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;
@@ -1023,8 +1041,9 @@ export class Agent {
     this.startNonStreamingRun(next.prompt, next.options).then(next.resolve, next.reject);
   }
 
+  // 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;
@@ -1065,6 +1084,7 @@ export class Agent {
     queueMicrotask(() => this.pumpQueue());
   }
 
+  // Removes the abort listener a run's merged signal fallback installed; in: a settled run's controller, out: nothing.
   private cleanupMerge(runController: AbortController): void {
     try {
       const dispose = mergeDisposers.get(runController);
@@ -1075,6 +1095,7 @@ export class Agent {
     } catch {}
   }
 
+  // Joins the caller's AbortSignal with the run's own controller (AbortSignal.any, else a manual forward) so both stop the run; in: AgentRunOptions.signal + the run controller, out: the signal handed to the loop.
   private mergeUserSignal(userSignal?: AbortSignal, runController?: AbortController): AbortSignal | undefined {
     if (!runController) return userSignal;
     if (!userSignal) return runController.signal;
@@ -1086,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") {
@@ -1227,6 +1248,7 @@ export class Agent {
     };
   }
 
+  // Runs one non-streaming run as a task: catalog refresh, model resolve, prompt/mark (or a resumed mark), loop with `runRetries` backoff, trace merge, run ending recorded; in: run()/queue/resume(), out: the AgentResponse promise.
   private startNonStreamingRun(
     prompt: string | ContentPart[],
     options?: AgentRunOptions,
@@ -1238,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();
@@ -1279,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 } : {}),
       };
@@ -1328,6 +1350,7 @@ export class Agent {
     return task;
   }
 
+  // Starts one streaming run: validates the model and thinking level synchronously, adds the prompt, builds the loop config and returns the loop's event stream, recording the run ending when it settles; in: stream()/pumpQueue, out: an AssistantMessageEventStream.
   private startStreamingRun(
     prompt: string | ContentPart[],
     options?: AgentRunOptions
@@ -1337,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();
@@ -1369,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 } : {}),
     };
@@ -1459,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 {}
@@ -1508,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 {}
     }
   }
@@ -1578,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 {
@@ -1621,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 {}
@@ -1655,8 +1688,9 @@ export class Agent {
     } catch {}
   }
 
+  // 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(
@@ -1665,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 = [];
     }
@@ -1731,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;
@@ -1791,7 +1825,7 @@ export class Agent {
           try {
             this.currentRun?.outerStream?.push({
               type: "queued",
-              queuedPrompt: this.previewPrompt(prompt),
+              queuedPrompt: previewPrompt(prompt),
               queueLength: this.pendingQueue.length,
             } as any);
           } catch {}
@@ -1869,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) {
@@ -1933,7 +1967,7 @@ export class Agent {
         try {
           this.currentRun.outerStream?.push({
             type: "queued",
-            queuedPrompt: this.previewPrompt(prompt),
+            queuedPrompt: previewPrompt(prompt),
             queueLength: this.pendingQueue.length + 1,
           } as any);
         } catch {}
@@ -2008,6 +2042,7 @@ export class Agent {
     return s;
   }
 
+  // Attaches onEvent/onDelta/onThinkingDelta to a stream and, with wrapThinking, adds display-only <think> tags and whitespace hygiene on the outer events; in: stream()/pumpQueue, out: listeners on the stream.
   private wireStreamCallbacks(
     s: AssistantMessageEventStream,
     options?: AgentRunOptions

package/src/agent/architecture.md

@@ -0,0 +1,25 @@
+# src/agent/
+
+The agent and everything that runs under it.
+
+| File | What it is | Used by |
+| :-- | :-- | :-- |
+| `agent.ts` | `Agent`: `run`/`stream`/`ask`, `steer`/`queue`/`interrupt`, persistence hooks, `resume()`/`interrupted()`, `usageReport()`, `fork()`, `toConfig()`/`fromConfig()`, the `workers` getter. | callers, workers, scheduler |
+| `loop.ts` | `runAgentLoop` / `streamAgentLoop`: per turn budget, pairing repair, file access, provider call, tool execution, repeat guard. Also `ensureToolPairing`, `accumulateUsage`. | `Agent` |
+| `context.ts` | `AgentContext`: the validated message list with checkpoint/rollback. | `Agent`, loops |
+| `delegation.ts` | Fixed workers (`agentToTool`, `buildAgentTools`), the live worker trace store, session-id helpers, budget helpers, `openWorkerTrace`/`workerMetadata`. | `Agent`, `workers.ts` |
+| `worker.ts` | Worker core: model/tool normalization, `buildDynamicWorkerConfig` (shared preset), `createLiveWorker`. | `Agent`, registry, scheduler |
+| `workers.ts` | `WorkerRegistry` (`agent.workers`): persistent multi-turn workers. | `Agent`, `subagents` tool |
+| `subagents-tool.ts` + `subagents.md` | The one model-facing `subagents` tool; the `.md` is its description. | `Agent` constructor |
+| `subagent.ts` | `SubAgent` class and `agentFromEnv` (thin, kept for compatibility). | callers |
+| `turns.ts` | Pure grouping of messages into finished turns (history cut for workers). | `workers.ts` |
+| `config-blocks.ts` | RSI blocks: only `model`, `instructions`, `tools` are editable; `allowedModels` check. | `Agent` |
+
+## Invariants
+- `runAgentLoop` and `streamAgentLoop` duplicate their turn logic: every loop change goes into both.
+- An `Agent` runs one thing at a time; delegation forks a copy per call so parallel calls never queue.
+- A worker is a plain `Agent` with a parent link and presets. Never duplicate logic between Agent and worker.
+- A worker is never less constrained than its parent (`inheritableConfig()`); its children draw only from the tools it was granted.
+- 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.

package/src/agent/context.ts

@@ -6,6 +6,7 @@ import { clearInteractionChains } from "../providers/google.ts";
 
 const USER_PART_TYPES = new Set(["text", "image", "audio", "video", "file"]);
 
+// Throws the AgentContext validation error with the SDK prefix; in: the add* validators, out: a thrown Error.
 function fail(message: string): never {
   throw new Error(`[Agent Accelerator] AgentContext: ${message}`);
 }
@@ -32,6 +33,7 @@ export class AgentContext {
     this.systemPrompt = systemPrompt;
   }
 
+  // Validates a user prompt (string or media/text parts) and appends it; in: Agent.prepareTurn and drained steers, out: messages.
   addUserMessage(content: string | ContentPart[]): void {
     if (Array.isArray(content)) {
       if (content.length === 0) return;
@@ -120,6 +122,7 @@ export class AgentContext {
     }
   }
 
+  // Appends one tool message per result, keeping logFile and stopped marks; in: the loops after a tool batch, out: messages.
   addToolResults(results: ToolResultRecord[]): void {
     if (!results || results.length === 0) return;
     for (let i = 0; i < results.length; i++) {
@@ -145,6 +148,7 @@ export class AgentContext {
     }
   }
 
+  // Copies the context with media bytes preserved (structuredClone, else a deep copy); in: callers needing an isolated history, out: a new AgentContext.
   clone(): AgentContext {
     const next = new AgentContext(this.systemPrompt);
     // Preserve Uint8Array/ArrayBuffer media via structuredClone when available (M8 fix)
@@ -166,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.
    */
@@ -181,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 {