agent-accelerator 0.5.7 → 0.5.9

package/src/agent/loop.ts

@@ -23,7 +23,7 @@ import {
 import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } from "../models/catalog.ts";
 import { enforceFileAccess } from "../utils/safe-io.ts";
 import { isSubagentResult, normalizeSubagentMetadata } from "../tools/subagent-result.ts";
-import { BudgetExceededError } from "../types/errors.ts";
+import { BudgetExceededError, TimeoutError } 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";
@@ -223,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(
@@ -237,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
@@ -306,7 +306,7 @@ export function ensureToolPairing(context: AgentContext): void {
 }
 
 // ---------------------------------------------------------------------------
-// Q-21/Q-22: abort + limits helpers.
+// Abort + limits helpers.
 // ---------------------------------------------------------------------------
 
 export interface LoopLimits {
@@ -319,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 =>
@@ -389,7 +389,7 @@ 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.`);
+    throw new BudgetExceededError(`[Agent Accelerator] Run deadline exceeded after ${deadlineMs}ms.`);
   }
 }
 
@@ -400,9 +400,7 @@ async function generateWithTimeout<T>(task: () => Promise<T>, timeoutMs: number)
   try {
     const timeoutP = new Promise<never>((_, reject) => {
       timer = setTimeout(() => {
-        const e = new Error(`[Agent Accelerator] Request timed out after ${timeoutMs}ms.`);
-        e.name = "TimeoutError";
-        reject(e);
+        reject(new TimeoutError(`[Agent Accelerator] Request timed out after ${timeoutMs}ms.`));
       }, timeoutMs);
       try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
     });
@@ -436,7 +434,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
@@ -444,7 +442,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 {
@@ -465,7 +463,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,
@@ -475,7 +473,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;
 
@@ -673,11 +671,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 = {
@@ -717,11 +715,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++;
@@ -737,13 +735,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 =
@@ -784,8 +782,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>")) {
@@ -853,13 +851,13 @@ 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(
+      throw new BudgetExceededError(
         `[Agent Accelerator] maxToolCallsPerRun exceeded (${allToolCalls.length} > ${limits.maxToolCallsPerRun}).`
       );
     }
@@ -901,7 +899,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, {
@@ -926,7 +924,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 });
   }
@@ -963,7 +961,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)),
@@ -972,7 +970,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 =
@@ -983,14 +981,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,
@@ -998,6 +996,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
         turns,
         toolCalls: allToolCalls,
         toolResults: allToolResults,
+        subagents: allSubagents,
         text: finalResult?.text,
       };
     } catch {
@@ -1042,7 +1041,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);
@@ -1050,7 +1049,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,
@@ -1062,7 +1061,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[] = [];
@@ -1118,7 +1117,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;
@@ -1176,7 +1175,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.
         {
@@ -1191,11 +1190,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
               Number.isFinite(waitMs) && waitMs !== Infinity && waitMs > 0
                 ? new Promise<never>((_, reject) => {
                     timer = setTimeout(() => {
-                      const e = new Error(
-                        `[Agent Accelerator] Stream ${first ? "first-byte" : "idle"} timed out after ${waitMs}ms.`
-                      );
-                      e.name = "TimeoutError";
-                      reject(e);
+                      reject(new TimeoutError(`[Agent Accelerator] Stream ${first ? "first-byte" : "idle"} timed out after ${waitMs}ms.`));
                     }, waitMs);
                     try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
                   })
@@ -1238,7 +1233,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)) {
@@ -1311,11 +1306,11 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         emitProgress(config); // the calls are on record BEFORE they run, so a crash can finish them instead of forgetting them
         allToolCalls.push(...turnResponse.toolCalls);
         if (allToolCalls.length > streamLimits.maxToolCallsPerRun) {
-          throw new Error(
+          throw new BudgetExceededError(
             `[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 {
@@ -1379,14 +1374,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 });
@@ -1444,6 +1439,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
             turns,
             toolCalls: allToolCalls,
             toolResults: allToolResults,
+            subagents: allSubagents,
             text: lastResponse?.text,
           }; } catch {}
           outerStream.fail(raw);
@@ -1463,7 +1459,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,
@@ -1486,7 +1482,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)) {
@@ -1497,16 +1493,17 @@ 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,
         turns,
         toolCalls: allToolCalls,
         toolResults: allToolResults,
+        subagents: allSubagents,
         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);
@@ -1537,12 +1534,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
@@ -1567,7 +1564,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

