agent-accelerator 0.5.6 → 0.5.8

package/src/agent/loop.ts

@@ -25,6 +25,7 @@ import { enforceFileAccess } from "../utils/safe-io.ts";
 import { isSubagentResult, normalizeSubagentMetadata } from "../tools/subagent-result.ts";
 import { BudgetExceededError } from "../types/errors.ts";
 import { applyCaptureRaw, type CaptureRawMode } from "../utils/raw-capture.ts";
+import { previewPrompt } from "../utils/session.ts";
 import { noteProviderTurn, normalizeStructuredOutput, parseStructuredOutput } from "../providers.ts";
 
 /** One mid-session steer request buffered while a run is active. */
@@ -99,20 +100,6 @@ export interface AgentLoopConfig {
   output?: unknown;
 }
 
-/** Short preview for `steer_injected` / `queued` event payloads (bounded, display-only). */
-function steerPreview(prompt: string | ContentPart[]): string {
-  if (typeof prompt === "string") return prompt.slice(0, 500);
-  try {
-    const texts = prompt
-      .filter((p) => (p as { type?: unknown }).type === "text")
-      .map((p) => (p as { text?: string }).text ?? "")
-      .join("\n");
-    return (texts || "[multipart]").slice(0, 500);
-  } catch {
-    return "[multipart]";
-  }
-}
-
 /**
  * Drains pending steer entries into the conversation as new user messages.
  * Returns display previews for events/telemetry. Never throws: invalid
@@ -133,7 +120,7 @@ function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[]): string[]
         else prompt = [{ type: "text", text: prefix } as ContentPart, ...prompt];
       }
       context.addUserMessage(prompt);
-      injected.push(steerPreview(entry.prompt));
+      injected.push(previewPrompt(entry.prompt));
     } catch {
       continue;
     }
@@ -141,6 +128,7 @@ function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[]): string[]
   return injected;
 }
 
+// Reports one finished turn to the caller's onTurn hook (ids only), never throwing; in: both loops, out: AgentRunOptions.onTurn.
 function emitTurn(
   runOptions: AgentRunOptions | undefined,
   turn: { turns: number; text?: string; thinking?: string; toolCalls?: ToolCallRecord[]; toolResults?: ToolResultRecord[] }
@@ -183,6 +171,7 @@ function shouldRollbackOnFailure(
   return !toolsExecuted;
 }
 
+// Calls the persistence checkpoint hook, never throwing; in: both loops after each step, out: Agent.persistNow.
 function emitProgress(config: { onProgress?: () => void }): void {
   try { config.onProgress?.(); } catch {}
 }
@@ -191,6 +180,7 @@ function emitProgress(config: { onProgress?: () => void }): void {
 // Structured outputs (canonical output wiring for the loop).
 // ---------------------------------------------------------------------------
 
+// Normalizes the structured-output option once per run (raw value + provider spec); in: AgentLoopConfig.output, out: the final-answer validation.
 function resolveLoopOutput(config: AgentLoopConfig): { raw: unknown; spec: import("../types/model.ts").StructuredOutputSpec | undefined } {
   const raw = (config as { output?: unknown }).output;
   const fromOptions = (config.options as { output?: import("../types/model.ts").StructuredOutputSpec } | undefined)?.output;
@@ -204,6 +194,7 @@ function resolveLoopOutput(config: AgentLoopConfig): { raw: unknown; spec: impor
   return { raw: undefined, spec: undefined };
 }
 
+// Validates the final text against the structured-output option, throwing ValidationError on mismatch; in: the last model text, out: AgentResponse.parsed.
 function parseFinalStructuredOutput(text: string, raw: unknown, spec: import("../types/model.ts").StructuredOutputSpec | undefined): unknown | undefined {
   if (raw === undefined && spec === undefined) return undefined;
   // Strict-fail when opted in: invalid JSON/schema throws ValidationError.
@@ -232,7 +223,7 @@ function normalizeMaxTurns(value?: number): number {
 function warnMaxTurnsHit(agentName: string | undefined, maxTurns: number, pendingTools: string[]): void {
   const who = agentName ? `"${agentName}"` : "Agent";
   const tools = pendingTools.length > 0 ? ` Pending tool calls dropped: ${pendingTools.join(", ")}.` : "";
-  // Q-41: no console.* in library code — route via the telemetry bus
+  // No console.* in library code — route via the telemetry bus
   // (default no-op; CLIs attach a pretty logger via telemetryBus.onEvent).
   try {
     telemetryBus.emitWarning(
@@ -246,11 +237,11 @@ function warnMaxTurnsHit(agentName: string | undefined, maxTurns: number, pendin
 }
 
 // ---------------------------------------------------------------------------
-// Q-19: tool-call/result pairing repair.
+// Tool-call/result pairing repair.
 // ---------------------------------------------------------------------------
 
 /**
- * Repairs tool call/result pairing before each provider request (Q-19).
+ * Repairs tool call/result pairing before each provider request.
  *
  * Providers reject a `tool_result` without its `tool_call`, a `tool_call`
  * without its result, AND (Chat-Completions style APIs) results that are not
@@ -315,7 +306,7 @@ export function ensureToolPairing(context: AgentContext): void {
 }
 
 // ---------------------------------------------------------------------------
-// Q-21/Q-22: abort + limits helpers.
+// Abort + limits helpers.
 // ---------------------------------------------------------------------------
 
 export interface LoopLimits {
@@ -328,7 +319,7 @@ export interface LoopLimits {
   streamIdleTimeoutMs: number;
 }
 
-/** Resolves `(config as any).limits` with Q-22 defaults (timeouts tolerate reasoning). */
+/** Resolves `(config as any).limits` with defaults (timeouts tolerate reasoning). */
 function resolveLoopLimits(config: AgentLoopConfig, fallbackMaxTurns: number): LoopLimits & { maxTurns: number; deadlineMs: number; maxToolCallsPerRun: number; maxTotalTokens: number } {
   const raw = ((config as unknown as { limits?: Record<string, unknown> }).limits ?? {}) as Record<string, unknown>;
   const num = (v: unknown): number | undefined =>
@@ -350,6 +341,7 @@ function resolveLoopLimits(config: AgentLoopConfig, fallbackMaxTurns: number): L
   return { maxTurns, deadlineMs, maxToolCallsPerRun, maxTotalTokens, requestTimeoutMs, firstByteTimeoutMs, streamIdleTimeoutMs };
 }
 
