agent-accelerator 0.5.7 → 0.5.9

package/src/streaming/event-stream.ts

@@ -4,7 +4,7 @@ import { telemetryBus } from "../telemetry.ts";
 /** Listener invoked for a matching stream event type or `*`. */
 export type StreamEventListener = (event: StreamEvent) => void;
 
-/** Options for AssistantMessageEventStream (Q-29). */
+/** Options for AssistantMessageEventStream. */
 export interface EventStreamOptions {
   /**
    * When false, `partialText`/`partialThinking` cumulative fields are stripped
@@ -25,9 +25,9 @@ type Resolver = {
   reject: (err: Error) => void;
 };
 
-/** Default max buffered events (Q-29). */
+/** Default max buffered events. */
 export const MAX_BUFFERED_EVENTS = 1000;
-/** Default max approx bytes per delta event (Q-29). */
+/** Default max approx bytes per delta event. */
 export const MAX_EVENT_BYTES = 1_048_576;
 
 // Approximate size of an event's text fields; in: push's oversize guard, out: a character count.
@@ -43,7 +43,7 @@ function approxEventBytes(event: StreamEvent): number {
 // Reports a dropped or overflowing event on the bus and the legacy hook, never throwing; in: push/enqueueBounded, out: telemetryBus.
 function reportStreamAnomaly(detail: { type: string; [k: string]: unknown }): void {
   // why: bus + hook only, never console — streams are hot paths and logging
-  // per-drop would spam and break no-console policy (Q-29/Q-41).
+  // per-drop would spam and break no-console policy.
   telemetryBus.emitWarning(detail.type, `[Agent Accelerator] stream anomaly: ${detail.type}`, detail);
   try {
     (globalThis as unknown as { __agentAccelAnomaly?: (d: unknown) => void }).__agentAccelAnomaly?.(detail);
@@ -68,7 +68,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   private readonly buffered: boolean;
   private readonly maxBufferedEvents: number;
   private readonly maxEventBytes: number;
-  /** First listener exception captured for inspection (Q-29/Q-41). */
+  /** First listener exception captured for inspection. */
   private listenerError: Error | null = null;
   /** Count of events dropped by bounds (buffer cap / oversize / unbuffered). */
   private droppedEvents = 0;
@@ -107,7 +107,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     return this.listenerError;
   }
 
-  /** Number of events dropped by Q-29 bounds. */
+  /** Number of events dropped by bounds. */
   getDroppedCount(): number {
     return this.droppedEvents;
   }
@@ -116,7 +116,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   push(event: StreamEvent): void {
     if (this.finished) return;
 
-    // Q-29: 1MB oversize guard — drop oversized deltas (no console).
+    // 1MB oversize guard — drop oversized deltas (no console).
     if (approxEventBytes(event) > this.maxEventBytes) {
       this.droppedEvents++;
       reportStreamAnomaly({ type: "stream_event_oversize", eventType: event.type });
@@ -132,7 +132,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
 
     if (out.type === "error") {
       this.error = (out.error instanceof Error ? out.error : new Error(String(out.error))) ?? new Error("Unknown error in stream");
-      // Single error semantic (Q-29): deliver the error event to listeners,
+      // Single error semantic: deliver the error event to listeners,
       // reject result(), mark finished, reject pending iterators, and queue
       // the error event so a late iterator observes it before failing.
       this.deliverToListeners(out);
@@ -156,7 +156,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
       resolver.resolve({ value: out, done: false });
     } else {
       // No waiter right now (typical between `next()` polls of a burst):
-      // buffer for the iterator with a hard cap (Q-29). Overflow drops the
+      // buffer for the iterator with a hard cap. Overflow drops the
       // oldest with an anomaly report — see `enqueueBounded`. A stream built
       // with `buffer: false` has no iterator to feed and keeps nothing.
       if (this.buffered) this.enqueueBounded(out);
@@ -194,7 +194,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   private enqueueBounded(event: StreamEvent): void {
     this.queue.push(event);
     while (this.queue.length > this.maxBufferedEvents) {
-      // Drop oldest buffered event to bound memory (Q-29). Error events are
+      // Drop oldest buffered event to bound memory. Error events are
       // never dropped: if the oldest is an error, drop the next-oldest
       // non-error instead; if the queue is all errors, keep them.
       if (this.queue[0]?.type === "error") {
@@ -213,7 +213,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   end(finalResponse?: AgentResponse): void {
     if (this.finished) return;
     if (!finalResponse) {
-      // Q-29: never hang result() — ending without a response is a
+      // Never hang result() — ending without a response is a
       // programming error, so fail loudly instead of leaving consumers
       // waiting forever.
       this.fail(new Error("end() requires response"));

package/src/telemetry-file.ts

@@ -1,34 +1,84 @@
 /**
- * Opt-in disk sink for the telemetry bus (`AgentConfig.telemetry.persist`).
- * Appends one JSON line per event to `<home>/telemetry/<YYYY-MM-DD>.ndjson`.
- * Each event is a single synchronous append, so a process crash keeps every
- * event already emitted: a `tool.call_started` with no ending event was in
- * flight, and the last `tool.progress` shows how far it got. Power loss is not
- * covered (no fsync, by design: this is observability, not state). `turn.thinking`
- * (full reasoning text) is never written. Takes the home's one-process lock.
+ * Opt-in disk sink for the telemetry bus (`AgentConfig.telemetry.persist`). Appends one JSON line per event.
+ * An event that carries the id of a persisted session (`data.sessionId`) goes to that session's own file,
+ * `<session folder>/telemetry.ndjson`, so a session's trace sits next to its journal and tool logs; every other event
+ * goes to `<home>/telemetry/<YYYY-MM-DD>.ndjson`. Nothing is ever written outside a home folder: a session folder
+ * that is not inside a home that enabled telemetry (a `persist.dir` pointing elsewhere) falls back to the daily file.
+ * Each event is a single synchronous append, so a process crash keeps every event already emitted: a
+ * `tool.call_started` with no ending event was in flight, and the last `tool.progress` shows how far it got. Power loss
+ * is not covered (no fsync, by design: this is observability, not state). `turn.thinking` (full reasoning text) is never
+ * written. Several processes may enable the same home: each event is one append, so lines never mix.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { telemetryBus } from "./telemetry.ts";
+import type { TelemetryEvent } from "./telemetry.ts";
 import { safeStringify } from "./utils/serialization.ts";
-import { lockFolder } from "./utils/durable.ts";
 
-const sinks = new Set<string>();
+/** Homes (resolved paths) that asked for telemetry. */
+const homes = new Set<string>();
+/** Where each persisted session lives, by session id. */
+const sessionFolders = new Map<string, string>();
+let unsubscribe: (() => void) | undefined;
 
-/** Starts appending bus events under `home` (idempotent per folder). */
-export function persistTelemetry(home: string): void {
-  const dir = path.join(home, "telemetry");
-  if (sinks.has(dir)) return;
-  lockFolder(home);
-  sinks.add(dir);
-  telemetryBus.onEvent((event) => {
-    if (event.code === "turn.thinking") return;
-    try {
-      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-      const file = path.join(dir, `${new Date(event.timestamp).toISOString().slice(0, 10)}.ndjson`);
-      fs.appendFileSync(file, safeStringify(event) + "\n", { mode: 0o600 });
-    } catch {
-      // why: a full disk must never fail a run, and reporting it would re-enter this listener.
+// True when `folder` is `home` itself or below it; in: the routing decision, out: a boolean.
+function inside(home: string, folder: string): boolean {
+  const rel = path.relative(home, folder);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+// Appends one line to a file, creating its folder; a full disk must never fail a run, and reporting it would re-enter this listener; in: the listener, out: the file.
+function append(file: string, line: string): void {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.appendFileSync(file, line, { mode: 0o600 });
+  } catch {
+    // why: observability must never fail a run.
+  }
+}
+
+// The bus listener: skips reasoning text, writes a session's event to its own folder when that folder is inside an enabled home, else to the daily file of every enabled home; in: each bus event, out: NDJSON files.
+function onEvent(event: TelemetryEvent): void {
+  if (event.code === "turn.thinking") return;
+  const line = safeStringify(event) + "\n";
+  const id = (event.data as { sessionId?: unknown } | undefined)?.sessionId;
+  const folder = typeof id === "string" ? sessionFolders.get(id) : undefined;
+  if (folder && [...homes].some((h) => inside(h, folder))) {
+    append(path.join(folder, "telemetry.ndjson"), line);
+    return;
+  }
+  const day = new Date(event.timestamp).toISOString().slice(0, 10);
+  for (const home of homes) {
+    if (!fs.existsSync(home)) {
+      homes.delete(home); // a deleted home is not recreated by a stray event
+      continue;
     }
-  });
+    append(path.join(home, "telemetry", `${day}.ndjson`), line);
+  }
+}
+
+/** Starts appending bus events for `home` (idempotent per folder); one listener serves every enabled home. */
+export function persistTelemetry(home: string): void {
+  const resolved = path.resolve(home);
+  unsubscribe = telemetryBus.onEvent(onEvent); // listeners are a Set, so this is idempotent, and it restores the sink after `telemetryBus.clear()`
+  if (homes.has(resolved)) return;
+  homes.add(resolved);
+}
+
+/** Remembers where a persisted session lives, so its events are written next to it; in: the Agent constructor and `importSession`, out: the routing map. */
+export function registerSessionFolder(sessionId: string, folder: string): void {
+  sessionFolders.set(sessionId, path.resolve(folder));
+}
+
+/** Forgets a session's folder (its events fall back to the daily file); in: `disposeSession` and `importSession`, out: the routing map. */
+export function unregisterSessionFolder(sessionId: string): void {
+  sessionFolders.delete(sessionId);
+}
+
+/** Forgets every enabled home and session and removes the listener. Test hook (not part of the public entry). */
+export function resetTelemetryFile(): void {
+  homes.clear();
+  sessionFolders.clear();
+  unsubscribe?.();
+  unsubscribe = undefined;
 }

package/src/telemetry.ts

@@ -1,5 +1,5 @@
 /**
- * In-process telemetry bus (Q-41). Library code routes warnings, anomalies and
+ * In-process telemetry bus. Library code routes warnings, anomalies and
  * per-turn traces here instead of `console.*`. The default has zero listeners,
  * so emission is a no-op; CLIs, tests and observability layers attach with
  * `telemetryBus.onEvent`. Intentionally dependency-free: every module in the
@@ -7,7 +7,7 @@
  * it without creating an import cycle.
  */
 
-/** Telemetry event emitted via the in-process bus (Q-41). */
+/** Telemetry event emitted via the in-process bus. */
 export interface TelemetryEvent {
   code: string;
   message: string;

package/src/tools/executor.ts

@@ -539,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/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/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

@@ -4,7 +4,7 @@ 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`, and `lockFolder` (one process per folder, stale-lock takeover, temp sweep). |
+| `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. |
@@ -12,8 +12,8 @@ Small shared helpers. Each file has one job.
 | `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. |
+| `errors.ts` | `toConciseProviderError` (any raw provider failure becomes one-line `ProviderError`: `code` `"provider"`, `retryable` from status/code, the provider's code as `providerCode`; SDK errors pass through), `isTransientError`, and the pre-network modality guards (`ValidationError`). |
+| `retry.ts` | `withRetries`, `isTransientError` (re-exported from `errors.ts`), `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. |