@@ -5,6 +5,7 @@ import type { Agent } from "./agent.ts";
 import { normalizeToolName } from "../tools/executor.ts";
 import { getModel, getSubModel } from "../utils/env.ts";
 import { resolveModel } from "../providers/registry.ts";
+import { ConfigError } from "../types/errors.ts";
 
 /** Minimal live-trace shape shared by fixed + dynamic workers (structural subset of `SubAgentTrace`). */
 export interface LiveWorkerTrace {
@@ -134,7 +135,7 @@ export function resolveDynamicModelInput(
 export function resolveSubAgentModel(config: { name?: string; model?: AgentConfig["model"] }): NonNullable<AgentConfig["model"]> {
   const resolvedModel = config.model ?? getSubModel() ?? getModel();
   if (!resolvedModel) {
-    throw new Error(
+    throw new ConfigError(
       `[Agent Accelerator] SubAgent '${config.name || "subagent"}' requires a model. ` +
         `Specify 'model' in SubAgent config, or set SUB_AGENT_MODEL or MODEL in environment variables.`
     );

package/src/architecture.md

@@ -6,7 +6,7 @@ The whole SDK. `index.ts` is the only public entry (`main`/`module`/`types`); ev
 | :-- | :-- |
 | `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 (`<home>/telemetry/<date>.ndjson`). |
+| `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. |

package/src/index.ts

@@ -15,7 +15,7 @@ export { Agent, SubAgentModelError } from "./agent/agent.ts";
 /**
  * @deprecated Compat alias: prefer composing a plain `Agent` and exposing it
  * via `agentToTool()`/`buildAgentTools()` (or `subagents: [...]`). `SubAgent`
- * stays for compat and receives no new features (Q-56).
+ * stays for compat and receives no new features.
  */
 export { SubAgent, agentFromEnv } from "./agent/subagent.ts";
 export type { SubAgentConfig } from "./agent/subagent.ts";
@@ -33,7 +33,7 @@ export type { CreateToolOptions } from "./tools/tool.ts";
 export { zodToJsonSchema, cleanJsonSchema } from "./tools/schema.ts";
 /**
  * @deprecated Internal executor surface. Prefer `Agent` runs; for direct
- * execution import from the future `/internal` entry (Q-50).
+ * execution import from the future `/internal` entry.
  */
 export { executeToolCalls } from "./tools/executor.ts";
 
@@ -135,7 +135,7 @@ export {
 /**
  * @deprecated Internal provider mappers/routing helpers. Prefer the
  * provider-agnostic registry (`resolveModel`/`getProvider`); direct mapper
- * use moves to the future `/internal` entry (Q-50).
+ * use moves to the future `/internal` entry.
  */
 export {
   emitProviderWarning,
@@ -204,7 +204,7 @@ export type { SteerEntry } from "./agent/loop.ts";
 // Responses
 export { AgentResponse } from "./types/response.ts";
 
-// Core error taxonomy (Q-50 core surface)
+// Core error taxonomy (core surface)
 export {
   AgentAccelError,
   ConfigError,
@@ -219,7 +219,7 @@ export {
   formatErrorPlain,
 } from "./types/errors.ts";
 export type { AgentAccelErrorCode, AgentAccelErrorContext } from "./types/errors.ts";
-// Normalized run limits (Q-22; sub-agents inherit unless overridden)
+// Normalized run limits (sub-agents inherit unless overridden)
 export type { AgentRunLimits } from "./agent/agent.ts";
 
 // Telemetry bus: warnings, anomalies and per-turn thinking traces (attach with `telemetryBus.onEvent`)
@@ -256,14 +256,14 @@ export type { SessionLimits, SessionPayloadStatus, PersistedAgentSession, Sessio
 // Utilities
 /**
  * @deprecated Session-routing internals. Prefer agent-level `sessionId`;
- * direct use moves to the future `/internal` entry (Q-50).
+ * direct use moves to the future `/internal` entry.
  */
 export { createSessionId, hashSessionPart, createTrackingId, nowMs, newRunId, newTurnId, previewPrompt, parseModelRef } from "./utils/session.ts";
 export type { ParsedModelRef } from "./utils/session.ts";
 /**
  * @deprecated Raw env access. Prefer explicit `Agent` config (which wins over
  * env) and `Agent.fromEnv()`/`agentFromEnv()`; direct use moves to the future
- * `/internal` entry (Q-50).
+ * `/internal` entry.
  */
 export { getApiKey, getEnv } from "./utils/env.ts";
 export { buildSessionHeaders, setAttribution, getAttribution } from "./utils/headers.ts";

package/src/models/architecture.md

@@ -5,7 +5,7 @@ The model catalog: context limits, prices, modalities and reasoning options come
 | File | What it is |
 | :-- | :-- |
 | `catalog-cache.ts` | Downloads and caches `models.dev/api.json` in `<home>/catalog/` (or `AGENT_CACHE_DIR`). Stale-while-revalidate: an expired catalog is served at once and refreshed in the background (8 s timeout, 10 min backoff after a failure); only a cold start waits. `AGENT_CATALOG_REFRESH=off` stops automatic refreshes. |
-| `catalog.ts` | Lookups (`getModelFromCatalog`), `registerModel`, thinking validation (`validateModelThinking`), and the exported `GOOGLE_/OPENAI_/OPENROUTER_MODELS` arrays (rebuilt in place when the catalog changes). |
+| `catalog.ts` | Lookups (`getModelFromCatalog`), `registerModel`, thinking validation (`validateModelThinking`, which throws `ThinkingLevelError`, a one-line `ConfigError`), and the exported `GOOGLE_/OPENAI_/OPENROUTER_MODELS` arrays (rebuilt in place when the catalog changes). |
 
 ## Invariants
 - Never hand-edit the cache file; register custom models with `registerModel()`. Verified modality fixes go in `MODALITY_OVERRIDES`.

package/src/models/catalog-cache.ts

@@ -9,13 +9,13 @@ import { writeFileDurable } from "../utils/durable.ts";
 /** Default TTL: 12 Hours (in milliseconds). */
 export const DEFAULT_CATALOG_TTL_MS = 12 * 60 * 60 * 1000;
 
-/** Max accepted models.dev payload size: 15MB (Q-16a). Larger payloads are rejected before parse. */
+/** Max accepted models.dev payload size: 15MB. Larger payloads are rejected before parse. */
 export const MAX_CATALOG_PAYLOAD_BYTES = 15 * 1024 * 1024;
 
 let globalCatalogTtlMs = DEFAULT_CATALOG_TTL_MS;
 
 /** Sets the global model catalog cache TTL in milliseconds.
- * Note (Q-16a): cache files carry their own `ttlMs`. A global `setCatalogTTL`
+ * Note: cache files carry their own `ttlMs`. A global `setCatalogTTL`
  * does not rewrite in-flight file TTLs; it takes effect on the next refresh
  * (fresh download) or when the cached file has no `ttlMs` of its own.
  */
@@ -90,7 +90,7 @@ export function getCacheDir(): string {
   return path.join(resolveHome(), "catalog");
 }
 
-/** Cache file path: `<cacheDir>/models.dev.json`, honoring AGENT_CACHE_DIR (Q-16a/Q-34). */
+/** Cache file path: `<cacheDir>/models.dev.json`, honoring AGENT_CACHE_DIR. */
 export function getCacheFilePath(): string {
   return path.join(getCacheDir(), "models.dev.json");
 }
@@ -111,7 +111,7 @@ function writeJsonFileSync(filePath: string, data: any): void {
   writeFileDurable(filePath, JSON.stringify(data), { backup: false });
 }
 
-/** Verifies optional sha256 pin from MODELS_DEV_SHA256 (Q-16a). Returns false on mismatch. */
+/** Verifies optional sha256 pin from MODELS_DEV_SHA256. Returns false on mismatch. */
 export function verifyCatalogSha256(text: string): boolean {
   const pin = getEnv("MODELS_DEV_SHA256")?.trim().toLowerCase();
   if (!pin) return true;
@@ -283,14 +283,14 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
       throw new Error(`HTTP ${res.status} ${res.statusText}`);
     }
 
-    // Q-16a: size-cap before parse (check text length, reject >15MB).
+    // Size-cap before parse (check text length, reject >15MB).
     const text = await res.text();
     if (text.length > MAX_CATALOG_PAYLOAD_BYTES) {
       clearTimeout(timer);
       fallbackToDiskCache();
       return getCatalogStatus();
     }
-    // Q-16a: optional sha256 pin via MODELS_DEV_SHA256.
+    // Optional sha256 pin via MODELS_DEV_SHA256.
     if (!verifyCatalogSha256(text)) {
       clearTimeout(timer);
       fallbackToDiskCache();
@@ -334,7 +334,7 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
 
   // Update in-memory state FIRST so a read-only filesystem still serves the
   // fresh catalog for this process; disk persistence below is best-effort.
-  // Q-34: a real download is NOT from cache.
+  // A real download is NOT from cache.
   activeCatalog = freshData;
   activeFetchedAt = fetchedAt;
   activeTtlMs = effectiveTtl;