+// The session id a run's provider calls use (run override, else agent default); in: AgentLoopConfig, out: rollback and routing.
 function loopSessionId(config: AgentLoopConfig): string | undefined {
   try {
     return (
@@ -359,6 +351,7 @@ function loopSessionId(config: AgentLoopConfig): string | undefined {
   } catch { return undefined; }
 }
 
+// Builds an AbortError that carries the run's partial progress; in: an abort reason + partial usage, out: the error the run rejects with.
 function makeAbortError(
   partial: { usage: TokenUsage; turns: number; text?: string },
   reason?: unknown
@@ -373,6 +366,7 @@ function makeAbortError(
   return base;
 }
 
+// Throws the run's AbortError as soon as its signal is aborted; in: loop checkpoints, out: nothing or a thrown abort.
 function throwIfAborted(
   signal: AbortSignal | undefined,
   partial: { usage: TokenUsage; turns: number; text?: string }
@@ -382,6 +376,7 @@ function throwIfAborted(
   }
 }
 
+// Throws BudgetExceededError when the run's tokens pass limits.maxTotalTokens; in: both loops after usage changes, out: nothing or a thrown error.
 function checkTokenLimit(usage: TokenUsage, maxTotalTokens: number): void {
   if (Number.isFinite(maxTotalTokens) && usage.totalTokens > maxTotalTokens) {
     throw new BudgetExceededError(
@@ -391,12 +386,14 @@ function checkTokenLimit(usage: TokenUsage, maxTotalTokens: number): void {
   }
 }
 
+// Throws when the run has been going longer than limits.deadlineMs; in: both loops each turn, out: nothing or a thrown error.
 function checkDeadline(startTime: number, deadlineMs: number): void {
   if (Number.isFinite(deadlineMs) && deadlineMs !== Infinity && Date.now() - startTime > deadlineMs) {
     throw new Error(`[Agent Accelerator] Run deadline exceeded after ${deadlineMs}ms.`);
   }
 }
 
+// Races one provider call against the request timeout (a TimeoutError), clearing its timer either way; in: runAgentLoop, out: the call's result.
 async function generateWithTimeout<T>(task: () => Promise<T>, timeoutMs: number): Promise<T> {
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs === Infinity) return task();
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -439,7 +436,7 @@ export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec, serv
 }
 
 // ---------------------------------------------------------------------------
-// Q-35: canonical usage accumulation (pure w.r.t. source).
+// Canonical usage accumulation (pure w.r.t. source).
 // Invariants (see assertUsageInvariants in session/store.ts):
 // - token counts are finite integers >= 0;
 // - cachedTokens/cacheReadTokens are a SUBSET of inputTokens (clamped below
@@ -447,7 +444,7 @@ export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec, serv
 // - thinkingTokens is a SUBSET of outputTokens when both are reported
 //   (reasoning is generated output; enforced in the test helper, documented
 //   here because providers vary on which side they omit).
-// This function never mutates `source` (Q-35): the priced cost is cloned
+// This function never mutates `source`: the priced cost is cloned
 // into a local before folding into the target.
 // ---------------------------------------------------------------------------
 export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec, serviceTier?: string): void {
@@ -468,7 +465,7 @@ export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: M
   target.cachedTokens = Math.min(preCached, target.inputTokens);
   target.cacheReadTokens = Math.min(preRead, target.inputTokens);
   if ((target.cachedTokens ?? 0) < preCached || (target.cacheReadTokens ?? 0) < preRead) {
-    // Q-35: no console — report via the anomaly hook + telemetry bus.
+    // No console — report via the anomaly hook + telemetry bus.
     reportUsageAnomaly({
       type: "cache_clamp",
       inputTokens: target.inputTokens,
@@ -478,7 +475,7 @@ export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: M
   }
 
   const priced = computeCostFromPricing(source, spec, serviceTier);
-  // Q-35: pure — read `source` only; never assign back to `source.cost`.
+  // Pure — read `source` only; never assign back to `source.cost`.
   // Clone the priced cost so later target folds cannot alias source state.
   const sourceCost = priced ? { ...priced } : undefined;
 
@@ -493,6 +490,7 @@ export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: M
   }
 }
 
+// Turns a tool result into what the model sees: a branded delegation envelope becomes its text and yields validated worker metadata, anything else passes through; in: executed results, out: history + usage roll-up.
 function sanitizeToolResult(r: ToolResultRecord): { sanitized: ToolResultRecord; metas: SubAgentExecutionMetadata[] } {
   // Only SDK-branded delegation envelopes are trusted. A plain object that
   // merely carries a `_subagentMetadata` key (e.g. scraped JSON) is ordinary
@@ -675,11 +673,11 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   const maxTurns = limits.maxTurns;
   // Structured outputs: normalize once (throws ValidationError for bad shapes).
   const loopOutput = resolveLoopOutput(config);
-  // Q-19: pre-run checkpoint for onFailure rollback.
+  // Pre-run checkpoint for onFailure rollback.
   const preRunCp = context.checkpoint();
   const sessionIdForRollback = loopSessionId(config);
 
-  // Q-37: partial-run state hoisted outside try so the catch block can attach
+  // Partial-run state hoisted outside try so the catch block can attach
   // {usage,cost,turns,toolCalls,toolResults,text} to ANY thrown error.
   const startTime = Date.now();
   const accumulatedUsage: TokenUsage = {
@@ -719,11 +717,11 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   }
 
   while (!stoppedByTool && turns < maxTurns) {
-    // Q-21: fail fast on abort (throws AbortError with partial).
+    // Fail fast on abort (throws AbortError with partial).
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: finalResult?.text });
     checkDeadline(startTime, limits.deadlineMs);
     config.enforceBudget?.();
-    // Q-19: repair orphan tool pairs before every request.
+    // Repair orphan tool pairs before every request.
     ensureToolPairing(context);
     if (config.fileAccess?.roots) await enforceFileAccess(context.messages, config.fileAccess.roots);
     turns++;
@@ -739,13 +737,13 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       toolChoice: toolChoiceForTurn(options?.toolChoice, turns),
       ...(loopOutput.spec ? { output: loopOutput.spec } : {}),
     };
-    // Q-22: per-request timeout pass-through (providers honor timeoutMs).
+    // Per-request timeout pass-through (providers honor timeoutMs).
     try {
       if (Number.isFinite(limits.requestTimeoutMs) && limits.requestTimeoutMs !== Infinity) {
         (providerOptions as unknown as { timeoutMs?: number }).timeoutMs = limits.requestTimeoutMs;
       }
     } catch {}
-    // Q-25-partial: google:{store:false} opt-out pass-through (provider
+    // google:{store:false} opt-out pass-through (provider
     // already respects body.store===false for chaining).
     try {
       const gStore =
@@ -786,8 +784,8 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       provider.id
     );
 
-    // Thinking is exposed via events/traces and onTurn. Promoting it to answer text is gated (Q-15,
-    // default OFF): without the opt-in the run returns the provider's empty text and finishReason.
+    // Thinking is exposed via events/traces and onTurn. Promoting it to answer text is gated (default
+    // OFF): without the opt-in the run returns the provider's empty text and finishReason.
     if ((!genResult.text || genResult.text.trim() === "") && (!genResult.toolCalls || genResult.toolCalls.length === 0) && genResult.thinking) {
       if (shouldPromoteThinkingToAnswer(config, runOptions)) {
         if (genResult.thinking.includes("</think>")) {
@@ -855,11 +853,11 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     }
 
     // Execute tool calls — always parallel (model-driven, bloatfree DX7)
-    // Q-21: check abort before tools (throws AbortError with partial).
+    // Check abort before tools (throws AbortError with partial).
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: genResult.text });
     emitProgress(config); // the calls are on record BEFORE they run, so a crash can finish them instead of forgetting them
     allToolCalls.push(...genResult.toolCalls);
-    // Q-22: per-run tool-call budget.
+    // Per-run tool-call budget.
     if (allToolCalls.length > limits.maxToolCallsPerRun) {
       throw new Error(
         `[Agent Accelerator] maxToolCallsPerRun exceeded (${allToolCalls.length} > ${limits.maxToolCallsPerRun}).`
@@ -903,7 +901,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     allToolResults.push(...sanitizedResults);
     context.addToolResults(sanitizedResults);
     checkTokenLimit(accumulatedUsage, limits.maxTotalTokens);
-    // Q-19: results are stored BEFORE the cancellation check so an abort
+    // Results are stored BEFORE the cancellation check so an abort
     // never drops executed tool work from history.
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: genResult.text });
     emitTurn(runOptions, {
@@ -928,7 +926,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     }
     emitProgress(config);
 
-    // Q-21: abort always throws AbortError with partial attached (never
+    // Abort always throws AbortError with partial attached (never
     // silently breaks).
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: finalResult?.text });
   }
@@ -965,7 +963,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     responseId: finalResult?.responseId,
     model: modelId,
     provider: provider.id,
-    // Q-04: canonical finish reason + raw vendor passthrough.
+    // Canonical finish reason + raw vendor passthrough.
     ...(stoppedByTool
       ? { finishReason: "stopped" as const, ...(finalResult?.finishReason ? { rawFinishReason: finalResult.finishReason } : {}) }
       : canonicalFinishReason(finalResult?.finishReason, truncatedByMaxTurns)),
@@ -974,7 +972,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     turns,
   });
   } catch (err) {
-    // Q-19: run-level onFailure rollback (default restores pre-run
+    // Run-level onFailure rollback (default restores pre-run
     // checkpoint; opt out with (config as any).onFailure === "keep").
     // Aborts are excluded so partial history survives interruption.
     const isAbort =
@@ -985,14 +983,14 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
         // why: rollback is best-effort — the original error takes precedence.
       }
     }
