agent-accelerator 0.5.6 → 0.5.7

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 (`<home>/telemetry/<date>.ndjson`). |
+| `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.

package/src/index.ts

@@ -1,28 +1,10 @@
 import type { AssistantMessageEventStream as AssistantMessageEventStreamT } from "./streaming/event-stream.ts";
 import type { AgentResponse as AgentResponseT } from "./types/response.ts";
 
-// Q-50 public API budget: ~25 core runtime exports + compat/deprecation shims.
-// Core = Agent, tool, SubAgent (deprecated alias), AgentResponse,
-// AssistantMessageEventStream, document conversion, delegation primitives,
-// provider registry, catalog, errors, and option/normalization helpers.
-// Everything else below is a shim kept for compat and marked @deprecated
-// toward a future `/internal` entry. Nothing is deleted (would break tests).
-//
-// Q-27 node split (deferred): this root entry pulls `session/store.ts`, which
-// imports `node:fs` for session persistence. A future `/node` subpath will
-// host the fs-backed persistence/telemetry surface; the root entry stays
-// runtime-agnostic. Until then, browser/bundler consumers should import the
-// documented core shims only.
-//
-// Q-51 one way to run: `run()` is canonical. `ask()` and `run/stream: true`
-// remain for compat but are deprecated — prefer `run()` for single-shot and
-// `stream()` for event iteration. `Run` (below) is the typed streaming handle.
+// Public barrel: the one entry point of the package (`main`/`module`/`types`). `run()` is the canonical way to run an
+// agent and `stream()` the canonical way to iterate events; `ask()` and `run(..., { stream: true })` remain as shorthands.
 
-/**
- * Typed streaming run handle (Q-51): the `AssistantMessageEventStream`
- * returned by `stream()`/`run(stream:true)`, with its terminal `result()` and
- * `cancel()` surfaced on the type for callers that only need the handle.
- */
+/** The `AssistantMessageEventStream` returned by `stream()`/`run(stream:true)`, typed with its terminal `result()` and `cancel()`. */
 export type Run = AssistantMessageEventStreamT & {
   result: () => Promise<AgentResponseT>;
   cancel: (reason?: unknown) => void;
@@ -64,27 +46,11 @@ export {
   createChildSessionId,
   createFixedChildSessionId,
   isSessionDescendant,
-  getSubAgentTrace,
-  getSubAgentTraceScoped,
-  getSubAgentTraceForSessions,
-  listSubAgentTraceIds,
-  listSubAgentTraceIdsForSessions,
-  subscribeToSubAgent,
-  subscribeToSubAgentForSessions,
-  appendSubAgentStep,
-  pruneTraces,
-  trimTraceSteps,
   checkBudget,
   chargeBudgetUsage,
   reserveSpawn,
-  isStreamingLoop,
-  escapeXml as escapeXmlFromDelegation,
-  MAX_SUBAGENT_TRACES,
-  SUBAGENT_TRACE_TTL_MS,
-  MAX_SUBAGENT_STEPS_PER_TRACE,
-  SUBAGENT_SUBSCRIBE_TTL_MS,
 } from "./agent/delegation.ts";
-export type { AgentAsToolTarget, SubAgentTrace, StreamingLoopHandle } from "./agent/delegation.ts";
+export type { AgentAsToolTarget, SubAgentTrace } from "./agent/delegation.ts";
 export type { WorkerRegistry, WorkerSpec, WorkerInfo, WorkerReply, WorkerCallOptions } from "./agent/workers.ts";
 
 // Scheduled actions: dynamic sub-agents that run later and save their answer to a file
@@ -147,20 +113,12 @@ export { resolveEffectiveThinking } from "./agent/agent.ts";
 export { withRetries, isTransientError } from "./utils/retry.ts";
 export { toConciseProviderError, assertModalitiesSupported, assertNoVideoPartsOnResponses } from "./utils/errors.ts";
 // Native provider implementations.
-/** @deprecated The discontinued beta-Responses transport was removed
- * directly for frozen wire-contract evidence only. It is wired nowhere and
- * must not be extended or re-exported here (Q-46). */
 export {
   OpenAICompatibleChatProvider,
   createOpenAICompatibleProvider,
   createCustomProvider,
   CustomProvider,
 } from "./providers/openai-compat.ts";
-/**
- * @deprecated Compat alias of `OpenAICompatibleChatProvider` (canonical).
- * Kept for back-compat only; new code uses the canonical name (Q-50).
- */
-export { OpenAICompatibleChatProvider as OpenAICompatibleProvider } from "./providers/openai-compat.ts";
 export type { CustomProviderOptions } from "./providers/openai-compat.ts";
 
 // Canonical provider contract (provider-agnostic) + native adapters.
@@ -168,29 +126,12 @@ export {
   GoogleInteractionsProvider,
   clearInteractionChains,
 } from "./providers/google.ts";
-/**
- * @deprecated Compat alias of `GoogleInteractionsProvider` (canonical).
- * Kept for back-compat only; new code uses the canonical name (Q-50).
- */
-export { GoogleInteractionsProvider as GoogleAIStudioProvider } from "./providers/google.ts";
 export {
   OpenRouterChatCompletionsProvider,
 } from "./providers/openrouter.ts";
-/**
- * @deprecated Compat alias of `OpenRouterChatCompletionsProvider`
- * (canonical). Kept for back-compat only (Q-50).
- */
-export { OpenRouterChatCompletionsProvider as OpenRouterProvider } from "./providers/openrouter.ts";
-// Discontinued beta-Responses transport, removed from core
-// (was frozen migration evidence, wired nowhere): OpenRouterResponsesProvider.
 export {
   OpenAIResponsesProvider,
 } from "./providers/openai.ts";
-/**
- * @deprecated Compat alias of `OpenAIResponsesProvider` (canonical).
- * Kept for back-compat only; new code uses the canonical name (Q-50).
- */
-export { OpenAIResponsesProvider as OpenAIProvider } from "./providers/openai.ts";
 /**
  * @deprecated Internal provider mappers/routing helpers. Prefer the
  * provider-agnostic registry (`resolveModel`/`getProvider`); direct mapper
@@ -205,9 +146,7 @@ export {
   clearSessionRouting,
   mapThinkingLevelToGoogle,
   mapServiceTierToGoogle,
-  mapThinkingLevelToOpenRouter,
   mapServiceTierToOpenRouter,
-  mapToolChoiceToOpenRouter,
   mapThinkingLevelToOpenRouterChat,
   mapToolChoiceToOpenRouterChat,
   mapThinkingLevelToOpenAI,
@@ -230,7 +169,6 @@ export {
 export type {
   ProviderCapabilityStatus,
   CanonicalToolChoiceMode,
-  OpenRouterToolChoice,
   OpenRouterChatToolChoice,
   OpenAIToolChoice,
   ChatCompletionsResponseFormat,
@@ -261,11 +199,6 @@ export { clampCacheKey } from "./utils/cache.ts";
 
 // Streaming & Events
 export { AssistantMessageEventStream } from "./streaming/event-stream.ts";
-/**
- * @deprecated Internal SSE plumbing. Prefer `AssistantMessageEventStream`;
- * direct parser use moves to the future `/internal` entry (Q-50).
- */
-export { SSEParser } from "./streaming/sse-parser.ts";
 export type { SteerEntry } from "./agent/loop.ts";
 
 // Responses
@@ -325,8 +258,8 @@ export type { SessionLimits, SessionPayloadStatus, PersistedAgentSession, Sessio
  * @deprecated Session-routing internals. Prefer agent-level `sessionId`;
  * direct use moves to the future `/internal` entry (Q-50).
  */
-export { createSessionId, hashSessionPart, createTrackingId, nowMs, newRunId, newTurnId, previewPrompt, parseModelRef, resolveAgentConfig } from "./utils/session.ts";
-export type { ParsedModelRef, ResolvedAgentConfig } from "./utils/session.ts";
+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

package/src/models/architecture.md

@@ -0,0 +1,14 @@
+# src/models/
+
+The model catalog: context limits, prices, modalities and reasoning options come from models.dev, not from code.
+
+| 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). |
+
+## Invariants
+- Never hand-edit the cache file; register custom models with `registerModel()`. Verified modality fixes go in `MODALITY_OVERRIDES`.
+- The global bare-id fallback applies to first-class providers and explicit bare-id lookups only. A custom prefix never borrows another provider's price or modalities: unknown stays unknown.
+- A payload that is not a catalog (fewer than 3 providers with models) never overwrites the cache.
+- Do not keep static copies of catalog data; use the lookups or the update listener.

package/src/models/catalog-cache.ts

@@ -64,11 +64,13 @@ export interface RefreshCatalogOptions {
 type CatalogUpdateListener = () => void;
 const updateListeners: Set<CatalogUpdateListener> = new Set();
 
+/** Registers a callback run whenever the catalog changes; in: catalog.ts (cache invalidation), out: an unsubscribe function. */
 export function registerCatalogUpdateListener(listener: CatalogUpdateListener): () => void {
   updateListeners.add(listener);
   return () => updateListeners.delete(listener);
 }
 
+// Runs every catalog-change listener, ignoring their errors; in: refresh and home change, out: the listeners.
 function notifyUpdateListeners(): void {
   for (const listener of updateListeners) {
     try {
@@ -93,6 +95,7 @@ export function getCacheFilePath(): string {
   return path.join(getCacheDir(), "models.dev.json");
 }
 
+// Reads and parses a JSON file, null when missing or damaged; in: the cache loader, out: the parsed value.
 function readJsonFileSync(filePath: string): any {
   try {
     if (!fs.existsSync(filePath)) return null;

package/src/models/catalog.ts

@@ -41,6 +41,7 @@ const MODALITY_OVERRIDES: Record<string, { input?: string[]; output?: string[] }
   // 404 still surfaces as a one-line error.
 };
 
+// Applies the verified modality corrections over the catalog's input/output lists; in: mapModelSpec, out: ModelModalities.
 function applyModalityOverrides(provider: string, modelId: string, base: ModelModalities): ModelModalities {
   const hit =
     MODALITY_OVERRIDES[`${provider}/${modelId}`] ??
@@ -65,6 +66,7 @@ function allowsGlobalFallback(providerInput: string, modelIdInput: string): bool
   return p in PROVIDER_ALIASES || p === "gemini" || p === modelIdInput.trim().toLowerCase();
 }
 
+// Drops a leading `provider/` scope from a model id; in: the lookups, out: the bare id.
 function normalizeModelIdForLookup(modelId: string): string {
   if (modelId.includes("/")) {
     const parts = modelId.split("/");
@@ -93,6 +95,7 @@ function setLookupCache(key: string, value: ModelSpec | undefined): void {
 // Custom-registered models (Q-33): 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.
 function customRegistryKey(provider: string, modelId: string): string {
   return `${provider.toLowerCase()}::${modelId.toLowerCase()}`;
 }
@@ -141,6 +144,7 @@ export function getModelSource(provider: string, modelId: string): "catalog" | "
   return getModelFromCatalog(provider, modelId) ? "catalog" : "unknown";
 }
 
+// Derives capability flags (thinking, caching, tools, structured output, modalities) from a raw catalog entry; in: mapModelSpec, out: ModelCapabilities.
 function mapCapabilities(raw: any, cost: ModelCost, reasoning: boolean, toolCall: boolean, modalities: ModelModalities) {
   return {
     supportsThinking: reasoning,
@@ -158,6 +162,7 @@ function mapCapabilities(raw: any, cost: ModelCost, reasoning: boolean, toolCall
   };
 }
 
+// Turns a raw models.dev entry into a ModelSpec with limits, cost, pricing and capabilities; in: the lookups, out: a ModelSpec.
 function mapModelSpec(provider: string, modelId: string, raw: any): ModelSpec {
   const limit: ModelLimit = raw.limit || { context: 128000, output: 8192 };
   const cost: ModelCost = raw.cost || {};
@@ -214,6 +219,7 @@ interface IndexEntry {
 
 let globalIndex: Map<string, IndexEntry> | null = null;
 
+// The lazily built id-to-entry index across all providers, used only for first-class or bare-id fallbacks; in: getModelFromCatalog, out: the index.
 function getGlobalIndex(): Map<string, IndexEntry> {
   if (globalIndex) return globalIndex;
   globalIndex = new Map();
@@ -576,6 +582,7 @@ export const GOOGLE_MODELS: ModelSpec[] = [...getModelsForProvider("google")];
 export const OPENAI_MODELS: ModelSpec[] = [...getModelsForProvider("openai")];
 export const OPENROUTER_MODELS: ModelSpec[] = [...getModelsForProvider("openrouter")];
 
+// Rebuilds the GOOGLE/OPENAI/OPENROUTER_MODELS arrays in place after a catalog change; in: the update listener, out: those exports.
 function refreshExportedModels(): void {
   GOOGLE_MODELS.length = 0;
   GOOGLE_MODELS.push(...getModelsForProvider("google"));

package/src/providers/architecture.md

@@ -0,0 +1,24 @@
+# src/providers/
+
+All HTTP and wire parsing. Canonical mappers (thinking, cache, tool choice, structured output) live in `../providers.ts`, never here.
+
+| File | Wire | Notes |
+| :-- | :-- | :-- |
+| `google.ts` | Google Interactions | Stateful chaining (TTL gate, self-heal on `not_found`), exact replay of raw `steps`, media consts at the top, Gemini 4 long decode as background interactions. |
+| `openai.ts` | OpenAI Responses | Stateless (`store:false`), full history every turn. |
+| `openrouter.ts` | OpenRouter Chat Completions | Every request streams (so it can be cancelled); `generate()` collects its own stream. |
+| `openai-compat.ts` | OpenAI-compatible Chat Completions | Serves every custom prefix; strict subset of fields; no default base URL. |
+| `registry.ts` | - | Routes `provider/model` to an adapter; the registry is immutable; `ModelProvider` helpers. |
+| `shared.ts` | - | Helpers every adapter uses: signals and timers, error payloads, ids, retry-after, SSE scaffold (`linkStreamAbort`, `withAbortTimer`, `readSseData`, `incompleteStreamCheck`, `failStream`). |
+
+## Contract (`Provider`, in `../types/model.ts`)
+`generate(model, context, options)` returns a `ProviderGenerateResult`; `stream(...)` returns an `AssistantMessageEventStream` that ends with an `AgentResponse`; optional `isLongRunning()` tells the loop to skip its whole-call timeouts.
+
+## Invariants
+- Fix shared streaming behaviour in `shared.ts`, never per adapter. Event parsing and request building stay in each adapter.
+- OpenRouter and compat chat chunk handlers are deliberately not merged.
+- A custom prefix never gets another provider's key or base URL.
+- A transient failure is retried only before the first byte of a stream.
+- A stream that ends without a terminal event while a tool call is missing or cut fails as a retryable `incomplete_stream`.
+- Adapters cancel a reader with `reader.cancel().catch(() => {})`, never a bare `void reader.cancel()`.
+- To add a provider: implement `Provider` on native `fetch`, reuse `shared.ts`, add pure mappers to `../providers.ts`, register in `registry.ts`.

package/src/providers/google.ts

@@ -264,10 +264,12 @@ const PAID_CHAIN_TTL_MS = 54 * 24 * 3600 * 1000;
 /** Last-turn total tokens per session for the rehydration invariant (Rule 3). */
 const lastTurnTotals = new Map<string, number>();
 
+// Storage tier for the chain TTL (`paid` only when set, else the safe `free`); in: ProviderRequestOptions.googleTier, out: chainTtlMs.
 function resolveInteractionTier(options?: ProviderRequestOptions): "free" | "paid" {
   return options?.googleTier === "paid" ? "paid" : "free";
 }
 
+// How long a chained interaction pointer is trusted locally (23 h free, 54 d paid); in: the tier, out: liveChainFor.
 function chainTtlMs(options?: ProviderRequestOptions): number {
   return resolveInteractionTier(options) === "paid" ? PAID_CHAIN_TTL_MS : FREE_CHAIN_TTL_MS;
 }
@@ -280,11 +282,13 @@ function reportChainAnomaly(detail: { type: string; [k: string]: unknown }): voi
   } catch {}
 }
 
+// The saved interaction pointer of a session, if any; in: liveChainFor, out: a ChainEntry or undefined.
 function chainFor(sessionId: string | undefined): ChainEntry | undefined {
   if (!sessionId) return undefined;
   return interactionChains.get(sessionId);
 }
 
+// Saves the pointer of the interaction a turn just created; in: generate/stream, out: interactionChains.
 function setChain(sessionId: string | undefined, entry: ChainEntry): void {
   if (!sessionId) return;
   interactionChains.set(sessionId, entry);
@@ -347,6 +351,7 @@ export function clearInteractionChains(sessionId?: string): void {
 // Request building (canonical -> Interactions)
 // ---------------------------------------------------------------------------
 
+// Endpoint from the option, GOOGLE_BASE_URL, else the v1beta default; in: each request, out: the base URL without a trailing slash.
 function resolveBaseUrl(options?: ProviderRequestOptions): string {
   return (
     options?.baseUrl ||
@@ -356,6 +361,7 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
   ).replace(/\/+$/, "");
 }
 
+// API key from the option or env, or `unused` when custom headers carry the auth; in: each request, out: the key or undefined.
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
   const key = getApiKey("google", options?.apiKey, options?.env);
   if (key) return key;
@@ -363,6 +369,7 @@ function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
   return undefined;
 }
 
+// Strips a google/, gemini/ or models/ prefix; in: generate/stream/getModel, out: the bare model id.
 function cleanModelId(model: string | ModelSpec): string {
   const rawId = typeof model === "string" ? model : model.id;
   return rawId.replace(/^(google\/|gemini\/|models\/)/i, "");
@@ -395,6 +402,7 @@ function throwIfFailedInteraction(interaction: InteractionObject, modelId: strin
   throw toConciseProviderError(failure, "google", modelId);
 }
 
+// Canonical tool declarations as Interactions function tools with a Google-safe schema; in: options.tools, out: request `tools`.
 function toGoogleTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -407,6 +415,7 @@ function toGoogleTools(tools?: StandardToolDeclaration[]): Array<Record<string,
   }));
 }
 
+// Canonical tool choice as `generation_config.tool_choice.allowed_tools`; in: options.toolChoice + tool names, out: the config value.
 function toGoogleToolChoice(
   choice: ProviderRequestOptions["toolChoice"],
   toolNames: string[]
@@ -500,6 +509,7 @@ function blockText(blocks: unknown): string {
   return blocks.map((b) => (typeof b?.text === "string" ? b.text : "")).join("");
 }
 
+// A tool result as the text of a function_result block; in: functionResultStep, out: a string.
 function resultToText(result: unknown): string {
   if (typeof result === "string") return result;
   return safeStringify(result);
@@ -654,6 +664,7 @@ async function fullHistorySteps(context: ProviderContext): Promise<InteractionIn
 // Response mapping (Interactions -> canonical)
 // ---------------------------------------------------------------------------
 
+// Google usage as TokenUsage, folding thought tokens into output and clamping cache reads to input; in: an interaction or step.stop usage, out: TokenUsage.
 function mapUsage(raw?: InteractionObject["usage"]): TokenUsage {
   const input = raw?.total_input_tokens ?? 0;
   // Google reports thought tokens separately from `total_output_tokens`, but bills them as output
@@ -677,6 +688,7 @@ function mapUsage(raw?: InteractionObject["usage"]): TokenUsage {
   };
 }
 
+// Interaction status as a finish reason (requires_action = tool_calls, incomplete = length, failed = error); in: parseInteraction/stream, out: finishReason.
 function mapFinishReason(status?: string): string {
   if (status === "requires_action") return "tool_calls";
   if (status === "incomplete") return "length";
@@ -684,6 +696,7 @@ function mapFinishReason(status?: string): string {
   return "stop";
 }
 
+// Turns a finished Interaction into text, thinking, tool calls, usage and replayable steps, throwing on failed or cancelled; in: generate, out: ProviderGenerateResult.
 function parseInteraction(
   interaction: InteractionObject,
   modelId: string,
@@ -767,6 +780,7 @@ export class GoogleInteractionsProvider implements Provider {
     return getModelsForProvider("google");
   }
 
+  // The catalog spec of a model, else a permissive generic one; in: the registry, out: a ModelSpec.
   getModel(modelId: string): ModelSpec | undefined {
     const clean = cleanModelId(modelId);
     return (
@@ -777,6 +791,7 @@ export class GoogleInteractionsProvider implements Provider {
     );
   }
 
+  // Builds the Interactions request: generation config, tools, structured output and the input (latest turn on a live chain, full history on a fresh or switched one); in: generate/stream, out: the request body.
   private buildBody(
     modelId: string,
     context: ProviderContext,
@@ -886,6 +901,7 @@ export class GoogleInteractionsProvider implements Provider {
     })();
   }
 
+  // Fetch options with JSON headers and the x-goog-api-key header; in: doFetch and stream, out: RequestInit.
   private requestInit(
     method: "POST" | "GET",
     body: InteractionRequestBody | undefined,
@@ -902,6 +918,7 @@ export class GoogleInteractionsProvider implements Provider {
     return { method, headers, ...(body ? { body: JSON.stringify(body) } : {}), signal };
   }
 
+  // One HTTP call under the request timeout, returning status, headers and body text; in: fetchInteraction and cancelInteraction, out: the raw reply.
   private async doFetch(
     url: string,
     method: "POST" | "GET",
@@ -924,6 +941,7 @@ export class GoogleInteractionsProvider implements Provider {
     }
   }
 
+  // Throws a concise provider error (status, code, Retry-After, key hint) for a non-2xx reply; in: every Google HTTP call, out: nothing or a thrown error.
   private throwIfError(
     status: number,
     statusText: string,
@@ -992,6 +1010,7 @@ export class GoogleInteractionsProvider implements Provider {
     void this.doFetch(`${baseUrl}/interactions/${id}/cancel`, "POST", undefined, options, apiKey).catch(() => {});
   }
 
+  // Non-streaming turn: creates the interaction (polling it when it runs in the background), records the chain and self-heals once on a lost chain; in: runAgentLoop, out: ProviderGenerateResult.
   async generate(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -1090,6 +1109,7 @@ export class GoogleInteractionsProvider implements Provider {
     }
   }
 
+  // Streaming turn over SSE: assembles text, thinking, calls and exact replay steps, reconnects a dropped background stream and fails clean on a lost chain; in: streamAgentLoop, out: an AssistantMessageEventStream.
   stream(
     model: string | ModelSpec,
     context: ProviderContext,

package/src/providers/openai-compat.ts

@@ -192,10 +192,12 @@ interface ChatResponse {
 // Request building (canonical -> Chat Completions)
 // ---------------------------------------------------------------------------
 
+// Env-variable prefix of a custom provider (`my-llm` becomes `MY_LLM`); in: key and URL lookups, out: the prefix.
 function envPrefixOf(prefix: string): string {
   return prefix.toUpperCase().replace(/[^A-Z0-9]/g, "_");
 }
 
+// Endpoint from the option, the provider's configuration or {PREFIX}_BASE_URL; throws ConfigError when none (never another vendor's URL); in: each request, out: the base URL.
 function resolveBaseUrl(
   prefix: string,
   configuredBaseUrl: string | undefined,
@@ -221,6 +223,7 @@ function resolveBaseUrl(
   return resolved.replace(/\/+$/, "");
 }
 
+// Key from the option, the provider's configuration or {PREFIX}_API_KEY, or `unused` when custom headers carry the auth; in: each request, out: the key or undefined.
 function resolveApiKey(
   prefix: string,
   configuredApiKey: string | undefined,
@@ -282,6 +285,7 @@ function cleanModelId(prefix: string, model: string | ModelSpec): string {
   return rawId.replace(new RegExp(`^${escaped}/`, "i"), "");
 }
 
+// Canonical tool declarations as Chat Completions function tools; in: options.tools, out: request `tools`.
 function toCompatTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -309,6 +313,7 @@ function warnThinkingDropped(prefix: string, thinking: ThinkingConfig | undefine
   });
 }
 
+// `wav` or `mp3`, the only formats Chat audio input takes here; in: contentPartsToBlocks, out: input_audio.format.
 function audioFormatFor(mimeType?: string): string {
   const mime = (mimeType || "").toLowerCase();
   if (mime.includes("wav")) return "wav";
@@ -354,6 +359,7 @@ function assertNoVideoOrFileParts(
   throw err;
 }
 
+// Text, image (link or data URL) and audio parts as Chat content blocks; in: a user message's parts, out: fullHistoryMessages.
 async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPart[]> {
   const blocks: ChatContentPart[] = [];
   for (const part of parts) {
@@ -388,6 +394,7 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPa
   return blocks;
 }
 
+// A tool result as the text of a tool message; in: fullHistoryMessages, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
   return safeStringify(result);
@@ -502,6 +509,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
 // Response mapping (Chat Completions -> canonical)
 // ---------------------------------------------------------------------------
 
+// Chat usage as TokenUsage, clamping cache reads to input; in: a reply or the last stream chunk, out: TokenUsage.
 function mapUsage(raw?: ChatResponse["usage"]): TokenUsage {
   const input = raw?.prompt_tokens ?? 0;
   const output = raw?.completion_tokens ?? 0;
@@ -517,12 +525,14 @@ function mapUsage(raw?: ChatResponse["usage"]): TokenUsage {
     cacheWriteTokens: raw?.prompt_tokens_details?.cache_write_tokens ?? 0,
     thinkingTokens: raw?.completion_tokens_details?.reasoning_tokens ?? 0,
   };
+  // `cost` is an OpenRouter extension. A generic endpoint that sends it may use 0 for "not computed", so only a positive value counts as known (OpenRouter's adapter accepts an explicit 0).
   if (typeof raw?.cost === "number" && raw.cost > 0) {
     usage.cost = { totalCost: raw.cost };
   }
   return usage;
 }
 
+// The Gemini thought signature a proxy put on a tool call, if any; in: parseResponse, out: a string or undefined.
 function extractSignature(rawTc: {
   extra_content?: { google?: { thought_signature?: string } };
 }): string | undefined {
@@ -536,6 +546,7 @@ function withCompatSignature(sig: string | undefined): { thoughtSignature?: stri
   return { thoughtSignature: sig, thoughtSignatureProvider: "google" };
 }
 
+// Throws a concise error for an HTTP 200 reply that carries only `error`; in: parseResponse, out: a thrown error.
 function throwResponseError(
   response: ChatResponse,
   prefix: string,
@@ -550,6 +561,7 @@ function throwResponseError(
   throw toConciseProviderError(failure, prefix, modelId);
 }
 
+// Turns a Chat Completions JSON reply into text, thinking, tool calls and usage; in: generate, out: ProviderGenerateResult.
 function parseResponse(
   response: ChatResponse,
   prefix: string,
@@ -664,6 +676,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     this.configuredApiKey = opts?.apiKey;
   }
 
+  // The catalog spec of a model, else a permissive generic one; in: the registry, out: a ModelSpec.
   getModel(modelId: string): ModelSpec | undefined {
     const clean = cleanModelId(this.prefix, modelId);
     return (
@@ -674,14 +687,17 @@ export class OpenAICompatibleChatProvider implements Provider {
     );
   }
 
+  // This provider's endpoint for one request; in: generate/stream, out: resolveBaseUrl.
   private baseUrl(options?: ProviderRequestOptions): string {
     return resolveBaseUrl(this.prefix, this.configuredBaseUrl, options);
   }
 
+  // This provider's key for one request; in: requireApiKey, out: resolveApiKey.
   private apiKey(options?: ProviderRequestOptions): string | undefined {
     return resolveApiKey(this.prefix, this.configuredApiKey, options);
   }
 
+  // The key, where a missing one only throws for non-local endpoints (loopback and LAN may omit it); in: generate/stream, out: the key or undefined.
   private requireApiKey(baseUrl: string, options?: ProviderRequestOptions): string | undefined {
     const key = this.apiKey(options);
     if (!key && !isLocalEndpoint(baseUrl)) {
@@ -692,6 +708,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     return key;
   }
 
+  // Builds the Chat request (messages, tools, tool_choice, generation controls, response_format, stream usage) and warns+drops what a strict endpoint cannot take; in: generate/stream, out: the body.
   private async buildBody(
     modelId: string,
     context: ProviderContext,
@@ -788,6 +805,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     return body;
   }
 
+  // Fetch options with session-affinity headers (unless opted out), JSON content type and the Bearer key; in: doFetch and stream, out: RequestInit.
   private requestInit(
     body: ChatRequestBody,
     options: ProviderRequestOptions | undefined,
@@ -823,6 +841,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
+  // One HTTP call under the request timeout, returning status, headers and body text; in: generate, out: the raw reply.
   private async doFetch(
     url: string,
     body: ChatRequestBody,
@@ -845,6 +864,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     }
   }
 
+  // Throws a concise provider error (status, code, Retry-After, key hint) for a non-2xx reply; in: generate and stream, out: nothing or a thrown error.
   private throwIfError(
     status: number,
     url: string,
@@ -873,6 +893,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     throw toConciseProviderError(err, this.prefix, modelId);
   }
 
+  // Non-streaming turn as one retried JSON request; in: runAgentLoop, out: ProviderGenerateResult.
   async generate(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -945,6 +966,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     }
   }
 
+  // Streaming turn over SSE: assembles text, reasoning, tool calls and usage, retrying only before the first byte; in: streamAgentLoop, out: an AssistantMessageEventStream.
   stream(
     model: string | ModelSpec,
     context: ProviderContext,