agent-accelerator 0.5.5 → 0.5.7

package/src/agent/worker.ts

@@ -3,12 +3,9 @@ import type { SubAgentStep } from "../types/response.ts";
 import type { AgentConfig } from "../types/agent.ts";
 import type { Agent } from "./agent.ts";
 import { normalizeToolName } from "../tools/executor.ts";
-import { escapeXml } from "../utils/serialization.ts";
 import { getModel, getSubModel } from "../utils/env.ts";
 import { resolveModel } from "../providers/registry.ts";
 
-export { escapeXml };
-
 /** Minimal live-trace shape shared by fixed + dynamic workers (structural subset of `SubAgentTrace`). */
 export interface LiveWorkerTrace {
   trackingId: string;
@@ -200,6 +197,7 @@ export function grantWorkerTools(
   return grantedTools;
 }
 
+// The provider id a model string resolves to, or undefined when it cannot be resolved; in: resolveWorkerCredentials, out: the provider match check.
 function providerOf(modelStr: string | unknown | undefined): string | undefined {
   if (!modelStr) return undefined;
   try {

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

@@ -58,6 +58,8 @@ import {
   retryOptionsFrom,
   headersToRecord,
   parseRetryAfterMs,
+  linkStreamAbort,
+  withAbortTimer,
 } from "./shared.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { createGenericModelSpec } from "../models/catalog.ts";
@@ -262,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;
 }
@@ -278,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);
@@ -345,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 ||
@@ -354,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;
@@ -361,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, "");
@@ -393,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) => ({
@@ -405,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[]
@@ -498,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);
@@ -652,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
@@ -675,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";
@@ -682,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,
@@ -765,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 (
@@ -775,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,
@@ -884,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,
@@ -900,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",
@@ -922,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,
@@ -990,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,
@@ -1088,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,
@@ -1097,23 +1119,7 @@ export class GoogleInteractionsProvider implements Provider {
     const startTime = Date.now();
     const clean = cleanModelId(model);
 
-    const linked = new AbortController();
-    const forwardUserAbort = () => {
-      try {
-        linked.abort((options?.signal as { reason?: unknown })?.reason);
-      } catch {
-        try {
-          linked.abort();
-        } catch {}
-      }
-    };
-    if (options?.signal?.aborted) forwardUserAbort();
-    else options?.signal?.addEventListener("abort", forwardUserAbort, { once: true });
-    const removeStreamCancel = eventStream.onCancel(() => {
-      try {
-        linked.abort();
-      } catch {}
-    });
+    const { linked, release } = linkStreamAbort(eventStream, options?.signal);
 
     (async () => {
       // Hoisted for the catch-block self-heal (consts inside try are not
@@ -1159,21 +1165,7 @@ export class GoogleInteractionsProvider implements Provider {
         // (429/5xx/network) are retried before the first byte; a live stream is never retried.
         const open = (target: string, method: "POST" | "GET"): Promise<Response> =>
           openStreamResponse({
-            fetchOnce: async () => {
-              const timer =
-                streamTimeoutMs && streamTimeoutMs > 0
-                  ? setTimeout(() => {
-                      try {
-                        linked.abort();
-                      } catch {}
-                    }, streamTimeoutMs)
-                  : undefined;
-              try {
-                return await (options?.fetch ?? fetch)(target, this.requestInit(method, method === "POST" ? body : undefined, options, apiKey, linked.signal));
-              } finally {
-                if (timer) clearTimeout(timer);
-              }
-            },
+            fetchOnce: () => withAbortTimer(linked, streamTimeoutMs, () => (options?.fetch ?? fetch)(target, this.requestInit(method, method === "POST" ? body : undefined, options, apiKey, linked.signal))),
             onHttpError: (r, text) => this.throwIfError(r.status, r.statusText, target, text, clean, headersToRecord(r.headers)),
             noBodyError: () => toConciseProviderError(new Error("Google streaming response had no body"), "google", clean),
             retry: retryOptionsFrom(options),
@@ -1210,7 +1202,7 @@ export class GoogleInteractionsProvider implements Provider {
           () => {
             aborted = true;
             try {
-              void reader?.cancel();
+              void reader?.cancel().catch(() => {}); // an aborted body is already errored: its cancel() rejects, and nobody else listens
             } catch {}
           },
           { once: true }
@@ -1465,12 +1457,7 @@ export class GoogleInteractionsProvider implements Provider {
           eventStream.fail(raw);
         }
       } finally {
-        try {
-          options?.signal?.removeEventListener("abort", forwardUserAbort);
-        } catch {}
-        try {
-          removeStreamCancel();
-        } catch {}
+        release();
       }
     })();