-    // Q-21: ensure aborts surface as AbortError with partial attached.
+    // Ensure aborts surface as AbortError with partial attached.
     if (isAbort && (err as { name?: string } | null)?.name !== "AbortError") {
       throw makeAbortError(
         { usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, turns: 0 },
         err
       );
     }
-    // Q-37: every failure carries its partial progress for observability.
+    // Every failure carries its partial progress for observability.
     try {
       (err as unknown as { partial?: unknown }).partial ??= {
         usage: accumulatedUsage,
@@ -1044,7 +1042,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
     }
   };
 
-  // Q-19/Q-22: per-run checkpoint + limits for the streaming loop.
+  // Per-run checkpoint + limits for the streaming loop.
   const streamPreCp = config.context.checkpoint();
   const streamSessionId = loopSessionId(config);
   const streamFallbackMax = normalizeMaxTurns((config as { maxTurns?: number }).maxTurns);
@@ -1052,7 +1050,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
   const streamStartTime = startTime;
 
   (async () => {
-    // Hoisted for catch-block partial reporting (Q-21/Q-37).
+    // Hoisted for catch-block partial reporting.
     let accumulatedUsage: TokenUsage = {
       inputTokens: 0,
       outputTokens: 0,
@@ -1064,7 +1062,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
     };
     let lastResponse: AgentResponse | null = null;
     let turns = 0;
-    // Q-37: tool progress hoisted so failures carry toolCalls/toolResults.
+    // Tool progress hoisted so failures carry toolCalls/toolResults.
     const allToolCalls: ToolCallRecord[] = [];
     const allToolResults: ToolResultRecord[] = [];
     const allSubagents: SubAgentExecutionMetadata[] = [];
@@ -1120,7 +1118,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         thinkingTokens: 0,
       };
 
-      // Q-37: allToolCalls/allToolResults/allSubagents are hoisted above (fresh
+      // allToolCalls/allToolResults/allSubagents are hoisted above (fresh
       // per stream run); just reset turn counters here.
       lastResponse = null;
       turns = 0;
@@ -1178,7 +1176,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         );
         currentInner = innerStream as AssistantMessageEventStream;
 
