agent-accelerator 0.5.7 → 0.5.8

package/src/agent/loop.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 =>
@@ -436,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
@@ -444,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 {
@@ -465,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,
@@ -475,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;
 
@@ -673,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 = {
@@ -717,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++;
@@ -737,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 =
@@ -784,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>")) {
@@ -853,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}).`
@@ -901,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, {
@@ -926,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 });
   }
@@ -963,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)),
@@ -972,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 =
@@ -983,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,
@@ -1042,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);
@@ -1050,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,
@@ -1062,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[] = [];
@@ -1118,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;
@@ -1176,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.
         {
@@ -1238,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)) {
@@ -1315,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 {
@@ -1379,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 });
@@ -1463,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,
@@ -1486,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)) {
@@ -1497,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,
@@ -1506,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);
@@ -1537,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
@@ -1567,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/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/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;

package/src/models/catalog.ts

@@ -1,8 +1,8 @@
 /**
- * Model catalog — battle-tested single source of truth (models.dev)
- * Dynamically loaded and synchronized via ~/.cache with ~12h TTL.
- * All context length, pricing, limits, reasoning, modalities come from here.
- * Providers' hardcoded GOOGLE_MODELS etc. are DEPRECATED fallbacks only.
+ * Model catalog: the single source of truth (models.dev) for context limits, prices, modalities and reasoning options.
+ * The data is cached in `<home>/catalog/models.dev.json` (or `AGENT_CACHE_DIR`) with a 12 hour TTL and refreshed in the
+ * background (see `catalog-cache.ts`). `GOOGLE_MODELS`, `OPENAI_MODELS` and `OPENROUTER_MODELS` are views of it,
+ * rebuilt in place whenever it changes.
  */
 
 import {
@@ -77,12 +77,12 @@ function normalizeModelIdForLookup(modelId: string): string {
 
 // ---------------------------------------------------------------------------
 // Internal cache — battle-tested: avoid repeated global scans (7487 models)
-// Bound lookupCache to 1000 entries LRU (Q-33): evict oldest on overflow.
+// Bound lookupCache to 1000 entries LRU: evict oldest on overflow.
 // ---------------------------------------------------------------------------
 const lookupCache = new Map<string, ModelSpec | undefined>();
 const providerModelsCache = new Map<string, ModelSpec[]>();
 
-/** Bounded LRU set for lookupCache (Q-33): keeps at most 1000 entries. */
+/** Bounded LRU set for lookupCache: keeps at most 1000 entries. */
 function setLookupCache(key: string, value: ModelSpec | undefined): void {
   if (lookupCache.has(key)) lookupCache.delete(key);
   else if (lookupCache.size >= 1000) {
@@ -92,7 +92,7 @@ function setLookupCache(key: string, value: ModelSpec | undefined): void {
   lookupCache.set(key, value);
 }
 
-// Custom-registered models (Q-33): checked first in getModelFromCatalog.
+// Custom-registered models: checked first in getModelFromCatalog.
 const customModelRegistry = new Map<string, ModelSpec>();
 
 // Case-insensitive key of a registered custom model; in: registerModel and lookups, out: a string.
@@ -101,7 +101,7 @@ function customRegistryKey(provider: string, modelId: string): string {
 }
 
 /**
- * Registers a custom model spec that takes precedence over the catalog (Q-33).
+ * Registers a custom model spec that takes precedence over the catalog.
  * Stored in a separate map, checked first in `getModelFromCatalog`.
  */
 export function registerModel(spec: ModelSpec): void {
@@ -124,7 +124,7 @@ export function clearCustomModels(): void {
 }
 
 /**
- * Returns where a model resolves from without touching frozen types (Q-33):
+ * Returns where a model resolves from without touching frozen types:
  * `"override"` for custom-registered or MODALITY_OVERRIDES-covered models,
  * `"catalog"` for plain catalog hits, `"unknown"` when unresolvable.
  */
@@ -256,7 +256,7 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
   const modelId = modelIdInput.trim();
   let result: ModelSpec | undefined;
 
-  // Q-33: custom-registered models win over the catalog.
+  // Custom-registered models win over the catalog.
   const customHit =
     customModelRegistry.get(customRegistryKey(provider, modelId)) ??
     customModelRegistry.get(customRegistryKey(provider, normalizeModelIdForLookup(modelId)));
@@ -287,7 +287,7 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
         return result;
       }
     }
-    // Q-33: tightened fuzzy match — exact, `endsWith("/"+modelId)` boundary,
+    // Tightened fuzzy match — exact, `endsWith("/"+modelId)` boundary,
     // or normalized equality. The old loose `modelId.endsWith(key)` is removed
     // (e.g. "gpt-4o-mini-extra" must not match "mini").
     for (const [key, raw] of Object.entries(providerData.models as Record<string, any>)) {
@@ -563,7 +563,7 @@ export function getModelsForProvider(provider: string): ModelSpec[] {
       out.push(mapModelSpec(alias as ProviderId, key, raw));
     }
   }
-  // Q-33: include custom-registered models for this provider/alias set.
+  // Include custom-registered models for this provider/alias set.
   for (const spec of customModelRegistry.values()) {
     if (aliases.includes(String(spec.provider)) || String(spec.provider) === provider) {
       if (!seen.has(spec.id)) {
@@ -573,7 +573,7 @@ export function getModelsForProvider(provider: string): ModelSpec[] {
     }
   }
   // Also include our internal provider id mapping
-  // Q-33: return copies — cache the canonical array, hand out a fresh copy.
+  // Return copies — cache the canonical array, hand out a fresh copy.
   providerModelsCache.set(provider, out);
   return [...out];
 }

package/src/providers/google.ts

@@ -609,7 +609,7 @@ async function fullHistorySteps(context: ProviderContext): Promise<InteractionIn
       const turnStart = steps.length;
       for (const part of m.content) {
         if (part.type === "thinking" && part.thinking) {
-          // Q-18: preserve namespaced signatures only — foreign-provider
+          // Preserve namespaced signatures only — foreign-provider
           // signatures never echo here; untagged legacy echoes (compat).
           // Absent signatures are omitted (never sent as empty strings).
           const partProvider = (part as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
@@ -642,7 +642,7 @@ async function fullHistorySteps(context: ProviderContext): Promise<InteractionIn
       } else if (m.thoughtSignature && !steps.slice(turnStart).some((s) => s.type === "thought")) {
         // Preserve a signature-only thought so stateless chaining keeps
         // reasoning continuity even when no summary text was retained.
-        // Q-18: only for google/untagged signatures.
+        // Only for google/untagged signatures.
         const msgProvider = (m as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
         if (shouldEchoSignature(msgProvider, "google")) {
           steps.push({ type: "thought", signature: m.thoughtSignature });
@@ -910,7 +910,7 @@ export class GoogleInteractionsProvider implements Provider {
     signal?: AbortSignal
   ): RequestInit {
     const headers: Record<string, string> = { "Content-Type": "application/json", ...options?.headers };
-    // Q-17: key travels as the `x-goog-api-key` header (never `?key=` in the
+    // Key travels as the `x-goog-api-key` header (never `?key=` in the
     // URL, which would leak into logs). Case-insensitive merge so a custom
     // `X-Goog-Api-Key` never duplicates the canonical header. Proxy flows
     // (`apiKey === "unused"`) preserve custom auth instead of overwriting.
@@ -1392,7 +1392,7 @@ export class GoogleInteractionsProvider implements Provider {
         noteProviderTurn(sessionId, "google");
         checkTurnTokens(sessionId, usage);
 
-        // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
+        // Terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
         const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;