agent-accelerator 0.5.6 → 0.5.8

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);
@@ -399,7 +406,7 @@ function resultToOutput(result: unknown): string {
  * resent — except echoed Gemini thought signatures, which strict
  * OpenAI-compatible endpoints require on tool calls they generated.
  *
- * Q-18: signatures are namespaced — only echo when the stored provider is
+ * Signatures are namespaced — only echo when the stored provider is
  * `google` (or untagged legacy). Signatures minted by other providers never
  * leak onto this transport.
  */
@@ -461,7 +468,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
           // Echo provider-issued thought signatures verbatim so endpoints
           // that minted them (Gemini behind a compat proxy) keep working.
           // Only present when a previous turn captured one — other endpoints
-          // never see this field. Q-18: echo only google/untagged signatures.
+          // never see this field. Echo only google/untagged signatures.
           const storedProvider = (part as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
           if (part.thoughtSignature && shouldEchoSignature(storedProvider, "google")) {
             call.extra_content = { google: { thought_signature: part.thoughtSignature } };
@@ -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 {
@@ -530,12 +540,13 @@ function extractSignature(rawTc: {
   return typeof sig === "string" && sig ? sig : undefined;
 }
 
-/** Tags a captured compat signature with its issuing provider (`google`, Q-18). */
+/** Tags a captured compat signature with its issuing provider (`google`). */
 function withCompatSignature(sig: string | undefined): { thoughtSignature?: string; thoughtSignatureProvider?: string } {
   if (!sig) return {};
   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,
@@ -563,7 +575,7 @@ function parseResponse(
 
   const choice = response.choices?.[0];
   const message = choice?.message;
-  // Q-23: refusal content surfaces as text with a `refusal` finish reason.
+  // Refusal content surfaces as text with a `refusal` finish reason.
   const refusal = typeof message?.refusal === "string" && message.refusal ? message.refusal : "";
   const text = typeof message?.content === "string" && message.content ? message.content : refusal;
   // Thinking tolerance: plain `reasoning` plus per-block texts (deepseek-style
@@ -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,
@@ -772,7 +789,7 @@ export class OpenAICompatibleChatProvider implements Provider {
         // why: invalid output shapes fail fast at Agent construction/loop validation.
       }
     }
-    // Q-38: request usage on streams where supported so terminal accounting
+    // Request usage on streams where supported so terminal accounting
     // arrives on the final chunk. Strict servers that reject unknown fields
     // opt out via `COMPAT_NO_STREAM_OPTIONS=1`; an explicit per-call
     // `(options as any).streamOptions === false` also skips it.
@@ -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,
@@ -1046,7 +1068,7 @@ export class OpenAICompatibleChatProvider implements Provider {
           const choice = (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
           const delta = (choice["delta"] as Record<string, unknown>) ?? {};
           // Text delta (content-free accounting frames carry "" — ignored).
-          // Q-23: refusal deltas surface as text with a `refusal` finish.
+          // Refusal deltas surface as text with a `refusal` finish.
           const deltaRefusal = delta["refusal"];
           if (typeof deltaRefusal === "string" && deltaRefusal) {
             text += deltaRefusal;
@@ -1165,7 +1187,7 @@ export class OpenAICompatibleChatProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // 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 cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();

package/src/providers/openai.ts

@@ -167,6 +167,7 @@ const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 // Request building (canonical -> Responses)
 // ---------------------------------------------------------------------------
 
+// Endpoint from the option, OPENAI_BASE_URL/OPENAI_API_BASE, else api.openai.com; in: each request, out: the base URL without a trailing slash.
 function resolveBaseUrl(options?: ProviderRequestOptions): string {
   return (
     options?.baseUrl ||
@@ -178,6 +179,7 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
   ).replace(/\/+$/, "");
 }
 
+// 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("openai", options?.apiKey, options?.env);
   if (key) return key;
@@ -191,6 +193,7 @@ function cleanModelId(model: string | ModelSpec): string {
   return rawId.replace(/^openai\//i, "");
 }
 
+// Canonical tool declarations as Responses function tools; in: options.tools, out: request `tools`.
 function toOpenAITools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -202,6 +205,7 @@ function toOpenAITools(tools?: StandardToolDeclaration[]): Array<Record<string,
   }));
 }
 
+// Text and media parts as input_text, input_image and input_file blocks; web links pass through, the rest is inlined as data URLs; in: a user message's parts, out: fullHistoryInput.
 async function contentPartsToBlocks(parts: ContentPart[]): Promise<ResponseContentPart[]> {
   const blocks: ResponseContentPart[] = [];
   for (const part of parts) {
@@ -258,17 +262,20 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ResponseConte
   return blocks;
 }
 
+// A tool result as the text of a function_call_output item; in: fullHistoryInput, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
   return safeStringify(result);
 }
 
+// Makes an id safe for the Responses wire (allowed characters, at most 64, no trailing underscores); in: fullHistoryInput, out: the id.
 function normalizeResponsesIdPart(part: string): string {
   const sanitized = String(part ?? "").replace(/[^a-zA-Z0-9_-]/g, "_");
   const truncated = sanitized.length > 64 ? sanitized.slice(0, 64) : sanitized;
   return truncated.replace(/_+$/, "") || "fc_unknown";
 }
 
+// Gives a function-call item id the required `fc_` prefix; in: fullHistoryInput, out: the id.
 function normalizeResponsesItemId(itemId: string): string {
   let norm = normalizeResponsesIdPart(itemId);
   if (!norm.startsWith("fc_")) {
@@ -390,6 +397,7 @@ async function fullHistoryInput(context: ProviderContext): Promise<ResponseInput
 // Response mapping (Responses -> canonical)
 // ---------------------------------------------------------------------------
 
+// Responses usage as TokenUsage, clamping cache reads to input; in: a response or the completed event, out: TokenUsage.
 function mapUsage(raw?: ResponsesObject["usage"]): TokenUsage {
   const input = raw?.input_tokens ?? 0;
   const output = raw?.output_tokens ?? 0;
@@ -406,6 +414,7 @@ function mapUsage(raw?: ResponsesObject["usage"]): TokenUsage {
   };
 }
 
+// Turns a Responses object into text, reasoning, tool calls and usage, mapping refusals and incomplete to finish reasons and throwing on failed; in: generate, out: ProviderGenerateResult.
 function parseResponse(
   response: ResponsesObject,
   modelId: string,
@@ -463,7 +472,7 @@ function parseResponse(
     }
   }
 
-  // Q-23: `incomplete` -> length (content-filter truncations surface as
+  // `incomplete` -> length (content-filter truncations surface as
   // refusal when refusal text is present).
   const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
   const finishReason =
@@ -509,6 +518,7 @@ export class OpenAIResponsesProvider implements Provider {
     return getModelsForProvider("openai");
   }
 
+  // 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 (
@@ -519,6 +529,7 @@ export class OpenAIResponsesProvider implements Provider {
     );
   }
 
+  // Builds the stateless Responses request (full history, store:false, tools, reasoning, tier, text.format, cache key and retention); in: generate/stream, out: the body.
   private async buildBody(
     modelId: string,
     context: ProviderContext,
@@ -620,6 +631,7 @@ export class OpenAIResponsesProvider implements Provider {
     return body;
   }
 
+  // Fetch options with session-affinity headers, JSON content type and the Bearer key; in: doFetch and stream, out: RequestInit.
   private requestInit(
     body: ResponsesRequestBody,
     options: ProviderRequestOptions | undefined,
@@ -640,6 +652,7 @@ export class OpenAIResponsesProvider 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: ResponsesRequestBody,
@@ -662,6 +675,7 @@ export class OpenAIResponsesProvider 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,
@@ -692,6 +706,7 @@ export class OpenAIResponsesProvider implements Provider {
     throw toConciseProviderError(err, "openai", modelId);
   }
 
+  // Non-streaming turn as one retried JSON request; in: runAgentLoop, out: ProviderGenerateResult.
   async generate(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -773,6 +788,7 @@ export class OpenAIResponsesProvider 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,
@@ -793,7 +809,7 @@ export class OpenAIResponsesProvider implements Provider {
           );
         }
         assertModalitiesSupported(context, "openai", clean);
-    assertNoVideoPartsOnResponses(context, "openai", clean);
+        assertNoVideoPartsOnResponses(context, "openai", clean);
         const baseUrl = resolveBaseUrl(options);
         const url = `${baseUrl}/responses`;
         const sessionId = options?.sessionId;
@@ -812,7 +828,7 @@ export class OpenAIResponsesProvider implements Provider {
           body,
         };
 
-        // Q-17: optional per-call timeout races the linked abort signal.
+        // Optional per-call timeout races the linked abort signal.
         const streamTimeoutMs = timeoutFor(options as { timeoutMs?: number } | undefined);
         // Transient failures (429/5xx/network) are retried here, before the
         // first byte; once the stream is live it is never retried.
@@ -879,7 +895,7 @@ export class OpenAIResponsesProvider implements Provider {
             type === "response.refusal.delta" ||
             type === "response.output_refusal.delta"
           ) {
-            // Q-23: refusal deltas carry the filter text; surface as text and
+            // Refusal deltas carry the filter text; surface as text and
             // remember for a `refusal` finish reason.
             if (typeof msg["delta"] === "string" && msg["delta"]) {
               text += msg["delta"] as string;
@@ -939,7 +955,7 @@ export class OpenAIResponsesProvider implements Provider {
             }
             // Non-streaming maps `incomplete` → `length` (max tokens). Streaming
             // must do the same — otherwise truncated turns misreport `stop`.
-            // Q-23: content-filter incompletes surface as `refusal`.
+            // Content-filter incompletes surface as `refusal`.
             const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
             if (response.status === "incomplete") {
               finishReason = incompleteReason === "content_filter" ? "refusal" : "length";
@@ -1023,7 +1039,7 @@ export class OpenAIResponsesProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // Q-23: terminal-state guard. Loops ending with no completed body, no
+        // Terminal-state guard. Loops ending with no completed body, no
         // finish_reason, and no usage while carrying no content must fail as
         // `incomplete_stream` (retryable) instead of resolving empty success.
         // Skipped for non-SSE payloads (e.g. JSON mocks in delegation tests)

package/src/providers/openrouter.ts

@@ -145,6 +145,7 @@ const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
 // Request building (canonical -> Chat Completions)
 // ---------------------------------------------------------------------------
 
+// Endpoint from the option, OPENROUTER_BASE_URL, else openrouter.ai; in: each request, out: the base URL without a trailing slash.
 function resolveBaseUrl(options?: ProviderRequestOptions): string {
   return (
     options?.baseUrl ||
@@ -154,6 +155,7 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
   ).replace(/\/+$/, "");
 }
 
+// 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("openrouter", options?.apiKey, options?.env);
   if (key) return key;
@@ -172,11 +174,13 @@ function cleanModelId(model: string | ModelSpec): string {
 
 // The HTTP status of an error chunk inside a stream (the HTTP status itself is 200): its numeric `code`, else the status of its retryable `error_type` (errors-and-debugging.md, "Typed Error Codes"); in: the chunk's error, out: streamInto, where it makes the error retryable.
 const RETRYABLE_ERROR_TYPE_STATUS: Record<string, number> = { rate_limit_exceeded: 429, provider_overloaded: 503, provider_unavailable: 502, timeout: 504, server: 500 };
+// HTTP-like status of an error chunk inside a stream, or undefined when unknown; in: streamInto's error branch, out: the status that makes the error retryable.
 function midStreamStatus(code: unknown, errorType: unknown): number | undefined {
   if (typeof code === "number" && Number.isInteger(code) && code >= 100 && code <= 599) return code;
   return typeof errorType === "string" ? RETRYABLE_ERROR_TYPE_STATUS[errorType] : undefined;
 }
 
+// Canonical tool declarations as Chat Completions function tools; in: options.tools, out: request `tools`.
 function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -192,6 +196,7 @@ function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<stri
 
 // The `input_audio.format` for a MIME type: Chat Completions takes any format string the provider supports (audio.md: wav, mp3, aiff, aac, ogg, flac, m4a, pcm16 ...), so the real format is sent, never a guess; in: an audio part's MIME type, out: contentPartsToBlocks.
 const AUDIO_FORMAT: Record<string, string> = { wav: "wav", wave: "wav", mpeg: "mp3", mp3: "mp3", mp4: "m4a", m4a: "m4a", aac: "aac", ogg: "ogg", flac: "flac", aiff: "aiff" };
+// The `input_audio.format` for an audio MIME type (see AUDIO_FORMAT above); in: contentPartsToBlocks, out: the format string.
 function audioFormatFor(mimeType?: string): string {
   const subtype = (mimeType || "").toLowerCase().split(";")[0]!.split("/")[1]?.replace(/^x-/, "") ?? "";
   return AUDIO_FORMAT[subtype] ?? (subtype || "mp3");
@@ -278,6 +283,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);
@@ -392,6 +398,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
 // Response mapping (Chat Completions -> canonical)
 // ---------------------------------------------------------------------------
 
+// Chat usage as TokenUsage with cache reads clamped to input, cache writes, reasoning tokens and OpenRouter's reported cost (0 counts); in: the last stream chunk, out: TokenUsage.
 function mapUsage(raw?: ChatUsage): TokenUsage {
   const input = raw?.prompt_tokens ?? 0;
   const output = raw?.completion_tokens ?? 0;
@@ -430,6 +437,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     return getModelsForProvider("openrouter");
   }
 
+  // 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 (
@@ -440,6 +448,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     );
   }
 
+  // Builds the Chat request (messages, tools, tool_choice, reasoning, tier, cache_control, generation controls, response_format, session_id); in: streamInto, out: the body.
   private async buildBody(
     modelId: string,
     context: ProviderContext,
@@ -518,6 +527,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     return body;
   }
 
+  // Fetch options with session and opt-in attribution headers, JSON content type and the Bearer key; in: streamInto, out: RequestInit.
   private requestInit(
     body: ChatRequestBody,
     options: ProviderRequestOptions | undefined,
@@ -537,6 +547,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
+  // Throws a concise provider error (status, code, Retry-After, key and media-link hints) for a non-2xx reply, marking the in-flight-budget 402 retryable; in: streamInto, out: nothing or a thrown error.
   private throwIfError(
     status: number,
     url: string,
@@ -612,6 +623,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     }
   }
 
+  // Streaming turn: a normal event stream from streamInto; in: streamAgentLoop, out: an AssistantMessageEventStream.
   stream(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -729,7 +741,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           const choice = (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
           const delta = (choice["delta"] as Record<string, unknown>) ?? {};
           // Text delta (content-free accounting frames carry "" — ignored).
-          // Q-23: refusal deltas surface as text with a `refusal` finish.
+          // Refusal deltas surface as text with a `refusal` finish.
           const deltaRefusal = delta["refusal"];
           if (typeof deltaRefusal === "string" && deltaRefusal) {
             text += deltaRefusal;
@@ -842,7 +854,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // 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 cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();

package/src/providers/registry.ts

@@ -42,6 +42,7 @@ const FIRST_CLASS = new Set([
 // resolve anywhere.
 const REMOVED_PROVIDERS = new Set(["opencode", "opencode-go"]);
 
+// The error text for a removed provider prefix; in: assertProviderNotRemoved, out: a message.
 function removedProviderMessage(id: string): string {
   return (
     `[Agent Accelerator] Provider "${id}" has been removed: OpenCode free models are ` +

package/src/providers/shared.ts

@@ -1,5 +1,5 @@
 /**
- * Shared provider helpers (Q-45-partial).
+ * Shared provider helpers.
  *
  * Single home for the `redactedHeaders` / `readErrorPayload` /
  * `parseArguments` / `normalizeThinkingParts` helpers previously duplicated
@@ -78,7 +78,7 @@ export function readErrorPayload(
   }
 }
 
-/** Retryable incomplete-stream error for truncated SSE (Q-23). */
+/** Retryable incomplete-stream error for truncated SSE. */
 export function incompleteStreamError(provider: string, modelId: string): Error {
   const err = toConciseProviderError(
     Object.assign(new Error("Stream ended without terminal event"), {
@@ -118,7 +118,7 @@ export function isNotFoundChainError(error: unknown): boolean {
   return code === "not_found";
 }
 
-/** Per-request timeout ms from provider options (Q-22). */
+/** Per-request timeout ms from provider options. */
 export function timeoutFor(options: { timeoutMs?: number } | undefined): number | undefined {
   const t = (options as { timeoutMs?: unknown } | undefined)?.timeoutMs;
   return typeof t === "number" && Number.isFinite(t) && t > 0 ? Math.floor(t) : undefined;
@@ -149,7 +149,7 @@ export function combinedSignal(signal?: AbortSignal, timeoutMs?: number): { sign
   return { signal: ctrl.signal, cleanup };
 }
 
-/** Q-34: crypto-backed tool-call id, no Math.random primary. */
+/** Crypto-backed tool-call id, no Math.random primary. */
 export function newToolCallId(prefix = "call"): string {
   try {
     const c = (globalThis as any)?.crypto;