-        // Q-22: first-byte + idle timeouts around SSE (tolerate reasoning).
+        // First-byte + idle timeouts around SSE (tolerate reasoning).
         // Implemented as races on the inner iterator so a hung provider
         // surfaces as TimeoutError instead of hanging the run forever.
         {
@@ -1240,7 +1238,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         );
 
         // Thinking stays on events/traces + onTurn (default exposed). Promoting
-        // it to answer text is gated (Q-15, default OFF): without the opt-in
+        // it to answer text is gated (default OFF): without the opt-in
         // the turn keeps the provider's empty text and finishReason.
         if ((!turnResponse.text || turnResponse.text.trim() === "") && (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0) && turnResponse.thinking) {
           if (shouldPromoteThinkingToAnswer(config, runOptions)) {
@@ -1317,7 +1315,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
             `[Agent Accelerator] maxToolCallsPerRun exceeded (${allToolCalls.length} > ${streamLimits.maxToolCallsPerRun}).`
           );
         }
-        // Q-40: typed tool lifecycle for streaming consumers.
+        // Typed tool lifecycle for streaming consumers.
         try {
           outerStream.push({ type: "tool_start", toolCalls: turnResponse.toolCalls });
         } catch {
@@ -1381,14 +1379,14 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
             toolResult: res,
           });
         }
