agent-accelerator 0.5.6 → 0.5.8

package/src/session/store.ts

@@ -127,10 +127,12 @@ export interface PersistedAgentSession {
   tools?: SessionToolRecord[];
 }
 
+/** Zeroed cumulative session totals; in: SessionTelemetry, out: a SessionTotals. */
 export function emptyTotals(): SessionTotals {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, cost: 0 };
 }
 
+// A finite non-negative number, else 0; in: telemetry and formatting, out: a safe number.
 function toNumber(n: unknown): number {
   const v = typeof n === "number" ? n : Number(n);
   return Number.isFinite(v) && v >= 0 ? v : 0;
@@ -164,7 +166,7 @@ function specFor(modelStr: string): ReturnType<typeof getModelFromCatalog> {
 }
 
 /** Context window for telemetry display. Falls back to 1M like the chat CLI.
- * @deprecated (Q-34) Kept for compat; new code should use
+ * @deprecated Kept for compat; new code should use
  * `getSessionContextWindowOrUndefined` and handle `undefined` explicitly.
  */
 export function getSessionContextWindow(modelStr: string): number {
@@ -191,6 +193,7 @@ export function computeSessionTurnCost(usage: TokenUsage, modelStr: string): num
   }
 }
 
+/** Compact token count (`1.2k`, `3.4M`); in: the status bar, out: a string. */
 export function formatSessionTokens(n: number): string {
   const v = toNumber(n);
   if (v >= 1e6) return `${(v / 1e6).toFixed(1)}M`;
@@ -198,6 +201,7 @@ export function formatSessionTokens(n: number): string {
   return `${Math.floor(v)}`;
 }
 
+/** Cost with precision that fits its size (`$0.0042`); in: the status bar and banner, out: a string. */
 export function formatSessionCost(c?: number): string {
   if (!c || c <= 0) return "$0.00";
   if (c < 0.0001) return `$${c.toFixed(6)}`;
@@ -246,10 +250,12 @@ export class SessionTelemetry {
     return turnCost;
   }
 
+  // Zeroes the totals; in: callers starting a fresh session, out: this.totals.
   reset(): void {
     this.totals = emptyTotals();
   }
 
+  // A copy of the totals for saving; in: buildSessionData/JSON.stringify, out: a SessionTotals.
   toJSON(): SessionTotals {
     return { ...this.totals };
   }
@@ -343,6 +349,7 @@ export interface SessionAgentLike {
   context: { systemPrompt?: string; messages: Message[] };
 }
 
+// Slims worker traces for the snapshot (one key per tracking id, repeated final text dropped, reasoning kept); in: buildSessionData, out: the `subagents` field.
 function snapshotSubagents(traces: Record<string, PersistedSubAgentTrace> | undefined): Record<string, PersistedSubAgentTrace> | undefined {
   if (!traces) return undefined;
   const keys = Object.keys(traces);
@@ -562,12 +569,13 @@ function toCacheOption(raw: unknown): CacheOption | undefined {
   return typeof retention === "string" ? legacy[retention] : undefined;
 }
 
+// Parses any supported snapshot shape (current, legacy pretty JSON, JSONL, ancient) or flags it over-limit; in: raw file text, out: a session, null or OVER_LIMIT.
 function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSession | null | typeof OVER_LIMIT {
   const maxMessages = limits?.maxMessages ?? MAX_SESSION_MESSAGES;
   const maxBytes = limits?.maxBytes ?? MAX_SESSION_JSON_BYTES;
   const text = (raw ?? "").trim();
   if (!text) return null;
-  // Q-10: oversized payloads are rejected, but flagged as over-limit (NOT corrupt).
+  // Oversized payloads are rejected, but flagged as over-limit (NOT corrupt).
   if (text.length > maxBytes) return OVER_LIMIT;
   try {
     // Legacy JSONL: lines shaped {type: session|mainModel|subagentModel|metrics|message|...}
@@ -618,7 +626,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
         }
       }
       if (!sessionId && messages.length === 0) return null;
-      // Q-10: oversize guard — flagged as over-limit, not corrupt.
+      // Oversize guard — flagged as over-limit, not corrupt.
       if (messages.length > maxMessages) return OVER_LIMIT;
       return {
         version: 1,
@@ -637,7 +645,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
     }
     const obj: any = JSON.parse(text);
     if (!obj || typeof obj !== "object") return null;
-    // Q-10: version check — reject unknown versions, accept legacy shapes
+    // Version check — reject unknown versions, accept legacy shapes
     // that predate versioning (no version field).
     if ("version" in obj && (obj as { version?: unknown }).version !== 1) return null;
     // Very old single-JSON shape without version: {sessionId, model, context:{messages}}
@@ -780,10 +788,12 @@ export function saveSessionFile(
 
 const MEDIA_PART_KEYS = ["image", "audio", "video", "file"] as const;
 
+// True for an http(s) link, which stays a reference instead of being saved as media; in: embeddedMedia, out: a boolean.
 function isHttpRef(value: string): boolean {
   return value.startsWith("http://") || value.startsWith("https://");
 }
 
+// Splits a `data:<mime>;base64,<payload>` string; in: embeddedMedia, out: its mime type and payload or undefined.
 function parseDataUrl(value: string): { mimeType: string; base64: string } | undefined {
   const m = value.match(/^data:([^;,]+)?(?:;[^,]*)?;base64,(.+)$/s);
   if (m && m[2]) return { mimeType: m[1] || "application/octet-stream", base64: m[2] };
@@ -797,6 +807,7 @@ function looksLikeEmbeddedBase64(value: string): boolean {
   return /^[A-Za-z0-9+/=\n\r]+$/.test(value.slice(0, 500));
 }
 
+// File extension for saved media from its mime type, else its filename, else `bin`; in: embeddedMedia, out: the extension.
 function extForMedia(mimeType?: string, filename?: string): string {
   const mime = (mimeType || "").toLowerCase().split(";")[0]!.trim();
   const known: Record<string, string> = {
@@ -850,6 +861,7 @@ export function embeddedMedia(part: ContentPart): { key: (typeof MEDIA_PART_KEYS
   return { key, bytes, ...(mimeType ? { mimeType } : {}), ext: extForMedia(mimeType, typeof p["filename"] === "string" ? (p["filename"] as string) : undefined) };
 }
 
+// Copy of the messages that keeps media bytes (structuredClone, else JSON); in: extractMediaToDir/resolveMediaPaths, out: a new array.
 function cloneMessages(messages: Message[]): Message[] {
   try {
     const g: any = globalThis as any;
@@ -966,7 +978,7 @@ export function saveSessionDir(
   agent: SessionAgentLike,
   telemetry?: SessionTelemetry | SessionTotals | null
 ): string {
-  // Q-28-partial: sessionDirFor already enforces assertValidSessionId.
+  // sessionDirFor already enforces assertValidSessionId.
   const sessionDir = sessionDirFor(rootDir, agent.sessionId);
   try {
     fs.mkdirSync(sessionDir, { recursive: true });
@@ -1127,7 +1139,7 @@ export function findLatestSessionDir(rootDir: string): string | null {
 }
 
 // ---------------------------------------------------------------------------
-// Q-10: session validation (append-only; deserializeSession above only gained
+// Session validation (append-only; deserializeSession above only gained
 // size/version guards, no behavior change otherwise).
 // ---------------------------------------------------------------------------
 
@@ -1136,6 +1148,7 @@ export const MAX_SESSION_MESSAGES = 50_000;
 /** Default max raw JSON size accepted when loading a session snapshot (override via `SessionLimits`). */
 export const MAX_SESSION_JSON_BYTES = 100 * 1024 * 1024;
 
+// A SessionLoadError-named Error with the SDK prefix; in: validateSessionData, out: the error.
 function sessionLoadError(message: string): Error {
   const e = new Error(`[Agent Accelerator] Invalid session: ${message}`);
   e.name = "SessionLoadError";
@@ -1143,9 +1156,9 @@ function sessionLoadError(message: string): Error {
 }
 
 /**
- * Manual Zod-like validation for session snapshots (Q-10, no new deps).
+ * Manual Zod-like validation for session snapshots (no new deps).
  * Checks `version===1`, string `sessionId`, array `messages`, and oversize
- * (>5000 messages or >10MB JSON). Throws a `SessionLoadError`-named Error
+ * (more than `MAX_SESSION_MESSAGES` = 50,000 messages or `MAX_SESSION_JSON_BYTES` = 100 MB of JSON). Throws a `SessionLoadError`-named Error
  * on failure; returns the typed session on success.
  */
 export function validateSessionData(data: unknown): PersistedAgentSession {
@@ -1178,12 +1191,12 @@ export function validateSessionData(data: unknown): PersistedAgentSession {
 }
 
 // ---------------------------------------------------------------------------
-// Q-34: context-window lookup without the legacy 1M fallback.
+// Context-window lookup without the legacy 1M fallback.
 // ---------------------------------------------------------------------------
 
 /**
- * Returns the catalog context window for a model, or `undefined` when unknown
- * (Q-34). Prefer this over `getSessionContextWindow` for new code.
+ * Returns the catalog context window for a model, or `undefined` when unknown.
+ * Prefer this over `getSessionContextWindow` for new code.
  */
 export function getSessionContextWindowOrUndefined(modelStr: string): number | undefined {
   try {
@@ -1197,7 +1210,7 @@ export function getSessionContextWindowOrUndefined(modelStr: string): number | u
 }
 
 // ---------------------------------------------------------------------------
-// Q-41: telemetry bus lives in `../telemetry.ts` (dependency-free, so low-level
+// Telemetry bus lives in `../telemetry.ts` (dependency-free, so low-level
 // modules such as the catalog cache and event stream can emit without import
 // cycles). Re-exported here for backward compatibility.
 // ---------------------------------------------------------------------------
@@ -1205,7 +1218,7 @@ import { telemetryBus } from "../telemetry.ts";
 export { telemetryBus };
 export type { TelemetryEvent, TelemetryListener } from "../telemetry.ts";
 
-/** Reports a usage/cost anomaly via the global hook + telemetry bus (Q-35). Never logs. */
+/** Reports a usage/cost anomaly via the global hook + telemetry bus. Never logs. */
 export function reportUsageAnomaly(detail: { type: string; [k: string]: unknown }): void {
   try {
     (globalThis as unknown as { __agentAccelAnomaly?: (d: unknown) => void }).__agentAccelAnomaly?.(detail);
@@ -1220,10 +1233,10 @@ export function reportUsageAnomaly(detail: { type: string; [k: string]: unknown
 }
 
 // ---------------------------------------------------------------------------
-// Q-35: canonical usage invariants.
+// Canonical usage invariants.
 // ---------------------------------------------------------------------------
 /**
- * Canonical usage invariants (provider-agnostic, Q-35):
+ * Canonical usage invariants (provider-agnostic):
  * - all token counts are finite integers >= 0;
  * - `cachedTokens` / `cacheReadTokens` are a SUBSET of `inputTokens`
  *   (cache hits cannot exceed input; aggregates clamp — see `accumulateUsage`
@@ -1274,13 +1287,13 @@ export function assertUsageInvariants(usage: TokenUsage): void {
 }
 
 // ---------------------------------------------------------------------------
-// Q-36: one cost model — integer micro-USD accumulation.
+// One cost model — integer micro-USD accumulation.
 // ---------------------------------------------------------------------------
 
-/** Where a priced cost came from (Q-36). Unknown stays unknown, never 0. */
+/** Where a priced cost came from. Unknown stays unknown, never 0. */
 export type CostSource = "provider" | "catalog" | "unknown";
 
-/** Integer micro-USD breakdown behind a priced cost (Q-36). */
+/** Integer micro-USD breakdown behind a priced cost. */
 export interface CostBreakdown {
   inputMicroUSD: number;
   outputMicroUSD: number;
@@ -1302,7 +1315,7 @@ export type PricedCost = NonNullable<TokenUsage["cost"]> & {
 };
 
 /**
- * Service-tier price multipliers (Q-36). Aligned with pi
+ * Service-tier price multipliers. Aligned with pi
  * (`api/openai-responses.ts:387`): `flex` trades latency for ~0.5x price,
  * `priority`/`fast` reserve capacity at ~2x (`2.5x` for `gpt-5.5`).
  * Standard/default is 1.0. Estimates because vendors do not publish exact
@@ -1314,6 +1327,7 @@ const SERVICE_TIER_MULTIPLIERS: Record<string, number> = {
   fast: 2,
 };
 
+// Price multiplier for a service tier (flex 0.5, priority 2, 2.5 for gpt-5.5; estimates); in: priceUsage, out: the multiplier and tier name.
 function serviceTierMultiplier(serviceTier?: string, modelId?: string): { multiplier: number; tier?: string } {
   if (!serviceTier) return { multiplier: 1 };
   const lower = serviceTier.toLowerCase();
@@ -1327,12 +1341,13 @@ function serviceTierMultiplier(serviceTier?: string, modelId?: string): { multip
   return m !== undefined ? { multiplier: m, tier: serviceTier } : { multiplier: 1, tier: serviceTier };
 }
 
+// Integer micro-USD to dollars; in: priceUsage, out: a number.
 function toDollars(microUSD: number): number {
   return microUSD / 1_000_000;
 }
 
 /**
- * Resolves effective per-1M pricing for a usage snapshot (Q-36). When
+ * Resolves effective per-1M pricing for a usage snapshot. When
  * `usage.inputTokens > 200_000` and the catalog carries `cost.tiers` or
  * `cost.context_over_200k`, the over-200k tier prices apply; otherwise base
  * `pricing.*` (falling back to legacy `cost.*`) applies.
@@ -1389,7 +1404,7 @@ function resolveEffectivePricing(
 }
 
 /**
- * Prices one usage snapshot with integer micro-USD accumulation (Q-36).
+ * Prices one usage snapshot with integer micro-USD accumulation.
  *
  * - A provider-reported `usage.cost.totalCost` (a number, 0 included: free or cached) wins (source `provider`).
  * - Else catalog pricing via `resolveEffectivePricing` (source `catalog`).
@@ -1483,7 +1498,7 @@ export function priceUsage(
 }
 
 /**
- * Computes and attaches catalog pricing to a usage snapshot (Q-36).
+ * Computes and attaches catalog pricing to a usage snapshot.
  * Keeps provider-reported costs untouched; returns the cost (or undefined
  * when unknown). Never fabricates a 0 object for unknown pricing.
  */

package/src/session/usage.ts

@@ -39,6 +39,7 @@ export function emptyUsage(): UsageTotals {
   };
 }
 
+// A finite whole number >= 0, else 0; in: the usage maths and readUsage, out: a safe count.
 const count = (n: unknown): number => (typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : 0);
 
 /** A model reference (string or catalog spec) as a plain string for a report line. */

package/src/streaming/architecture.md

@@ -0,0 +1,13 @@
+# src/streaming/
+
+| File | What it is |
+| :-- | :-- |
+| `event-stream.ts` | `AssistantMessageEventStream`: an async-iterable event stream with listeners (`on`/`off`), a `result()` promise, `cancel()` and bounded buffering. Providers produce it; the loop and `Agent` consume it. |
+| `sse-parser.ts` | `SSEParser`: incremental Server-Sent Events framing that survives events split across network chunks. Internal (not exported from the barrel). |
+
+## Invariants
+- The buffer holds at most 1000 events (oldest dropped, reported on the bus); an event over 1 MB is dropped. `{ buffer: false }` keeps none (for a caller that only wants `result()`).
+- `end()` without a response fails the stream instead of leaving `result()` hanging.
+- A cancel is recognised by the `AbortError` name only, never by message text.
+- Breaking out of `for await` cancels the stream, which tears down the HTTP request.
+- A throwing listener never breaks the stream; the first error is kept in `getListenerError()`.

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,11 +25,12 @@ 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.
 function approxEventBytes(event: StreamEvent): number {
   let n = 0;
   if (typeof event.delta === "string") n += event.delta.length;
@@ -39,9 +40,10 @@ function approxEventBytes(event: StreamEvent): number {
   return n;
 }
 
+// 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);
@@ -66,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;
@@ -105,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;
   }
@@ -114,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 });
@@ -130,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);
@@ -154,13 +156,14 @@ 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);
     }
   }
 
+  // Calls the listeners of the event's type and `*`, remembering the first listener error instead of throwing; in: push, out: those callbacks.
   private deliverToListeners(event: StreamEvent): void {
     const specificListeners = this.listeners.get(event.type);
     if (specificListeners) {
@@ -187,10 +190,11 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     }
   }
 
+  // Buffers an event for the iterator, dropping the oldest non-error events beyond the cap; in: push, out: this.queue.
   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") {
@@ -209,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"));
@@ -289,6 +293,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     return this.finalResultPromise;
   }
 
+  // Iterator over the stream: buffered events first, then waits for new ones; breaking out cancels the stream and a failed stream rejects after delivering its error event; in: for-await consumers, out: StreamEvents.
   [Symbol.asyncIterator](): AsyncIterator<StreamEvent> {
     let iteratorDone = false;
     return {

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;
@@ -30,6 +30,7 @@ interface TelemetryBus {
   clear(): void;
 }
 
+/** The in-process telemetry bus: listeners subscribe with `onEvent`; emission never throws and does nothing without listeners. */
 export const telemetryBus: TelemetryBus = (() => {
   const listeners = new Set<TelemetryListener>();
   const deliver = (event: TelemetryEvent): void => {

package/src/tools/architecture.md

@@ -0,0 +1,19 @@
+# src/tools/
+
+Defining tools and running them.
+
+| File | What it is |
+| :-- | :-- |
+| `tool.ts` | `tool()` factory, name validation, `toStandardToolDeclarations`, option normalizers. |
+| `schema.ts` | Zod to JSON Schema, `$ref` resolution, `stripSchemaForGoogle`. |
+| `executor.ts` | `executeToolCalls`: validation, concurrency (8 global + per-tool), attempts, timeout, result cap, error scrubbing, `ctx.stop`, `tool.*` events, per-call logs. |
+| `subagent-result.ts` | The private-Symbol brand that marks a result as made by the SDK's delegation tools. |
+
+## Invariants
+- Tool names match `^[a-zA-Z0-9_-]{1,64}$` and must not collide after normalization (checked in the `Agent` constructor).
+- One attempt by default; only idempotent tools retry transient failures; the timeout is best effort (`ctx.signal` is cooperative), and an uncooperative tool no longer holds an aborted run.
+- Results are capped by serialized size (default 20000 chars); nested error stacks and absolute paths are scrubbed. The telemetry bus gets full detail, the model gets the scrubbed text.
+- A truncated call (`{ __truncated_raw }`) never executes.
+- `ctx.stop(reason)` throws a private signal; the batch finishes, then the loop ends the run as `stopped`.
+- Only branded envelopes get their `_subagentMetadata` trusted; the executor passes them through untouched.
+- Failures return `Error executing <name>: <msg>` plus a JSON block (attempts, timedOut, last progress, hint).