agent-accelerator 0.5.5 → 0.5.7

package/src/session/store.ts

@@ -127,10 +127,12 @@ export interface PersistedAgentSession {
   tools?: SessionToolRecord[];
 }
 
+/** Zeroed cumulative session totals; in: SessionTelemetry, out: a SessionTotals. */
 export function emptyTotals(): SessionTotals {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, cost: 0 };
 }
 
+// A finite non-negative number, else 0; in: telemetry and formatting, out: a safe number.
 function toNumber(n: unknown): number {
   const v = typeof n === "number" ? n : Number(n);
   return Number.isFinite(v) && v >= 0 ? v : 0;
@@ -191,6 +193,7 @@ export function computeSessionTurnCost(usage: TokenUsage, modelStr: string): num
   }
 }
 
+/** Compact token count (`1.2k`, `3.4M`); in: the status bar, out: a string. */
 export function formatSessionTokens(n: number): string {
   const v = toNumber(n);
   if (v >= 1e6) return `${(v / 1e6).toFixed(1)}M`;
@@ -198,6 +201,7 @@ export function formatSessionTokens(n: number): string {
   return `${Math.floor(v)}`;
 }
 
+/** Cost with precision that fits its size (`$0.0042`); in: the status bar and banner, out: a string. */
 export function formatSessionCost(c?: number): string {
   if (!c || c <= 0) return "$0.00";
   if (c < 0.0001) return `$${c.toFixed(6)}`;
@@ -246,10 +250,12 @@ export class SessionTelemetry {
     return turnCost;
   }
 
+  // Zeroes the totals; in: callers starting a fresh session, out: this.totals.
   reset(): void {
     this.totals = emptyTotals();
   }
 
+  // A copy of the totals for saving; in: buildSessionData/JSON.stringify, out: a SessionTotals.
   toJSON(): SessionTotals {
     return { ...this.totals };
   }
@@ -343,6 +349,7 @@ export interface SessionAgentLike {
   context: { systemPrompt?: string; messages: Message[] };
 }
 
+// Slims worker traces for the snapshot (one key per tracking id, repeated final text dropped, reasoning kept); in: buildSessionData, out: the `subagents` field.
 function snapshotSubagents(traces: Record<string, PersistedSubAgentTrace> | undefined): Record<string, PersistedSubAgentTrace> | undefined {
   if (!traces) return undefined;
   const keys = Object.keys(traces);
@@ -562,6 +569,7 @@ function toCacheOption(raw: unknown): CacheOption | undefined {
   return typeof retention === "string" ? legacy[retention] : undefined;
 }
 
+// Parses any supported snapshot shape (current, legacy pretty JSON, JSONL, ancient) or flags it over-limit; in: raw file text, out: a session, null or OVER_LIMIT.
 function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSession | null | typeof OVER_LIMIT {
   const maxMessages = limits?.maxMessages ?? MAX_SESSION_MESSAGES;
   const maxBytes = limits?.maxBytes ?? MAX_SESSION_JSON_BYTES;
@@ -780,10 +788,12 @@ export function saveSessionFile(
 
 const MEDIA_PART_KEYS = ["image", "audio", "video", "file"] as const;
 
+// True for an http(s) link, which stays a reference instead of being saved as media; in: embeddedMedia, out: a boolean.
 function isHttpRef(value: string): boolean {
   return value.startsWith("http://") || value.startsWith("https://");
 }
 
+// Splits a `data:<mime>;base64,<payload>` string; in: embeddedMedia, out: its mime type and payload or undefined.
 function parseDataUrl(value: string): { mimeType: string; base64: string } | undefined {
   const m = value.match(/^data:([^;,]+)?(?:;[^,]*)?;base64,(.+)$/s);
   if (m && m[2]) return { mimeType: m[1] || "application/octet-stream", base64: m[2] };
@@ -797,6 +807,7 @@ function looksLikeEmbeddedBase64(value: string): boolean {
   return /^[A-Za-z0-9+/=\n\r]+$/.test(value.slice(0, 500));
 }
 
+// File extension for saved media from its mime type, else its filename, else `bin`; in: embeddedMedia, out: the extension.
 function extForMedia(mimeType?: string, filename?: string): string {
   const mime = (mimeType || "").toLowerCase().split(";")[0]!.trim();
   const known: Record<string, string> = {
@@ -850,6 +861,7 @@ export function embeddedMedia(part: ContentPart): { key: (typeof MEDIA_PART_KEYS
   return { key, bytes, ...(mimeType ? { mimeType } : {}), ext: extForMedia(mimeType, typeof p["filename"] === "string" ? (p["filename"] as string) : undefined) };
 }
 
+// Copy of the messages that keeps media bytes (structuredClone, else JSON); in: extractMediaToDir/resolveMediaPaths, out: a new array.
 function cloneMessages(messages: Message[]): Message[] {
   try {
     const g: any = globalThis as any;
@@ -1136,6 +1148,7 @@ export const MAX_SESSION_MESSAGES = 50_000;
 /** Default max raw JSON size accepted when loading a session snapshot (override via `SessionLimits`). */
 export const MAX_SESSION_JSON_BYTES = 100 * 1024 * 1024;
 
+// A SessionLoadError-named Error with the SDK prefix; in: validateSessionData, out: the error.
 function sessionLoadError(message: string): Error {
   const e = new Error(`[Agent Accelerator] Invalid session: ${message}`);
   e.name = "SessionLoadError";
@@ -1314,6 +1327,7 @@ const SERVICE_TIER_MULTIPLIERS: Record<string, number> = {
   fast: 2,
 };
 
+// Price multiplier for a service tier (flex 0.5, priority 2, 2.5 for gpt-5.5; estimates); in: priceUsage, out: the multiplier and tier name.
 function serviceTierMultiplier(serviceTier?: string, modelId?: string): { multiplier: number; tier?: string } {
   if (!serviceTier) return { multiplier: 1 };
   const lower = serviceTier.toLowerCase();
@@ -1327,6 +1341,7 @@ function serviceTierMultiplier(serviceTier?: string, modelId?: string): { multip
   return m !== undefined ? { multiplier: m, tier: serviceTier } : { multiplier: 1, tier: serviceTier };
 }
 
+// Integer micro-USD to dollars; in: priceUsage, out: a number.
 function toDollars(microUSD: number): number {
   return microUSD / 1_000_000;
 }
@@ -1391,7 +1406,7 @@ function resolveEffectivePricing(
 /**
  * Prices one usage snapshot with integer micro-USD accumulation (Q-36).
  *
- * - Provider-reported `usage.cost.totalCost > 0` wins (source `provider`).
+ * - A provider-reported `usage.cost.totalCost` (a number, 0 included: free or cached) wins (source `provider`).
  * - Else catalog pricing via `resolveEffectivePricing` (source `catalog`).
  * - Else returns `undefined` (source `unknown` is implicit) — unknown stays
  *   unknown, never a fabricated 0 object.
@@ -1408,7 +1423,7 @@ export function priceUsage(
   opts?: { serviceTier?: ServiceTier | string; modelId?: string }
 ): PricedCost | undefined {
   const reported = usage?.cost;
-  if (reported && typeof reported.totalCost === "number" && reported.totalCost > 0) {
+  if (reported && typeof reported.totalCost === "number" && reported.totalCost >= 0) {
     const micro = (d?: number): number => (typeof d === "number" && d > 0 ? Math.round(d * 1_000_000) : 0);
     const inputMicroUSD = micro(reported.inputCost);
     const outputMicroUSD = micro(reported.outputCost);
@@ -1492,7 +1507,7 @@ export function addCostToUsage(
   spec?: ModelSpec,
   opts?: { serviceTier?: ServiceTier | string }
 ): TokenUsage["cost"] | undefined {
-  if (usage?.cost && typeof usage.cost.totalCost === "number" && usage.cost.totalCost > 0) {
+  if (usage?.cost && typeof usage.cost.totalCost === "number" && usage.cost.totalCost >= 0) {
     return usage.cost;
   }
   const priced = priceUsage(usage, spec, opts);

package/src/session/usage.ts

@@ -39,6 +39,7 @@ export function emptyUsage(): UsageTotals {
   };
 }
 
+// A finite whole number >= 0, else 0; in: the usage maths and readUsage, out: a safe count.
 const count = (n: unknown): number => (typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : 0);
 
 /** A model reference (string or catalog spec) as a plain string for a report line. */

package/src/streaming/architecture.md

@@ -0,0 +1,13 @@
+# src/streaming/
+
+| File | What it is |
+| :-- | :-- |
+| `event-stream.ts` | `AssistantMessageEventStream`: an async-iterable event stream with listeners (`on`/`off`), a `result()` promise, `cancel()` and bounded buffering. Providers produce it; the loop and `Agent` consume it. |
+| `sse-parser.ts` | `SSEParser`: incremental Server-Sent Events framing that survives events split across network chunks. Internal (not exported from the barrel). |
+
+## Invariants
+- The buffer holds at most 1000 events (oldest dropped, reported on the bus); an event over 1 MB is dropped. `{ buffer: false }` keeps none (for a caller that only wants `result()`).
+- `end()` without a response fails the stream instead of leaving `result()` hanging.
+- A cancel is recognised by the `AbortError` name only, never by message text.
+- Breaking out of `for await` cancels the stream, which tears down the HTTP request.
+- A throwing listener never breaks the stream; the first error is kept in `getListenerError()`.

package/src/streaming/event-stream.ts

@@ -30,6 +30,7 @@ export const MAX_BUFFERED_EVENTS = 1000;
 /** Default max approx bytes per delta event (Q-29). */
 export const MAX_EVENT_BYTES = 1_048_576;
 
+// Approximate size of an event's text fields; in: push's oversize guard, out: a character count.
 function approxEventBytes(event: StreamEvent): number {
   let n = 0;
   if (typeof event.delta === "string") n += event.delta.length;
@@ -39,6 +40,7 @@ function approxEventBytes(event: StreamEvent): number {
   return n;
 }
 
+// Reports a dropped or overflowing event on the bus and the legacy hook, never throwing; in: push/enqueueBounded, out: telemetryBus.
 function reportStreamAnomaly(detail: { type: string; [k: string]: unknown }): void {
   // why: bus + hook only, never console — streams are hot paths and logging
   // per-drop would spam and break no-console policy (Q-29/Q-41).
@@ -161,6 +163,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     }
   }
 
+  // Calls the listeners of the event's type and `*`, remembering the first listener error instead of throwing; in: push, out: those callbacks.
   private deliverToListeners(event: StreamEvent): void {
     const specificListeners = this.listeners.get(event.type);
     if (specificListeners) {
@@ -187,6 +190,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     }
   }
 
+  // Buffers an event for the iterator, dropping the oldest non-error events beyond the cap; in: push, out: this.queue.
   private enqueueBounded(event: StreamEvent): void {
     this.queue.push(event);
     while (this.queue.length > this.maxBufferedEvents) {
@@ -289,6 +293,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     return this.finalResultPromise;
   }
 
+  // Iterator over the stream: buffered events first, then waits for new ones; breaking out cancels the stream and a failed stream rejects after delivering its error event; in: for-await consumers, out: StreamEvents.
   [Symbol.asyncIterator](): AsyncIterator<StreamEvent> {
     let iteratorDone = false;
     return {

package/src/telemetry.ts

@@ -30,6 +30,7 @@ interface TelemetryBus {
   clear(): void;
 }
 
+/** The in-process telemetry bus: listeners subscribe with `onEvent`; emission never throws and does nothing without listeners. */
 export const telemetryBus: TelemetryBus = (() => {
   const listeners = new Set<TelemetryListener>();
   const deliver = (event: TelemetryEvent): void => {

package/src/tools/architecture.md

@@ -0,0 +1,19 @@
+# src/tools/
+
+Defining tools and running them.
+
+| File | What it is |
+| :-- | :-- |
+| `tool.ts` | `tool()` factory, name validation, `toStandardToolDeclarations`, option normalizers. |
+| `schema.ts` | Zod to JSON Schema, `$ref` resolution, `stripSchemaForGoogle`. |
+| `executor.ts` | `executeToolCalls`: validation, concurrency (8 global + per-tool), attempts, timeout, result cap, error scrubbing, `ctx.stop`, `tool.*` events, per-call logs. |
+| `subagent-result.ts` | The private-Symbol brand that marks a result as made by the SDK's delegation tools. |
+
+## Invariants
+- Tool names match `^[a-zA-Z0-9_-]{1,64}$` and must not collide after normalization (checked in the `Agent` constructor).
+- One attempt by default; only idempotent tools retry transient failures; the timeout is best effort (`ctx.signal` is cooperative), and an uncooperative tool no longer holds an aborted run.
+- Results are capped by serialized size (default 20000 chars); nested error stacks and absolute paths are scrubbed. The telemetry bus gets full detail, the model gets the scrubbed text.
+- A truncated call (`{ __truncated_raw }`) never executes.
+- `ctx.stop(reason)` throws a private signal; the batch finishes, then the loop ends the run as `stopped`.
+- Only branded envelopes get their `_subagentMetadata` trusted; the executor passes them through untouched.
+- Failures return `Error executing <name>: <msg>` plus a JSON block (attempts, timedOut, last progress, hint).

package/src/tools/executor.ts

@@ -28,20 +28,24 @@ export interface ExecuteToolsOptions {
 
 const DEFAULT_TOOL_CONCURRENCY = 8;
 
+// Wall-clock milliseconds; in: the executor's timing, out: a number.
 function nowMs(): number {
   return Date.now();
 }
 
+// Milliseconds since `start`, at least 1 so a result never reports 0; in: result records, out: durationMs.
 function elapsedMs(start: number): number {
   return Math.max(1, nowMs() - start);
 }
 
+// A finite number >= 0 from a number or numeric string option, else undefined; in: tool options, out: timeout and limits.
 function numericOption(value: number | string | undefined): number | undefined {
   if (value === undefined || value === "") return undefined;
   const parsed = typeof value === "number" ? value : Number(value);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
 }
 
+// numericOption rounded down to a whole number; in: tool options, out: attempts, concurrency and char caps.
 function integerOption(value: number | string | undefined): number | undefined {
   const parsed = numericOption(value);
   return parsed === undefined ? undefined : Math.floor(parsed);
@@ -128,11 +132,13 @@ export function sanitizeErrorMessage(message: string): string {
   return out;
 }
 
+// The tool's `maxResultChars` or the 20000 default; in: runSingle, out: the cap on a result kept for the model.
 function resultCharLimit(toolDef: ToolDefinition): number {
   const configured = integerOption((toolDef as any).maxResultChars);
   return configured && configured > 0 ? configured : DEFAULT_MAX_RESULT_CHARS;
 }
 
+// Cuts a string to the limit and appends a `[Truncated: ...]` note; in: runSingle, out: the capped result.
 function truncateResultString(value: string, limit: number): string {
   if (value.length <= limit) return value;
   return value.slice(0, limit) + `\n[Truncated: showing ${limit} of ${value.length} chars]`;
@@ -275,12 +281,14 @@ export function traceToolEvent(
   });
 }
 
+// Scrubbed, JSON-safe value capped to `max` serialized characters for logs and events; in: progress and event tracing, out: a value or a truncated string.
 function capJson(value: unknown, max = 2000): unknown {
   const safe = scrubErrors(toJsonSafe(value));
   const json = JSON.stringify(safe);
   return typeof json === "string" && json.length > max ? `${json.slice(0, max)}…[truncated]` : safe;
 }
 
+// Edit distance between two strings; in: resolveTool's did-you-mean, out: a number.
 function levenshtein(a: string, b: string): number {
   const row = Array.from({ length: b.length + 1 }, (_, i) => i);
   for (let i = 1; i <= a.length; i++) {
@@ -303,6 +311,7 @@ interface ResolvedTool {
   suggestion?: string;
 }
 
+// Finds the tool a call names (exact, then case/format-insensitive), else suggests the closest name; in: runSingle and findToolDefinition, out: ResolvedTool.
 function resolveTool(tools: Record<string, ToolDefinition>, requestedName: string): ResolvedTool {
   const direct = tools[requestedName];
   if (direct) return { definition: direct, name: direct.name || requestedName };
@@ -348,6 +357,7 @@ class Semaphore {
 
   constructor(private readonly limit: number) {}
 
+  // Takes a slot (immediately if free, else waits in line), rejecting if the run aborts first; in: runSingle, out: a release function.
   acquire(signal?: AbortSignal): Promise<() => void> {
     if (signal?.aborted) return Promise.reject(new Error("Tool execution aborted"));
     if (this.limit === Number.POSITIVE_INFINITY || this.active < this.limit) {
@@ -372,6 +382,7 @@ class Semaphore {
     });
   }
 
+  // Frees a slot and hands it to the next live waiter, dropping aborted ones; in: the function acquire returned, out: the next waiter's grant.
   private release(): void {
     this.active = Math.max(0, this.active - 1);
     while (this.waiters.length > 0) {
@@ -405,6 +416,7 @@ function isTransientError(error: any): boolean {
   return false;
 }
 
+// Waits the retry backoff, rejecting `Tool execution aborted` as soon as the run aborts; in: runSingle's retry loop, out: nothing.
 function waitForRetry(ms: number, signal?: AbortSignal): Promise<void> {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {
@@ -437,6 +449,7 @@ function raceAbort<T>(work: Promise<T>, signal: AbortSignal | undefined): Promis
   });
 }
 
+// One attempt of a tool: runs it, raced against the run's abort and the per-attempt timeout (which also aborts the tool's signal); in: runSingle, out: the tool's result or a thrown timeout/abort.
 async function executeAttempt(
   toolDef: ToolDefinition,
   parsedInput: unknown,

package/src/tools/schema.ts

@@ -160,6 +160,7 @@ function extractZodObjectSchema(zodSchema: any): Record<string, unknown> {
   };
 }
 
+// Best-effort JSON Schema for one Zod property when toJSONSchema is unavailable; in: extractZodObjectSchema, out: a schema fragment.
 function inferZodPropertyType(prop: any): Record<string, unknown> {
   const unwrapped = prop.unwrap?.() || prop._def?.innerType || prop;
   const description = prop.description || unwrapped.description || prop._def?.description;

package/src/tools/subagent-result.ts

@@ -34,6 +34,7 @@ export function isSubagentResult(value: unknown): value is SubagentResult {
   return !!value && typeof value === "object" && (value as Record<symbol, unknown>)[SUBAGENT_RESULT_BRAND] === true;
 }
 
+// A finite number >= 0, else 0; in: normalizeSubagentMetadata, out: a safe usage count.
 const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
 
 /**

package/src/types/architecture.md

@@ -0,0 +1,20 @@
+# src/types/
+
+Shared contracts. Types only, plus a few tiny helpers that belong to a type.
+
+| File | What it defines |
+| :-- | :-- |
+| `agent.ts` | `AgentConfig`, `AgentRunOptions`, `DynamicSubagentsConfig`, `Budget`, `EditableAgentConfig`, run/turn event shapes. |
+| `core.ts` | `ThinkingLevel`, `CacheOption` (+ `CACHE_OPTIONS`), `ServiceTier`, `TokenUsage`. |
+| `message.ts` | `Message` and the content parts (text, image, audio, video, file, tool call/result, thinking), `ProviderSteps`. |
+| `model.ts` | `ModelSpec`, `Provider`, `ProviderRequestOptions`, `ProviderGenerateResult`, structured-output spec. |
+| `response.ts` | `AgentResponse`, `FinishReason` + `normalizeFinishReason`, `StreamEvent`, worker metadata. |
+| `tool.ts` | `ToolDefinition`, `ToolExecutionContext` (`log`, `stop`, `emit`), call/result records, the truncated-arguments marker. |
+| `scheduler.ts` | Scheduled-action input, record and delivery types. |
+| `errors.ts` | The typed error family (`AgentAccelError` and subclasses), `isAbortError`. |
+
+## Invariants
+- Adding a field to a public type is a public API change: update `README.md` and `docs/`.
+- Abort means `signal.aborted` or `name === "AbortError"`, never a message match.
+- Error messages are one line and ANSI-free.
+- No logic here beyond `normalizeFinishReason`, `isTruncatedArguments` and the error classes.

package/src/types/message.ts

@@ -9,7 +9,7 @@ export interface TextPart {
   thoughtSignature?: string;
 }
 
-/** Detail level a provider spends on one image or video (more detail = more input tokens). Google only; other providers ignore it with a warning. */
+/** Detail level a provider spends on one image or video (more detail = more input tokens). Google (images and videos) and OpenRouter (images, as `image_url.detail`) honour it; other providers ignore it with a warning. */
 export type MediaResolution = "low" | "medium" | "high" | "ultra_high";
 
 /** Image content accepted as a URL, data, path, or binary value. */

package/src/utils/architecture.md

@@ -0,0 +1,25 @@
+# src/utils/
+
+Small shared helpers. Each file has one job.
+
+| File | What it does |
+| :-- | :-- |
+| `durable.ts` | The ONE disk writer (`writeFileDurable`: temp, fsync, `.bak`, rename, folder fsync), `readWithBackup`, and `lockFolder` (one process per folder, stale-lock takeover, temp sweep). |
+| `home.ts` | `resolveHome` / `setHome`: the single folder everything is stored in. |
+| `env.ts` | Process-env lookups and API key resolution. No `globalThis` fallback. |
+| `headers.ts` | Session-affinity headers, opt-in attribution, browser stripping, package version fallback. |
+| `media.ts` | Normalizes a path, URL, data URL, base64 or bytes to base64 and a MIME type; magic-byte sniffing. |
+| `safe-io.ts` | `fileAccess.roots` containment and the guarded remote fetch (private hosts refused, redirects re-checked, size cap). |
+| `raw-capture.ts` | The `captureRaw` policy for `AgentResponse.raw`. |
+| `cache.ts` | Cache-key clamp (64 chars) and the central secret redaction. |
+| `errors.ts` | `toConciseProviderError` and pre-network modality guards. |
+| `retry.ts` | `withRetries`, `isTransientError`, `isRetryableRun`, `sleep`. Structured data only (status, code, flags), never message text. |
+| `session.ts` | Id helpers (`createSessionId`, `hashSessionPart`, `createTrackingId`, run/turn ids), `parseModelRef`, `previewPrompt`. |
+| `serialization.ts` | `toJsonSafe`, `safeStringify`, `escapeXml`. |
+| `base64.ts`, `thought-signature.ts` | Runtime-agnostic base64; Gemini thought-signature helpers. |
+
+## Invariants
+- Never write state with a bare `writeFileSync`; use `writeFileDurable`.
+- `media.ts` and `safe-io.ts` import `node:*` lazily so browser bundles keep working.
+- Redaction is central (`cache.ts`); adapters must not keep their own deny-lists.
+- `AGENT_ACCEL_HOME` is read at import time; `setHome()` after import relies on the catalog reload hook.

package/src/utils/base64.ts

@@ -1,5 +1,6 @@
 /** Runtime-agnostic base64 helpers — no Node Buffer, safe in browsers. */
 
+/** Decodes base64 (whitespace ignored) to bytes, with Buffer when present, else atob; in: media and session code, out: a Uint8Array. */
 export function base64ToBytes(b64: string): Uint8Array {
   const clean = b64.replace(/\s/g, "");
   const nodeBuffer = (globalThis as any)?.Buffer;
@@ -13,6 +14,7 @@ export function base64ToBytes(b64: string): Uint8Array {
   return out;
 }
 
+/** Encodes bytes as base64, with Buffer when present, else btoa in chunks; in: media and session code, out: a string. */
 export function bytesToBase64(bytes: Uint8Array): string {
   const nodeBuffer = (globalThis as any)?.Buffer;
   if (nodeBuffer && typeof nodeBuffer.from === "function") {

package/src/utils/cache.ts

@@ -28,11 +28,13 @@ const SENSITIVE_VALUE_PATTERNS: RegExp[] = [
   /(^|[^A-Za-z0-9])AIza[A-Za-z0-9_-]{10,}/,
 ];
 
+// True when a header name contains key, token, secret, cookie or authorization; in: redactHeadersCentral, out: a boolean.
 function headerNameIsSensitive(name: string): boolean {
   const lower = String(name ?? "").toLowerCase();
   return REDACT_HEADER_SUBSTRINGS.some((s) => lower.includes(s));
 }
 
+// True when a string looks like a credential (sk-, gsk_, xox, AIza, long Bearer token); in: the redactors, out: a boolean.
 function valueLooksSensitive(value: unknown): boolean {
   if (typeof value !== "string") return false;
   const v = value.trim();

package/src/utils/errors.ts

@@ -3,6 +3,7 @@ import { getModelFromCatalog } from "../models/catalog.ts";
 
 const CONCISE = "__agentAccelConcise";
 
+// HTTP status from the shapes provider errors carry, else undefined; in: toConciseProviderError, out: a status.
 function readStatus(error: any): number | undefined {
   const s =
     error?.statusCode ??
@@ -14,6 +15,7 @@ function readStatus(error: any): number | undefined {
   return Number.isFinite(n) && n > 0 ? n : undefined;
 }
 
+// The request URL of an error without its query string; in: toConciseProviderError, out: a string.
 function readUrl(error: any): string {
   const raw =
     (typeof error?.url === "string" && error.url) ||
@@ -22,6 +24,7 @@ function readUrl(error: any): string {
   return raw.split("?")[0];
 }
 
+// The provider's own message from the error's data, body or message; in: toConciseProviderError, out: one trimmed line.
 function readProviderMessage(error: any): string {
   const data = error?.data;
   if (typeof data?.error?.message === "string" && data.error.message.trim()) return data.error.message.trim();
@@ -39,6 +42,7 @@ function readProviderMessage(error: any): string {
   return String(error?.message ?? error).slice(0, 300);
 }
 
+// `provider/model` without doubling an existing prefix; in: the error messages, out: a label.
 function displayModel(providerId: string, modelId: string): string {
   if (modelId.toLowerCase().startsWith(`${providerId.toLowerCase()}/`)) return modelId;
   return `${providerId}/${modelId}`;
@@ -113,7 +117,8 @@ const PART_TO_MODALITY: Record<string, "image" | "audio" | "video" | "pdf"> = {
 
 /**
  * Fails fast — before any network call — when the catalog knows the model
- * lacks a requested input modality (image/audio/video/document). Unknown
+ * lacks a requested input modality (image/audio/video/document; files are
+ * not checked on OpenRouter, which parses them for any model). Unknown
  * models (custom providers, dynamic routers) are skipped: the provider
  * verdict stands and surfaces via toConciseProviderError instead.
  */
@@ -130,6 +135,8 @@ export function assertModalitiesSupported(
       if (mapped) needed.add(mapped);
     }
   }
+  // OpenRouter reads a file with the model's native support or its own parser, so the catalog's "pdf" flag never gates a file there.
+  if (providerId === "openrouter") needed.delete("pdf");
   if (needed.size === 0) return;
   let supported: readonly string[] | undefined;
   try {

package/src/utils/headers.ts

@@ -1,6 +1,7 @@
 import type { ProviderId } from "../types/model.ts";
 import { clampCacheKey } from "./cache.ts";
 
+/** True in a browser, worker or React Native scope, where custom headers cause CORS preflights; in: header building, out: a boolean. */
 export function isBrowserRuntime(): boolean {
   try {
     const g = globalThis as any;
@@ -23,9 +24,10 @@ export function getPackageVersion(): string {
     const v = (globalThis as any).process?.env?.npm_package_version;
     if (typeof v === "string" && v) return v;
   } catch {}
-  return "0.5.5";
+  return "0.5.7";
 }
 
+// User-Agent string with version and platform; in: AGENT_ACCEL_USER_AGENT, out: a string.
 function getAgentAccelUserAgent(): string {
   const version = getPackageVersion();
   try {
@@ -125,6 +127,7 @@ const BROWSER_DROPPED = new Set([
   "x-goog-api-client",
 ]);
 
+// Drops the headers a browser may not or should not send; in: buildSessionHeaders, out: the safe headers.
 function stripForBrowser(headers: Record<string, string>): Record<string, string> {
   const out: Record<string, string> = {};
   for (const [k, v] of Object.entries(headers)) {

package/src/utils/media.ts

@@ -26,6 +26,11 @@ export function inferMimeType(input: string, fallback = "application/octet-strea
   if (clean.endsWith(".mp3")) return "audio/mp3";
   if (clean.endsWith(".wav")) return "audio/wav";
   if (clean.endsWith(".ogg")) return "audio/ogg";
+  if (clean.endsWith(".flac")) return "audio/flac";
+  if (clean.endsWith(".m4a")) return "audio/m4a";
+  if (clean.endsWith(".aac")) return "audio/aac";
+  if (clean.endsWith(".aiff") || clean.endsWith(".aif")) return "audio/aiff";
+  if (clean.endsWith(".mpeg") || clean.endsWith(".mpg")) return "video/mpeg";
   if (clean.endsWith(".mp4")) return "video/mp4";
   if (clean.endsWith(".webm")) return "video/webm";
   if (clean.endsWith(".mov")) return "video/quicktime";
@@ -33,6 +38,7 @@ export function inferMimeType(input: string, fallback = "application/octet-strea
   return fallback;
 }
 
+// True when the bytes spell `text` at `start`; in: sniffMimeType, out: a boolean.
 const ascii = (bytes: Uint8Array, start: number, text: string): boolean =>
   bytes.length >= start + text.length && [...text].every((ch, i) => bytes[start + i] === ch.charCodeAt(0));
 
@@ -53,8 +59,12 @@ export function sniffMimeType(bytes: Uint8Array): string | undefined {
   if (ascii(bytes, 0, "RIFF") && ascii(bytes, 8, "WAVE")) return "audio/wav";
   if (ascii(bytes, 0, "%PDF")) return "application/pdf";
   if (ascii(bytes, 0, "OggS")) return "audio/ogg";
+  if (ascii(bytes, 0, "fLaC")) return "audio/flac";
+  if (ascii(bytes, 0, "FORM") && ascii(bytes, 8, "AIF")) return "audio/aiff";
+  if (bytes[0] === 0xff && ((bytes[1] ?? 0) & 0xf6) === 0xf0) return "audio/aac"; // ADTS: sync bits plus layer 00 (MP3 frames have a non-zero layer)
   if (ascii(bytes, 0, "ID3") || (bytes[0] === 0xff && ((bytes[1] ?? 0) & 0xe0) === 0xe0)) return "audio/mp3";
-  if (ascii(bytes, 4, "ftyp")) return ascii(bytes, 8, "qt") ? "video/quicktime" : "video/mp4";
+  if (ascii(bytes, 4, "ftyp")) return ascii(bytes, 8, "M4A") || ascii(bytes, 8, "M4B") ? "audio/m4a" : ascii(bytes, 8, "qt") ? "video/quicktime" : "video/mp4";
+  if (bytes[0] === 0 && bytes[1] === 0 && bytes[2] === 1 && bytes[3] === 0xba) return "video/mpeg"; // MPEG program stream
   if (bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3) return "video/webm";
   return undefined;
 }

package/src/utils/raw-capture.ts

@@ -3,6 +3,7 @@ import type { ProviderRawData } from "../types/model.ts";
 /** How much of the wire exchange `AgentResponse.raw` keeps (see `AgentConfig.captureRaw`). */
 export type CaptureRawMode = false | "redacted" | true;
 
+// Serialized length of a value, 0 if it cannot be serialized; in: the body summaries, out: a number.
 function byteLength(value: unknown): number {
   try {
     return JSON.stringify(value)?.length ?? 0;
@@ -11,6 +12,7 @@ function byteLength(value: unknown): number {
   }
 }
 
+// Tool names from a request body's `tools`, if any; in: summarizeRequestBody, out: names or undefined.
 function toolNames(tools: unknown): string[] | undefined {
   if (!Array.isArray(tools)) return undefined;
   const names = tools
@@ -34,6 +36,7 @@ function summarizeRequestBody(body: unknown): unknown {
   };
 }
 
+// Content-free summary of a response body (size, id, status); in: applyCaptureRaw, out: the summary.
 function summarizeResponseBody(body: unknown): unknown {
   if (body === null || body === undefined) return body;
   const b = (typeof body === "object" ? body : {}) as Record<string, unknown>;

package/src/utils/retry.ts

@@ -43,6 +43,7 @@ export function isRetryableRun(error: unknown): boolean {
   return isTransientError(error);
 }
 
+/** The server's wait hint in ms from `retryAfterMs` or a Retry-After header, capped at 60 s; in: withRetries, out: ms or undefined. */
 export function readRetryAfterMs(error: unknown): number | undefined {
   const err = error as Record<string, unknown>;
   // Preferred: milliseconds attached by the adapter from the Retry-After header.

package/src/utils/safe-io.ts

@@ -98,6 +98,7 @@ export async function enforceFileAccess(messages: Message[], roots: readonly str
 // Remote fetch guard (SSRF + size cap)
 // ---------------------------------------------------------------------------
 
+// True for the private, loopback, link-local and CGNAT IPv4 ranges; in: isPrivateAddress, out: a boolean.
 function ipv4Private(a: number, b: number): boolean {
   return (
     a === 0 ||
@@ -124,6 +125,7 @@ export function isPrivateAddress(address: string): boolean {
   return false;
 }
 
+// True for localhost, .local/.internal names and private addresses; in: assertRemoteUrlAllowed, out: a boolean.
 function isPrivateHostname(host: string): boolean {
   return (
     host === "localhost" ||
@@ -134,6 +136,7 @@ function isPrivateHostname(host: string): boolean {
   );
 }
 
+// Throws RemoteFetchError for a non-http(s) URL or, unless private hosts are allowed, a private host (also by DNS result); in: fetchRemoteBytes on every hop, out: nothing or a thrown error.
 async function assertRemoteUrlAllowed(url: URL, allowPrivateNetwork: boolean): Promise<void> {
   if (url.protocol !== "http:" && url.protocol !== "https:") {
     throw new RemoteFetchError("blocked", `[Agent Accelerator] Only http(s) URLs are allowed (got ${url.protocol}).`, url.href);
@@ -156,6 +159,7 @@ async function assertRemoteUrlAllowed(url: URL, allowPrivateNetwork: boolean): P
   }
 }
 
+// Reads a response body up to `maxBytes`, throwing too_large as soon as the declared or streamed size passes it; in: fetchRemoteBytes, out: the bytes.
 async function readCapped(res: Response, maxBytes: number, url: string): Promise<Uint8Array> {
   const tooLarge = () =>
     new RemoteFetchError(