-        // Q-40: close the tool lifecycle opened by `tool_start` above.
+        // Close the tool lifecycle opened by `tool_start` above.
         try {
           outerStream.push({ type: "tool_end", toolResults: sanitizedResults });
         } catch {
           // why: stream push never throws, but guard anyway to protect the loop.
         }
 
-        // Q-19: store tool results BEFORE the cancellation check.
+        // Store tool results BEFORE the cancellation check.
         allToolResults.push(...sanitizedResults);
         context.addToolResults(sanitizedResults);
         throwIfCancelled({ usage: accumulatedUsage, turns, text: turnResponse.text });
@@ -1465,7 +1463,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         responseId: lastResponse?.responseId,
         model: modelId,
         provider: provider.id,
-        // Q-04: canonical finish reason + raw vendor passthrough.
+        // Canonical finish reason + raw vendor passthrough.
         ...truncatedFinish,
         durationMs: Date.now() - startTime,
         raw: applyCaptureRaw(lastResponse?.raw, config.captureRaw) as ProviderRawData,
@@ -1488,7 +1486,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         linked.signal.aborted ||
         outerStream.isCancelled() ||
         (raw as any)?.name === "AbortError";
-      // Q-19: streaming onFailure rollback (same policy as runAgentLoop;
+      // Streaming onFailure rollback (same policy as runAgentLoop;
       // aborts excluded so partial history survives).
       try {
         if (shouldRollbackOnFailure(config.onFailure, isAbort, toolsExecuted)) {
@@ -1499,7 +1497,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
       } catch {
         // why: rollback policy itself must never mask the original error.
       }
-      // Q-37: every failure carries its partial progress for observability.
+      // Every failure carries its partial progress for observability.
       const partial = {
         usage: accumulatedUsage,
         cost: accumulatedUsage.cost,
@@ -1508,7 +1506,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         toolResults: allToolResults,
         text: lastResponse?.text,
       };
-      // Q-21: aborts always surface as AbortError with partial attached.
+      // Aborts always surface as AbortError with partial attached.
       if (isAbort) {
         const abortErr =
           raw.name === "AbortError" ? raw : makeAbortError(partial, raw);
@@ -1539,12 +1537,12 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
 }
 
 // ---------------------------------------------------------------------------
-// Q-15: thinking-promotion policy + Q-04 canonical finish helper.
+// Thinking-promotion policy + canonical finish helper.
 // (Appended here to avoid conflicts with other loop sections.)
 // ---------------------------------------------------------------------------
 
 /**
- * Whether an empty-text turn may promote `thinking` to answer `text` (Q-15).
+ * Whether an empty-text turn may promote `thinking` to answer `text`.
  * Default false: the run returns the provider's empty text with its
  * finishReason instead of fabricating an answer from reasoning. Opt in via
  * `(runOptions as any).thinkingAsAnswerFallback === true` or
@@ -1569,7 +1567,7 @@ export function shouldPromoteThinkingToAnswer(config?: unknown, runOptions?: unk
 }
 
 /**
- * Canonicalizes a provider finish reason for AgentResponse (Q-04).
+ * Canonicalizes a provider finish reason for AgentResponse.
  * When `truncated` (maxTurns exhausted with pending tools), forces
  * `"max_turns"` and preserves the provider's reason in `rawFinishReason`.
  * Otherwise delegates to `normalizeFinishReason` (unknown vendor strings map

package/src/agent/subagent.ts

@@ -9,7 +9,7 @@ import { getModel, getSubModel } from "../utils/env.ts";
 export interface SubAgentConfig extends AgentConfig {}
 
 /**
- * Canonical env-based construction (Q-56): builds an `Agent` reading
+ * Canonical env-based construction: builds an `Agent` reading
  * `MODEL`/`SUB_AGENT_MODEL` only for the fields the caller omits, via
  * `getModel()`/`getSubModel()`. Explicit config always wins; constructing an
  * `Agent` with an explicit `model` reads no env for routing. The static
@@ -36,12 +36,12 @@ export function agentFromEnv(
  * It inherits 100% of the capabilities of Agent, defaults to SUB_AGENT_MODEL,
  * and provides .asTool() and .toTool() for seamless registration into parent agents.
  *
- * Model fallback chain (Q-56, canonical): explicit `config.model` ??
+ * Model fallback chain (canonical): explicit `config.model` ??
  * `SUB_AGENT_MODEL` (`getSubModel()`) ?? `MODEL` (`getModel()`). Missing
  * everything throws. Constructing any `Agent`/`SubAgent` with an explicit
  * `model` reads no env for routing.
  *
- * Q-47 decomposition boundary: this class stays a thin wrapper. The run/stream
+ * Decomposition boundary: this class stays a thin wrapper. The run/stream
  * loops live in `agent.ts`/`loop.ts`, spawning in `delegation.ts`
  * (`agentToTool`), and model parsing in `utils/session.ts` (`parseModelRef`).
  * No loop, transport, or formatting logic is duplicated here.
@@ -104,7 +104,7 @@ export class SubAgent extends Agent {
   }
 }
 
-// Q-56: `Agent.fromEnv()` static without touching `agent.ts` (owned by
+// `Agent.fromEnv()` static without touching `agent.ts` (owned by
 // another lane). Wired at module load; typed via the declaration below so
 // `Agent.fromEnv({...})` typechecks wherever this module is imported.
 declare module "./agent.ts" {

package/src/agent/worker.ts

@@ -3,12 +3,9 @@ import type { SubAgentStep } from "../types/response.ts";
 import type { AgentConfig } from "../types/agent.ts";
 import type { Agent } from "./agent.ts";
 import { normalizeToolName } from "../tools/executor.ts";
-import { escapeXml } from "../utils/serialization.ts";
 import { getModel, getSubModel } from "../utils/env.ts";
 import { resolveModel } from "../providers/registry.ts";
 
-export { escapeXml };
-
 /** Minimal live-trace shape shared by fixed + dynamic workers (structural subset of `SubAgentTrace`). */
 export interface LiveWorkerTrace {
   trackingId: string;
@@ -200,6 +197,7 @@ export function grantWorkerTools(
   return grantedTools;
 }
 
+// The provider id a model string resolves to, or undefined when it cannot be resolved; in: resolveWorkerCredentials, out: the provider match check.
 function providerOf(modelStr: string | unknown | undefined): string | undefined {
   if (!modelStr) return undefined;
   try {

package/src/architecture.md

@@ -0,0 +1,28 @@
+# src/
+
+The whole SDK. `index.ts` is the only public entry (`main`/`module`/`types`); everything else is reached through it.
+
+| File / folder | What it is |
+| :-- | :-- |
+| `index.ts` | The public barrel. Adding or removing an export is a public API change. |
+| `telemetry.ts` | The in-process event bus (`telemetryBus`). Imports nothing from the SDK, so any module may use it. |
+| `telemetry-file.ts` | Opt-in NDJSON sink for the bus: a persisted session's events go to `<session folder>/telemetry.ndjson`, the rest to `<home>/telemetry/<date>.ndjson`; never outside a home. |
+| `update-models.ts` | CLI behind `bun run update-models` (refreshes the model catalog cache). |
+| `providers.ts` | Provider-agnostic mappers (thinking, cache, tool choice, structured output, generation params). No HTTP. |
+| `agent/` | `Agent`, the model-to-tools loop, workers, delegation. |
+| `providers/` | One adapter per wire (Google, OpenAI, OpenRouter, OpenAI-compatible), the registry, shared helpers. |
+| `models/` | The model catalog (models.dev) and its cache. |
+| `tools/` | `tool()`, schemas, the executor. |
+| `streaming/` | The event stream and the SSE parser. |
+| `session/` | Persistence (snapshot + journal), usage accounting, tool logs. |
+| `scheduler/` | Scheduled actions. |
+| `types/` | Shared contracts (no logic except small helpers). |
+| `utils/` | Small shared helpers (durable writes, home, env, media, retry, safe I/O). |
+
+## Rules for every file here
+- Imports use `.ts` extensions; type-only imports use `import type`.
+- No `console.*`: warnings and traces go to `telemetryBus` (exceptions: the `update-models.ts` CLI and one compat `console.warn` in `providers.ts`).
+- All state is written under the one home folder (`utils/home.ts`). Files are replaced through `utils/durable.ts`; the append-only ones are the session journal and tool logs (fsynced per line) and the opt-in telemetry file (not fsynced).
+- Provider differences never leave `providers/` and `providers.ts`.
+- Every function has one comment line above it (how it works, where input comes from, where output goes).
+- Change a public option, export, env var or telemetry code: update `README.md` and `docs/` in the same change.