agent-accelerator 0.5.6 → 0.5.8

package/src/tools/executor.ts

@@ -28,20 +28,24 @@ export interface ExecuteToolsOptions {
 
 const DEFAULT_TOOL_CONCURRENCY = 8;
 
+// Wall-clock milliseconds; in: the executor's timing, out: a number.
 function nowMs(): number {
   return Date.now();
 }
 
+// Milliseconds since `start`, at least 1 so a result never reports 0; in: result records, out: durationMs.
 function elapsedMs(start: number): number {
   return Math.max(1, nowMs() - start);
 }
 
+// A finite number >= 0 from a number or numeric string option, else undefined; in: tool options, out: timeout and limits.
 function numericOption(value: number | string | undefined): number | undefined {
   if (value === undefined || value === "") return undefined;
   const parsed = typeof value === "number" ? value : Number(value);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
 }
 
+// numericOption rounded down to a whole number; in: tool options, out: attempts, concurrency and char caps.
 function integerOption(value: number | string | undefined): number | undefined {
   const parsed = numericOption(value);
   return parsed === undefined ? undefined : Math.floor(parsed);
@@ -128,11 +132,13 @@ export function sanitizeErrorMessage(message: string): string {
   return out;
 }
 
+// The tool's `maxResultChars` or the 20000 default; in: runSingle, out: the cap on a result kept for the model.
 function resultCharLimit(toolDef: ToolDefinition): number {
   const configured = integerOption((toolDef as any).maxResultChars);
   return configured && configured > 0 ? configured : DEFAULT_MAX_RESULT_CHARS;
 }
 
+// Cuts a string to the limit and appends a `[Truncated: ...]` note; in: runSingle, out: the capped result.
 function truncateResultString(value: string, limit: number): string {
   if (value.length <= limit) return value;
   return value.slice(0, limit) + `\n[Truncated: showing ${limit} of ${value.length} chars]`;
@@ -275,12 +281,14 @@ export function traceToolEvent(
   });
 }
 
+// Scrubbed, JSON-safe value capped to `max` serialized characters for logs and events; in: progress and event tracing, out: a value or a truncated string.
 function capJson(value: unknown, max = 2000): unknown {
   const safe = scrubErrors(toJsonSafe(value));
   const json = JSON.stringify(safe);
   return typeof json === "string" && json.length > max ? `${json.slice(0, max)}…[truncated]` : safe;
 }
 
+// Edit distance between two strings; in: resolveTool's did-you-mean, out: a number.
 function levenshtein(a: string, b: string): number {
   const row = Array.from({ length: b.length + 1 }, (_, i) => i);
   for (let i = 1; i <= a.length; i++) {
@@ -303,6 +311,7 @@ interface ResolvedTool {
   suggestion?: string;
 }
 
+// Finds the tool a call names (exact, then case/format-insensitive), else suggests the closest name; in: runSingle and findToolDefinition, out: ResolvedTool.
 function resolveTool(tools: Record<string, ToolDefinition>, requestedName: string): ResolvedTool {
   const direct = tools[requestedName];
   if (direct) return { definition: direct, name: direct.name || requestedName };
@@ -348,6 +357,7 @@ class Semaphore {
 
   constructor(private readonly limit: number) {}
 
+  // Takes a slot (immediately if free, else waits in line), rejecting if the run aborts first; in: runSingle, out: a release function.
   acquire(signal?: AbortSignal): Promise<() => void> {
     if (signal?.aborted) return Promise.reject(new Error("Tool execution aborted"));
     if (this.limit === Number.POSITIVE_INFINITY || this.active < this.limit) {
@@ -372,6 +382,7 @@ class Semaphore {
     });
   }
 
+  // Frees a slot and hands it to the next live waiter, dropping aborted ones; in: the function acquire returned, out: the next waiter's grant.
   private release(): void {
     this.active = Math.max(0, this.active - 1);
     while (this.waiters.length > 0) {
@@ -405,6 +416,7 @@ function isTransientError(error: any): boolean {
   return false;
 }
 
+// Waits the retry backoff, rejecting `Tool execution aborted` as soon as the run aborts; in: runSingle's retry loop, out: nothing.
 function waitForRetry(ms: number, signal?: AbortSignal): Promise<void> {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {
@@ -437,6 +449,7 @@ function raceAbort<T>(work: Promise<T>, signal: AbortSignal | undefined): Promis
   });
 }
 
+// One attempt of a tool: runs it, raced against the run's abort and the per-attempt timeout (which also aborts the tool's signal); in: runSingle, out: the tool's result or a thrown timeout/abort.
 async function executeAttempt(
   toolDef: ToolDefinition,
   parsedInput: unknown,
@@ -526,7 +539,7 @@ export async function executeToolCalls(
     let attempts = 0;
     let timedOut = false;
 
-    // Truncated streamed arguments (Q-12): the `__truncated_raw` marker means the
+    // Truncated streamed arguments: the `__truncated_raw` marker means the
     // provider's partial JSON never parsed. Never execute or overwrite wire
     // finishReason here — return a synthetic error so the model retries with
     // complete JSON.

package/src/tools/schema.ts

@@ -160,6 +160,7 @@ function extractZodObjectSchema(zodSchema: any): Record<string, unknown> {
   };
 }
 
+// Best-effort JSON Schema for one Zod property when toJSONSchema is unavailable; in: extractZodObjectSchema, out: a schema fragment.
 function inferZodPropertyType(prop: any): Record<string, unknown> {
   const unwrapped = prop.unwrap?.() || prop._def?.innerType || prop;
   const description = prop.description || unwrapped.description || prop._def?.description;

package/src/tools/subagent-result.ts

@@ -34,6 +34,7 @@ export function isSubagentResult(value: unknown): value is SubagentResult {
   return !!value && typeof value === "object" && (value as Record<symbol, unknown>)[SUBAGENT_RESULT_BRAND] === true;
 }
 
+// A finite number >= 0, else 0; in: normalizeSubagentMetadata, out: a safe usage count.
 const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
 
 /**

package/src/tools/tool.ts

@@ -10,7 +10,7 @@ import { zodToJsonSchema } from "./schema.ts";
 import { ConfigError } from "../types/errors.ts";
 
 /**
- * Valid tool-name pattern (Q-55): 1–64 chars of letters, digits, `_`, `-`.
+ * Valid tool-name pattern: 1–64 chars of letters, digits, `_`, `-`.
  * Names are validated at registration in {@link tool} (record-key fallback
  * included); invalid names throw `ConfigError` with a fix.
  */
@@ -31,7 +31,7 @@ export function assertValidToolName(name: string): void {
 }
 
 /**
- * Normalizes the Q-52 canonical `thinking` option to a bare level.
+ * Normalizes the canonical `thinking` option to a bare level.
  * Accepts a level string or `{ level, budgetTokens }`; `budgetTokens` is
  * carried separately by providers, so only the level is returned here.
  * Resolution honors `thinking ?? thinkingLevel`.
@@ -50,7 +50,7 @@ export function normalizeThinkingV2(
 }
 
 /**
- * Resolves the Q-51 canonical busy policy. `whenBusy` wins over `mode`.
+ * Resolves the canonical busy policy. `whenBusy` wins over `mode`.
  *
  * @example `resolveWhenBusy({ whenBusy: "queue", mode: "steer" }); // "queue"`
  */
@@ -62,7 +62,7 @@ export function resolveWhenBusy(
 }
 
 /**
- * Normalizes the Q-52 `maxAttempts` alias to a `maxTries` value.
+ * Normalizes the `maxAttempts` alias to a `maxTries` value.
  * `maxTries` wins when both are set.
  *
  * @example `normalizeMaxAttempts({ maxAttempts: 3 }); // 3`
@@ -90,7 +90,7 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
   /** Maximum total attempts for transient failures. `0`/omitted means no configured limit. */
   maxTries?: number | string;
   /**
-   * Canonical alias for `maxTries` (Q-52). When both are set, `maxTries` wins.
+   * Canonical alias for `maxTries`. When both are set, `maxTries` wins.
    * Normalized by `normalizeMaxAttempts`.
    */
   maxAttempts?: number | string;
@@ -116,12 +116,12 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
   /** Optional hook to redact/replace the error message sent back to the model. */
   redactError?: (err: unknown) => string;
   /**
-   * Canonical alias for `redactError` (Q-55). When both are set,
+   * Canonical alias for `redactError`. When both are set,
    * `redactError` wins.
    */
   redact?: (err: unknown) => string;
   /**
-   * Explicit retry policy (Q-55). Preferred over bare `maxTries` for new
+   * Explicit retry policy. Preferred over bare `maxTries` for new
    * code; the executor reads via `(toolDef as any).retry`.
    */
   retry?: { maxRetries?: number; baseDelayMs?: number; maxDelayMs?: number };
@@ -165,7 +165,7 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
 export function tool<TInput = any, TOutput = any>(
   options: CreateToolOptions<TInput, TOutput>
 ): ToolDefinition<TInput, TOutput> {
-  // Q-55: names are validated at registration (record-key fallback included).
+  // Names are validated at registration (record-key fallback included).
   if (options.name !== undefined) assertValidToolName(options.name);
   // ToolDefinition (src/types/tool.ts) carries the v2 policies as typed
   // optionals; the executor additionally reads them via `(toolDef as any).*`.

package/src/types/agent.ts

@@ -10,7 +10,7 @@ import type { Agent } from "../agent/agent.ts";
 import type { z } from "zod";
 
 // ---------------------------------------------------------------------------
-// Q-52/Q-53/Q-54 canonical option types (all additive; nothing renamed).
+// Canonical option types (all additive; nothing renamed).
 //
 // Canonical homes (one place per setting):
 // - Worker model: `dynamicSubagents.model` only. Top-level `subagentModel`
@@ -27,10 +27,10 @@ import type { z } from "zod";
 /** Canonical model reference: `provider/model` string, catalog spec, or provider helper result. */
 export type ModelRef = string | ModelSpec | ModelProviderInstance;
 
-/** Canonical reasoning option (Q-52): bare level, or level + explicit token budget. */
+/** Canonical reasoning option: bare level, or level + explicit token budget. */
 export type ThinkingOption = ThinkingLevel | { level?: ThinkingLevel; budgetTokens?: number };
 
-/** Canonical retry policy (Q-54). Read by the loop via `(config as any).retry`. */
+/** Canonical retry policy. Read by the loop via `(config as any).retry`. */
 export interface RetryPolicyConfig {
   maxRetries?: number;
   baseDelayMs?: number;
@@ -38,7 +38,7 @@ export interface RetryPolicyConfig {
   budgetMs?: number;
 }
 
-/** Minimal logger surface for Agent/loop telemetry (Q-54). */
+/** Minimal logger surface for Agent/loop telemetry. */
 export interface AgentLogger {
   debug?: (...args: unknown[]) => void;
   info?: (...args: unknown[]) => void;
@@ -46,17 +46,17 @@ export interface AgentLogger {
   error?: (...args: unknown[]) => void;
 }
 
-/** Canonical tool-selection control (Q-54). String form is the portable subset. */
+/** Canonical tool-selection control. String form is the portable subset. */
 export type ToolChoiceOption =
   | "auto"
   | "none"
   | "required"
   | { mode?: "auto" | "none" | "required"; tool?: string };
 
-/** Canonical stop control (Q-54): sequence(s) halting generation. */
+/** Canonical stop control: sequence(s) halting generation. */
 export type StopOption = string | string[];
 
-/** Canonical structured-output input (Q-61). Zod, JSON Schema, or explicit form. */
+/** Canonical structured-output input. Zod, JSON Schema, or explicit form. */
 export type StructuredOutputOption =
   | z.ZodType
   | Record<string, unknown>
@@ -90,7 +90,7 @@ export interface AgentConfig {
   /** Requested reasoning level, validated against the model catalog. */
   thinkingLevel?: ThinkingLevel;
   /**
-   * Canonical reasoning option (Q-52, preferred over `thinkingLevel`).
+   * Canonical reasoning option (preferred over `thinkingLevel`).
    * Accepts a bare level or `{ level, budgetTokens }`. When both are set,
    * `thinking` wins; resolution honors `thinking ?? thinkingLevel`.
    * See `normalizeThinkingV2` (re-exported from the root entry).
@@ -151,11 +151,11 @@ export interface AgentConfig {
   resume?: "automatic" | "explicit";
   /**
    * Folder for everything Agent Accelerator writes to disk (`sessions/`,
-   * `scheduled_actions/`, `telemetry/`). Defaults to `setHome()`, then the `AGENT_ACCEL_HOME` env var, then `.agent-accel/` in the working directory.
+   * `scheduled/`, `telemetry/`). Defaults to `setHome()`, then the `AGENT_ACCEL_HOME` env var, then `.agent-accel/` in the working directory.
    * An explicit `persist.dir` / `persist.file` still wins for sessions.
    */
   home?: string;
-  // Q-54 missing knobs (all optional, additive; loop reads via `(config as any).*`).
+  // Additional options (all optional, additive; loop reads via `(config as any).*`).
   /**
    * Canonical tool-selection control (`"auto"` default). `"none"` applies to
    * every turn of a run; `"required"` and a pinned tool (`{ tool: "name" }`)
@@ -193,8 +193,10 @@ export interface AgentConfig {
   /** @deprecated Not implemented yet (accepted for forward compatibility; passing it emits a `config.unsupported_option` warning). */
   contextManagement?: unknown;
   /**
-   * Telemetry options. `persist: true` appends every `telemetryBus` event (except full reasoning
-   * text) to `<home>/telemetry/<date>.ndjson`. Off by default: the SDK writes nothing unless asked.
+   * Telemetry options. `persist: true` appends every `telemetryBus` event (except full reasoning text). An event
+   * that belongs to a persisted session (`data.sessionId`: tool events, resume and retry events) goes to
+   * `<session folder>/telemetry.ndjson`, next to the session's journal; every other event goes to
+   * `<home>/telemetry/<date>.ndjson`. Nothing is written outside the home. Off by default: the SDK writes nothing unless asked.
    */
   telemetry?: { persist?: boolean };
   /**
@@ -226,7 +228,7 @@ export interface AgentConfig {
    * models with unknown pricing contribute $0, never a guess.
    */
   budget?: Budget;
-  /** Run + network limits (Q-22). Turn/budget caps unlimited by default; network timeouts finite. */
+  /** Run + network limits. Turn/budget caps unlimited by default; network timeouts finite. */
   limits?: AgentRunLimits;
   /**
    * The only models this agent may use, as `provider/model` strings compared as written. Unset (default) = any model.
@@ -260,7 +262,7 @@ export interface InterruptedRun {
   pendingToolCalls: string[];
 }
 
-/** Per-request + run limits (Q-22). */
+/** Per-request + run limits. */
 export interface AgentRunLimits {
   maxTurns?: number;
   deadlineMs?: number;
@@ -275,7 +277,7 @@ export interface AgentRunLimits {
 /** Developer policy for mid-session new-query insertion while a run is active. */
 export type MidSessionMode = "steer" | "queue" | "auto";
 
-/** Q-51 canonical busy-policy alias: prefer `whenBusy`, `mode` kept for compat. */
+/** Canonical busy-policy alias: prefer `whenBusy`, `mode` kept for compat. */
 export type WhenBusyMode = MidSessionMode;
 
 /** Developer-configured policy for LLM-spawned dynamic sub-agents. */
@@ -288,7 +290,7 @@ export interface MidSessionConfig {
    */
   mode?: MidSessionMode;
   /**
-   * Canonical alias for `mode` (Q-51, preferred). When both are set,
+   * Canonical alias for `mode` (preferred). When both are set,
    * `whenBusy` wins. Accepted anywhere `mode` is read; resolution honors
    * `whenBusy ?? mode ?? "auto"`.
    */
@@ -341,7 +343,7 @@ export interface AgentRunOptions {
   /** Per-run reasoning-level override, validated against the selected model. */
   thinkingLevel?: ThinkingLevel;
   /**
-   * Canonical per-run reasoning option (Q-52, preferred over `thinkingLevel`).
+   * Canonical per-run reasoning option (preferred over `thinkingLevel`).
    * Resolution honors `thinking ?? thinkingLevel`.
    */
   thinking?: ThinkingOption;
@@ -375,7 +377,7 @@ export interface AgentRunOptions {
   wrapThinking?: boolean;
   /** Called after every model/tool turn with a turn summary (also drives sub-agent step logs + durable persistence). */
   onTurn?: (turn: AgentTurnEvent) => void;
-  // Q-54 per-run knobs (all optional, additive; `output` intentionally
+  // Per-run knobs (all optional, additive; `output` intentionally
   // omitted here — it is agent-level only, see AgentConfig.output).
   /** Per-run tool-selection override. */
   toolChoice?: ToolChoiceOption;
@@ -409,7 +411,7 @@ export interface AgentTurnEvent {
   toolResults?: Array<{ id: string; name: string; isError?: boolean }>;
 }
 
-/** Optional run budgets enforced by delegation helpers (Q-39). All fields default to unlimited. */
+/** Optional run budgets enforced by delegation helpers. All fields default to unlimited. */
 export interface Budget {
   /** Maximum total cost in USD across this agent + spawned workers. */
   maxCostUsd?: number;
@@ -433,7 +435,7 @@ export interface BudgetState {
   startedAtMs: number;
 }
 
-/** Run/turn lineage attached to sub-agent metadata via `(metadata as any)` (Q-42). */
+/** Run/turn lineage attached to sub-agent metadata via `(metadata as any)`. */
 export interface SubAgentRunIds {
   /** Stable id for this worker batch/run (`newRunId`). */
   runId?: string;

package/src/types/architecture.md

@@ -0,0 +1,20 @@
+# src/types/
+
+Shared contracts. Types only, plus a few tiny helpers that belong to a type.
+
+| File | What it defines |
+| :-- | :-- |
+| `agent.ts` | `AgentConfig`, `AgentRunOptions`, `DynamicSubagentsConfig`, `Budget`, `EditableAgentConfig`, run/turn event shapes. |
+| `core.ts` | `ThinkingLevel`, `CacheOption` (+ `CACHE_OPTIONS`), `ServiceTier`, `TokenUsage`. |
+| `message.ts` | `Message` and the content parts (text, image, audio, video, file, tool call/result, thinking), `ProviderSteps`. |
+| `model.ts` | `ModelSpec`, `Provider`, `ProviderRequestOptions`, `ProviderGenerateResult`, structured-output spec. |
+| `response.ts` | `AgentResponse`, `FinishReason` + `normalizeFinishReason`, `StreamEvent`, worker metadata. |
+| `tool.ts` | `ToolDefinition`, `ToolExecutionContext` (`log`, `stop`, `emit`), call/result records, the truncated-arguments marker. |
+| `scheduler.ts` | Scheduled-action input, record and delivery types. |
+| `errors.ts` | The typed error family (`AgentAccelError` and subclasses), `isAbortError`. |
+
+## Invariants
+- Adding a field to a public type is a public API change: update `README.md` and `docs/`.
+- Abort means `signal.aborted` or `name === "AbortError"`, never a message match.
+- Error messages are one line and ANSI-free.
+- No logic here beyond `normalizeFinishReason`, `isTruncatedArguments` and the error classes.

package/src/types/response.ts

@@ -67,7 +67,7 @@ export type FinishReason =
 /** Maps a vendor finish reason to canonical FinishReason + raw passthrough.
  * Known aliases collapse to the canonical set; empty/undefined stays
  * undefined; any other non-empty string maps to `"error"` with the original
- * preserved in `rawFinishReason` (Q-04). */
+ * preserved in `rawFinishReason`. */
 export function normalizeFinishReason(raw?: string): {
   finishReason?: FinishReason;
   rawFinishReason?: string;
@@ -118,7 +118,7 @@ export interface AgentResponseJSON {
   model: string;
   provider: ProviderId | string;
   finishReason?: FinishReason;
-  /** Original vendor finish string when it differs from canonical `finishReason` (Q-04). */
+  /** Original vendor finish string when it differs from canonical `finishReason`. */
   rawFinishReason?: string;
   durationMs: number;
   raw: ProviderRawData;
@@ -140,7 +140,7 @@ export class AgentResponse {
   readonly model: string;
   readonly provider: ProviderId | string;
   readonly finishReason?: FinishReason;
-  /** Original vendor finish string when it differs from canonical `finishReason` (Q-04). */
+  /** Original vendor finish string when it differs from canonical `finishReason`. */
   readonly rawFinishReason?: string;
   readonly durationMs: number;
   readonly raw: ProviderRawData;
@@ -247,15 +247,15 @@ export type StreamEventType =
 /** Payload for one streaming text, thinking, tool, usage, or lifecycle event. */
 export interface StreamEvent {
   type: StreamEventType;
-  /** Schema version for typed consumers (Q-40). Currently always 1 when present. */
+  /** Schema version for typed consumers. Currently always 1 when present. */
   schemaVersion?: 1;
   delta?: string;
   thinkingDelta?: string;
   toolCall?: ToolCallRecord;
   toolResult?: ToolResultRecord;
-  /** Batch tool calls for `tool_start` events (Q-40). */
+  /** Batch tool calls for `tool_start` events. */
   toolCalls?: ToolCallRecord[];
-  /** Batch tool results for `tool_end` events (Q-40). */
+  /** Batch tool results for `tool_end` events. */
   toolResults?: ToolResultRecord[];
   subagent?: SubAgentExecutionMetadata;
   /** Tracking id of the worker emitting a `subagent_delta` event. */
@@ -271,7 +271,7 @@ export interface StreamEvent {
   /** Canonical finish reason when known; vendor strings pass through as-is
    * for provider compat (normalize with `normalizeFinishReason`). */
   finishReason?: string;
-  /** Original vendor finish string when it differs from canonical (Q-04). */
+  /** Original vendor finish string when it differs from canonical. */
   rawFinishReason?: string;
   error?: Error | unknown;
   partialText?: string;
@@ -279,7 +279,7 @@ export interface StreamEvent {
   raw?: ProviderRawData;
 }
 
-/** Typed (discriminated) stream event schema, version 1 (Q-40).
+/** Typed (discriminated) stream event schema, version 1.
  * `StreamEvent` stays the permissive compat shape; use this union when you
  * want exhaustive switching (e.g. `tool_start`/`tool_end` lifecycle). */
 export type StreamEventV2 =

package/src/types/scheduler.ts

@@ -1,4 +1,4 @@
-/** Lifecycle of a scheduled action as stored in `tasks.json`. */
+/** Lifecycle of a scheduled action as stored in `task.json`. */
 export type ScheduledState = "waiting" | "cooking" | "missed" | "done";
 
 /** Outcome of one run. */
@@ -45,7 +45,7 @@ export type ScheduledActionPatch = Partial<Omit<ScheduledActionInput, "scheduled
   scheduled_action?: Partial<Omit<ScheduledActionInput["scheduled_action"], "id">>;
 };
 
-/** One entry of `tasks.json`. All times are local clock strings `YYYY-MM-DDTHH:mm:ss` (no offset). */
+/** The record inside an action's `task.json`. All times are local clock strings `YYYY-MM-DDTHH:mm:ss` (no offset). */
 export interface ScheduledActionRecord {
   id: string;
   name: string;

package/src/types/tool.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod";
 
-/** Minimal logger surface accepted by tool contexts (Q-54/Q-55, additive). */
+/** Minimal logger surface accepted by tool contexts (additive). */
 export interface ToolLogger {
   debug?: (...args: unknown[]) => void;
   info?: (...args: unknown[]) => void;
@@ -8,7 +8,7 @@ export interface ToolLogger {
   error?: (...args: unknown[]) => void;
 }
 
-/** Live-event emitter handed to tools that stream progress (Q-55, additive). */
+/** Live-event emitter handed to tools that stream progress (additive). */
 export type ToolEmitFn = (event: { type: string; [k: string]: unknown }) => void;
 
 export interface ToolExecutionContext {
@@ -22,7 +22,7 @@ export interface ToolExecutionContext {
   sessionId?: string;
   /** Forwards live sub-agent deltas (used by the `subagents` tool for realtime tracking). */
   onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
-  // Q-55 Tool API v2 context additions (all optional, additive).
+  // Tool API v2 context additions (all optional, additive).
   /** Stable id for this run (`newRunId`). Mirrors SubAgentRunIds.runId. */
   runId?: string;
   /** Live-event emitter for tools that stream progress. */
@@ -69,7 +69,7 @@ export interface ToolDefinition<TInput = any, TOutput = any> {
   maxConcurrency?: number | string;
   /** Function executed after validation; its result is made JSON-safe for model context. */
   execute: ToolExecuteFn<TInput, TOutput>;
-  // Q-55 Tool API v2 additions (all optional, additive; loop reads via `(toolDef as any).*`).
+  // Tool API v2 additions (all optional, additive; loop reads via `(toolDef as any).*`).
   /**
    * Canonical alias for `maxTries`. When both are set, `maxTries` wins.
    * Normalized by `normalizeMaxAttempts` (see tools/tool.ts).
@@ -101,7 +101,7 @@ export interface ToolDefinition<TInput = any, TOutput = any> {
   redactError?: (err: unknown) => string;
   /**
    * Canonical alias for `redactError`. When both are set, `redactError` wins.
-   * Kept short for Q-55 Tool API v2 parity.
+   * Kept short for Tool API v2 parity.
    */
   redact?: (err: unknown) => string;
   /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */

package/src/update-models.ts

@@ -12,7 +12,7 @@ import { refreshModelCatalog } from "./index.ts";
 import { ConfigError } from "./types/errors.ts";
 
 const args = process.argv.slice(2);
-// Q-34: force is true only with explicit --force (previously also true when no --ttl).
+// Force is true only with explicit --force (previously also true when no --ttl).
 const force = args.includes("--force");
 
 let customTtlMs: number | undefined;
@@ -26,7 +26,7 @@ for (const arg of args) {
     } else {
       customTtlMs = parseFloat(val);
     }
-    // Q-34: reject non-numeric TTLs (e.g. --ttl=abc) instead of silently caching NaN.
+    // Reject non-numeric TTLs (e.g. --ttl=abc) instead of silently caching NaN.
     if (!Number.isFinite(customTtlMs)) {
       throw new ConfigError(`Invalid --ttl value "${val}": expected a number with optional h/m suffix (e.g. --ttl=24h).`);
     }

package/src/utils/architecture.md

@@ -0,0 +1,25 @@
+# src/utils/
+
+Small shared helpers. Each file has one job.
+
+| File | What it does |
+| :-- | :-- |
+| `durable.ts` | The ONE disk writer (`writeFileDurable`: temp, fsync, `.bak`, rename, folder fsync), `readWithBackup`, `lockFolder` (one process per folder, used for session folders; stale-lock takeover, temp sweep) and `withFileMutex` (short per-file lock for state several processes change, e.g. one scheduled action). |
+| `home.ts` | `resolveHome` / `setHome`: the single folder everything is stored in. |
+| `env.ts` | Process-env lookups and API key resolution. No `globalThis` fallback. |
+| `headers.ts` | Session-affinity headers, opt-in attribution, browser stripping, package version fallback. |
+| `media.ts` | Normalizes a path, URL, data URL, base64 or bytes to base64 and a MIME type; magic-byte sniffing. |
+| `safe-io.ts` | `fileAccess.roots` containment and the guarded remote fetch (private hosts refused, redirects re-checked, size cap). |
+| `raw-capture.ts` | The `captureRaw` policy for `AgentResponse.raw`. |
+| `cache.ts` | Cache-key clamp (64 chars) and the central secret redaction. |
+| `errors.ts` | `toConciseProviderError` and pre-network modality guards. |
+| `retry.ts` | `withRetries`, `isTransientError`, `isRetryableRun`, `sleep`. Structured data only (status, code, flags), never message text. |
+| `session.ts` | Id helpers (`createSessionId`, `hashSessionPart`, `createTrackingId`, run/turn ids), `parseModelRef`, `previewPrompt`. |
+| `serialization.ts` | `toJsonSafe`, `safeStringify`, `escapeXml`. |
+| `base64.ts`, `thought-signature.ts` | Runtime-agnostic base64; Gemini thought-signature helpers. |
+
+## Invariants
+- Never write state with a bare `writeFileSync`; use `writeFileDurable`.
+- `media.ts` and `safe-io.ts` import `node:*` lazily so browser bundles keep working.
+- Redaction is central (`cache.ts`); adapters must not keep their own deny-lists.
+- `AGENT_ACCEL_HOME` is read at import time; `setHome()` after import relies on the catalog reload hook.

package/src/utils/base64.ts

@@ -1,5 +1,6 @@
 /** Runtime-agnostic base64 helpers — no Node Buffer, safe in browsers. */
 
+/** Decodes base64 (whitespace ignored) to bytes, with Buffer when present, else atob; in: media and session code, out: a Uint8Array. */
 export function base64ToBytes(b64: string): Uint8Array {
   const clean = b64.replace(/\s/g, "");
   const nodeBuffer = (globalThis as any)?.Buffer;
@@ -13,6 +14,7 @@ export function base64ToBytes(b64: string): Uint8Array {
   return out;
 }
 
+/** Encodes bytes as base64, with Buffer when present, else btoa in chunks; in: media and session code, out: a string. */
 export function bytesToBase64(bytes: Uint8Array): string {
   const nodeBuffer = (globalThis as any)?.Buffer;
   if (nodeBuffer && typeof nodeBuffer.from === "function") {

package/src/utils/cache.ts

@@ -11,7 +11,7 @@ export function clampCacheKey(key?: string): string | undefined {
 }
 
 // ---------------------------------------------------------------------------
-// Central redaction helpers (Q-11, temporary home to avoid owner conflicts).
+// Central redaction helpers (temporary home to avoid owner conflicts).
 // Providers must call these instead of maintaining local deny-lists.
 // ---------------------------------------------------------------------------
 
@@ -28,11 +28,13 @@ const SENSITIVE_VALUE_PATTERNS: RegExp[] = [
   /(^|[^A-Za-z0-9])AIza[A-Za-z0-9_-]{10,}/,
 ];
 
+// True when a header name contains key, token, secret, cookie or authorization; in: redactHeadersCentral, out: a boolean.
 function headerNameIsSensitive(name: string): boolean {
   const lower = String(name ?? "").toLowerCase();
   return REDACT_HEADER_SUBSTRINGS.some((s) => lower.includes(s));
 }
 
+// True when a string looks like a credential (sk-, gsk_, xox, AIza, long Bearer token); in: the redactors, out: a boolean.
 function valueLooksSensitive(value: unknown): boolean {
   if (typeof value !== "string") return false;
   const v = value.trim();
@@ -43,7 +45,7 @@ function valueLooksSensitive(value: unknown): boolean {
 }
 
 /**
- * Redacts a single value: sensitive strings become "[REDACTED]" (Q-11).
+ * Redacts a single value: sensitive strings become "[REDACTED]".
  */
 export function redactValue(value: unknown): unknown {
   if (typeof value !== "string") return value;
@@ -52,7 +54,7 @@ export function redactValue(value: unknown): unknown {
 }
 
 /**
- * Redacts sensitive header values (Q-11). Returns a shallow copy; input untouched.
+ * Redacts sensitive header values. Returns a shallow copy; input untouched.
  * Deny-list (name contains): *key*, *token*, *secret*, cookie, authorization.
  * Value patterns (redacted regardless of name): sk-, AIza, gsk-, xox-.
  */
@@ -69,7 +71,7 @@ export function redactHeadersCentral(
 }
 
 /**
- * Redacts secret-looking substrings inside free text (Q-11).
+ * Redacts secret-looking substrings inside free text.
  * Replaces `sk-...`, `AIza...`, `gsk-...`, `xox-...` tokens with "[REDACTED]".
  */
 export function redactText(text: string): string {