agent-accelerator 0.5.6 → 0.5.8

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;
@@ -33,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";
@@ -51,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";
 
@@ -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,33 +126,16 @@ 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
- * use moves to the future `/internal` entry (Q-50).
+ * use moves to the future `/internal` entry.
  */
 export {
   emitProviderWarning,
@@ -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,17 +199,12 @@ 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
 export { AgentResponse } from "./types/response.ts";
 
-// Core error taxonomy (Q-50 core surface)
+// Core error taxonomy (core surface)
 export {
   AgentAccelError,
   ConfigError,
@@ -286,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`)
@@ -323,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, 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
- * `/internal` entry (Q-50).
+ * `/internal` entry.
  */
 export { getApiKey, getEnv } from "./utils/env.ts";
 export { buildSessionHeaders, setAttribution, getAttribution } from "./utils/headers.ts";

package/src/models/architecture.md

@@ -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

@@ -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.
  */
@@ -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 {
@@ -88,11 +90,12 @@ 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");
 }
 
+// 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;
@@ -108,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;
@@ -280,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();
@@ -331,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 {
@@ -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("/");
@@ -75,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) {
@@ -90,15 +92,16 @@ 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.
 function customRegistryKey(provider: string, modelId: string): string {
   return `${provider.toLowerCase()}::${modelId.toLowerCase()}`;
 }
 
 /**
- * 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 {
@@ -121,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.
  */
@@ -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();
@@ -250,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)));
@@ -281,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>)) {
@@ -557,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)) {
@@ -567,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];
 }
@@ -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);
@@ -599,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;
@@ -632,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 });
@@ -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,
@@ -894,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.
@@ -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,
@@ -1372,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;