agent-accelerator 0.5.8 → 0.6.0

package/src/types/core.ts

@@ -2,15 +2,7 @@
  * Level-based reasoning — single flag for all levels (bloatfree)
  */
 /** Public reasoning control accepted by AgentConfig. */
-export type ThinkingLevel =
-  | "none"
-  | "dynamic"
-  | "minimal"
-  | "low"
-  | "medium"
-  | "high"
-  | "xhigh"
-  | "max";
+export type ThinkingLevel = "none" | "dynamic" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 // Internal normalized config (SDK-internal, not exposed as Agent flag)
 /** Internal normalized reasoning configuration passed to providers. */

package/src/types/errors.ts

@@ -40,7 +40,11 @@ export class AgentAccelError extends Error {
   readonly code: AgentAccelErrorCode;
   readonly retryable: boolean;
   readonly context: AgentAccelErrorContext;
-  constructor(code: AgentAccelErrorCode, message: string, opts?: { retryable?: boolean; context?: AgentAccelErrorContext; cause?: unknown }) {
+  constructor(
+    code: AgentAccelErrorCode,
+    message: string,
+    opts?: { retryable?: boolean; context?: AgentAccelErrorContext; cause?: unknown }
+  ) {
     super(message);
     this.name = "AgentAccelError";
     this.code = code;
@@ -59,10 +63,26 @@ export class ConfigError extends AgentAccelError {
 
 export class ProviderError extends AgentAccelError {
   readonly status?: number;
-  constructor(message: string, opts?: { status?: number; provider?: string; model?: string; requestId?: string; retryable?: boolean; context?: AgentAccelErrorContext }) {
+  constructor(
+    message: string,
+    opts?: {
+      status?: number;
+      provider?: string;
+      model?: string;
+      requestId?: string;
+      retryable?: boolean;
+      context?: AgentAccelErrorContext;
+    }
+  ) {
     super("provider", message, {
       retryable: opts?.retryable ?? false,
-      context: { ...opts?.context, provider: opts?.provider, model: opts?.model, status: opts?.status, requestId: opts?.requestId },
+      context: {
+        ...opts?.context,
+        provider: opts?.provider,
+        model: opts?.model,
+        status: opts?.status,
+        requestId: opts?.requestId,
+      },
     });
     this.name = "ProviderError";
     this.status = opts?.status;
@@ -124,7 +144,9 @@ export function isAbortError(error: unknown): boolean {
 /** Format without ANSI for CLI pretty-printing. */
 export function formatErrorPlain(err: unknown): string {
   if (err instanceof AgentAccelError) {
-    const ctx = err.context?.provider ? ` [${err.context.provider}${err.context.model ? `/${err.context.model}` : ""}]` : "";
+    const ctx = err.context?.provider
+      ? ` [${err.context.provider}${err.context.model ? `/${err.context.model}` : ""}]`
+      : "";
     const status = err.context?.status ? ` (${err.context.status})` : "";
     return `[${err.code}]${ctx}${status}: ${err.message}`;
   }

package/src/types/model.ts

@@ -185,10 +185,6 @@ export interface ProviderRequestOptions {
   googleTier?: "free" | "paid";
   /** Upper bound on generated tokens for one model call. */
   maxOutputTokens?: number;
-  /** Stop sequence(s). Chat Completions only; other wires warn+drop. */
-  stop?: string[];
-  /** Deterministic-sampling seed. Chat Completions only; other wires warn+drop. */
-  seed?: number;
   /** `fetch` implementation used for the provider request (defaults to global `fetch`). */
   fetch?: typeof fetch;
   /** Base backoff delay in ms for provider retries (default 250). */

package/src/types/tool.ts

@@ -21,7 +21,13 @@ export interface ToolExecutionContext {
   /** Session identifier associated with this invocation. */
   sessionId?: string;
   /** Forwards live sub-agent deltas (used by the `subagents` tool for realtime tracking). */
-  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+  onSubagentEvent?: (event: {
+    trackingId: string;
+    delta?: string;
+    thinkingDelta?: string;
+    partialText?: string;
+    partialThinking?: string;
+  }) => void;
   // Tool API v2 context additions (all optional, additive).
   /** Stable id for this run (`newRunId`). Mirrors SubAgentRunIds.runId. */
   runId?: string;
@@ -161,5 +167,9 @@ export const TRUNCATED_ARGS_KEY = "__truncated_raw";
 export function isTruncatedArguments(args: unknown): boolean {
   if (!args || typeof args !== "object" || Array.isArray(args)) return false;
   const keys = Object.keys(args as Record<string, unknown>);
-  return keys.length === 1 && keys[0] === TRUNCATED_ARGS_KEY && typeof (args as Record<string, unknown>)[TRUNCATED_ARGS_KEY] === "string";
+  return (
+    keys.length === 1 &&
+    keys[0] === TRUNCATED_ARGS_KEY &&
+    typeof (args as Record<string, unknown>)[TRUNCATED_ARGS_KEY] === "string"
+  );
 }

package/src/update-models.ts

@@ -28,7 +28,9 @@ for (const arg of args) {
     }
     // Reject non-numeric TTLs (e.g. --ttl=abc) instead of silently caching NaN.
     if (!Number.isFinite(customTtlMs)) {
-      throw new ConfigError(`Invalid --ttl value "${val}": expected a number with optional h/m suffix (e.g. --ttl=24h).`);
+      throw new ConfigError(
+        `Invalid --ttl value "${val}": expected a number with optional h/m suffix (e.g. --ttl=24h).`
+      );
     }
   }
 }
@@ -42,13 +44,11 @@ try {
   const ttlHours = (result.ttlMs / (1000 * 60 * 60)).toFixed(1);
 
   if (result.fromCache) {
-    console.log(
-      `\x1b[32m✓\x1b[0m Models catalog is already fresh (within ${ttlHours}h TTL).`
-    );
+    console.log(`\x1b[32m✓\x1b[0m Models catalog is already fresh (within ${ttlHours}h TTL).`);
   } else {
     console.log(
       `\x1b[32m✓\x1b[0m Successfully downloaded and cached \x1b[1m${result.modelCount.toLocaleString()}\x1b[0m models ` +
-      `across \x1b[1m${result.providerCount}\x1b[0m providers in ${duration}s.`
+        `across \x1b[1m${result.providerCount}\x1b[0m providers in ${duration}s.`
     );
   }
   console.log(`  \x1b[90mCache location: ${result.cachePath}\x1b[0m`);

package/src/utils/architecture.md

@@ -2,23 +2,24 @@
 
 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`, `lockFolder` (one process per folder, used for session folders; stale-lock takeover, temp sweep) and `withFileMutex` (short per-file lock for state several processes change, e.g. one scheduled action). |
-| `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. |
+| File                                | What it does                                                                                                                                                                                                                                                                                                     |
+| :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `durable.ts`                        | The ONE disk writer (`writeFileDurable`: temp, fsync, `.bak`, rename, folder fsync), `readWithBackup`, `lockFolder` (one process per folder, used for session folders; stale-lock takeover, temp sweep) and `withFileMutex` (short per-file lock for state several processes change, e.g. one scheduled action). |
+| `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` (any raw provider failure becomes one-line `ProviderError`: `code` `"provider"`, `retryable` from status/code, the provider's code as `providerCode`; SDK errors pass through), `isTransientError`, and the pre-network modality guards (`ValidationError`).                            |
+| `retry.ts`                          | `withRetries`, `isTransientError` (re-exported from `errors.ts`), `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.

package/src/utils/cache.ts

@@ -58,9 +58,7 @@ export function redactValue(value: unknown): unknown {
  * Deny-list (name contains): *key*, *token*, *secret*, cookie, authorization.
  * Value patterns (redacted regardless of name): sk-, AIza, gsk-, xox-.
  */
-export function redactHeadersCentral(
-  headers: Record<string, unknown> | undefined | null
-): Record<string, unknown> {
+export function redactHeadersCentral(headers: Record<string, unknown> | undefined | null): Record<string, unknown> {
   if (!headers || typeof headers !== "object") return {};
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(headers)) {

package/src/utils/durable.ts

@@ -32,7 +32,11 @@ export function fsyncFolder(dir: string): void {
  * Durable atomic write: temp file (0600) -> fsync -> previous version kept as `<file>.bak` (hard link, no copy)
  * -> rename -> fsync of the folder. Throws on failure; the temp file is removed. `backup: false` skips the `.bak`.
  */
-export function writeFileDurable(filePath: string, content: string | Uint8Array, opts: { backup?: boolean } = {}): void {
+export function writeFileDurable(
+  filePath: string,
+  content: string | Uint8Array,
+  opts: { backup?: boolean } = {}
+): void {
   const dir = path.dirname(filePath);
   try {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -73,7 +77,10 @@ export function writeFileDurable(filePath: string, content: string | Uint8Array,
  * Reads `file`; when `isValid` rejects it, falls back to `<file>.bak`. `undefined` when the file is missing (a deleted
  * file is never resurrected from its backup). When both are invalid the primary text comes back, `fromBackup: false`.
  */
-export function readWithBackup(file: string, isValid: (text: string) => boolean): { text: string; fromBackup: boolean } | undefined {
+export function readWithBackup(
+  file: string,
+  isValid: (text: string) => boolean
+): { text: string; fromBackup: boolean } | undefined {
   let text: string;
   try {
     text = fs.readFileSync(file, "utf8");
@@ -234,7 +241,8 @@ const heldMutexes = new Set<string>();
  */
 export function withFileMutex<T>(lockFile: string, fn: () => T): T {
   const file = path.resolve(lockFile);
-  if (heldMutexes.has(file)) throw new ConfigError(`[Agent Accelerator] Mutex "${file}" is already held by this process (nested use).`);
+  if (heldMutexes.has(file))
+    throw new ConfigError(`[Agent Accelerator] Mutex "${file}" is already held by this process (nested use).`);
   const mine = JSON.stringify({ pid: process.pid, host: os.hostname(), at: Date.now() });
   const deadline = Date.now() + MUTEX_WAIT_MS;
   let unreadable = 0;
@@ -265,7 +273,8 @@ export function withFileMutex<T>(lockFile: string, fn: () => T): T {
       owner = undefined;
     }
     let stale = false;
-    if (typeof owner?.pid !== "number") stale = ++unreadable > 5; // empty or garbage: another process may be mid-write
+    if (typeof owner?.pid !== "number")
+      stale = ++unreadable > 5; // empty or garbage: another process may be mid-write
     else if (owner.host === os.hostname() && !processAlive(owner.pid)) stale = true;
     else if (Date.now() - mtime > MUTEX_MAX_AGE_MS) stale = true;
     if (stale) {
@@ -276,7 +285,10 @@ export function withFileMutex<T>(lockFile: string, fn: () => T): T {
       }
       continue;
     }
-    if (Date.now() > deadline) throw new ConfigError(`[Agent Accelerator] Timed out after ${MUTEX_WAIT_MS} ms waiting for the lock "${file}" (held by process ${String(owner?.pid)}).`);
+    if (Date.now() > deadline)
+      throw new ConfigError(
+        `[Agent Accelerator] Timed out after ${MUTEX_WAIT_MS} ms waiting for the lock "${file}" (held by process ${String(owner?.pid)}).`
+      );
     pause(typeof owner?.pid === "number" ? 2 : 40);
   }
   heldMutexes.add(file);

package/src/utils/env.ts

@@ -11,7 +11,10 @@ export function getEnv(key: string, fallback?: string): string | undefined {
   if (typeof process !== "undefined" && process.env && process.env[key]) {
     // Trim quotes/whitespace from .env files (`sk-..."\n` -> 401 otherwise).
     const raw = String(process.env[key]);
-    const trimmed = raw.trim().replace(/^["']|["']$/g, "").trim();
+    const trimmed = raw
+      .trim()
+      .replace(/^["']|["']$/g, "")
+      .trim();
     if (trimmed) return trimmed;
   }
   return fallback;
@@ -27,7 +30,10 @@ export type ProviderEnv = Record<string, string>;
 export function getApiKey(provider: string, explicitKey?: string, env?: ProviderEnv): string | undefined {
   const clean = (v: unknown): string | undefined => {
     if (typeof v !== "string") return undefined;
-    const t = v.trim().replace(/^["']|["']$/g, "").trim();
+    const t = v
+      .trim()
+      .replace(/^["']|["']$/g, "")
+      .trim();
     return t || undefined;
   };
   const cleanedExplicit = clean(explicitKey);
@@ -56,11 +62,7 @@ export function getApiKey(provider: string, explicitKey?: string, env?: Provider
   switch (provider.toLowerCase()) {
     case "google":
     case "gemini":
-      return (
-        getEnv("GEMINI_API_KEY") ||
-        getEnv("GOOGLE_API_KEY") ||
-        getEnv("GOOGLE_GENAI_API_KEY")
-      );
+      return getEnv("GEMINI_API_KEY") || getEnv("GOOGLE_API_KEY") || getEnv("GOOGLE_GENAI_API_KEY");
     case "openrouter":
       return getEnv("OPENROUTER_API_KEY");
     case "openai":

package/src/utils/errors.ts

@@ -1,5 +1,34 @@
 import type { ProviderContext } from "../types/message.ts";
 import { getModelFromCatalog } from "../models/catalog.ts";
+import { AgentAccelError, ProviderError, ValidationError, isAbortError } from "../types/errors.ts";
+
+/**
+ * Checks whether a provider error is transient and safe to retry.
+ * Structured-data only: status / code / transient flag. Never message text,
+ * so a 400 mentioning "512 tokens" is not retried.
+ */
+export function isTransientError(error: unknown): boolean {
+  if (!error) return false;
+  if (isAbortError(error)) return false;
+  const err = error as Record<string, unknown>;
+  if (err["transient"] === true) return true;
+  if ((err as { retryable?: unknown }).retryable === true) return true;
+  const status = Number(
+    (err["status"] as number | undefined) ??
+      (err["statusCode"] as number | undefined) ??
+      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      ((err["lastError"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      NaN
+  );
+  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
+  const code = String(
+    (err["providerCode"] as string | undefined) ?? (err["code"] as string | undefined) ?? ""
+  ).toUpperCase();
+  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "EPIPE", "ETIMEDOUT"].includes(code)) {
+    return true;
+  }
+  return false;
+}
 
 const CONCISE = "__agentAccelConcise";
 
@@ -49,12 +78,12 @@ function displayModel(providerId: string, modelId: string): string {
 }
 
 /**
- * Collapses a raw provider error (which carries the full request/response
- * dump as enumerable props) into a one-line actionable error. Raw details stay
- * available but non-enumerable, so runtime dumps stay small.
+ * Collapses a raw provider error (which carries the full request/response dump as enumerable props) into a one-line
+ * `ProviderError` with `retryable` set from its status/code; the provider's own error code is `providerCode`. Raw
+ * details stay available but non-enumerable, so runtime dumps stay small. An SDK error (already typed) passes through.
  */
 export function toConciseProviderError(error: unknown, providerId: string, modelId: string): Error {
-  if (error instanceof Error && (error as any)[CONCISE]) return error;
+  if (error instanceof AgentAccelError || (error instanceof Error && (error as any)[CONCISE])) return error;
   const err = error as any;
   const status = readStatus(err);
   const url = readUrl(err);
@@ -70,10 +99,10 @@ export function toConciseProviderError(error: unknown, providerId: string, model
   if (rawMeta && !detail.includes(rawMeta.slice(0, 80))) {
     detail = `${detail}\n${rawMeta.slice(0, 500)}`.slice(0, 800);
   }
-  const concise = new Error(
-    `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`
+  const concise = new ProviderError(
+    `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`,
+    { status, provider: providerId, model: modelId, retryable: isTransientError(err) }
   );
-  concise.name = "AgentAccelProviderError";
   Object.defineProperties(concise, {
     [CONCISE]: { value: true, enumerable: false },
     statusCode: { value: status, enumerable: false },
@@ -87,14 +116,11 @@ export function toConciseProviderError(error: unknown, providerId: string, model
     // Forwarded when present (e.g. OpenRouter's canonical `error_type`,
     // which disambiguates lossy native codes). Survives re-wraps so retry
     // helpers never strip it.
-    ...(typeof err?.errorType === "string"
-      ? { errorType: { value: err.errorType, enumerable: false } }
-      : {}),
-    // Forwarded when present (e.g. Google's `not_found` chain-eviction code,
-    // which carries no HTTP status on SSE error frames). Survives re-wraps
-    // so chain-expiry detectors never lose it.
+    ...(typeof err?.errorType === "string" ? { errorType: { value: err.errorType, enumerable: false } } : {}),
+    // The provider's own error code (e.g. Google's `not_found` chain-eviction code, which carries no HTTP status on
+    // SSE error frames); `code` itself is the SDK kind (`"provider"`). Survives re-wraps so chain detectors never lose it.
     ...((typeof err?.code === "string" || typeof err?.code === "number") && err.code !== ""
-      ? { code: { value: err.code, enumerable: false } }
+      ? { providerCode: { value: err.code, enumerable: false } }
       : {}),
     // Server rate-limit hint in ms (from Retry-After); survives re-wraps so
     // `withRetries` can honor it instead of hammering a 429.
@@ -120,13 +146,9 @@ const PART_TO_MODALITY: Record<string, "image" | "audio" | "video" | "pdf"> = {
  * 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.
+ * verdict stands and surfaces via toConciseProviderError instead. Throws a `ValidationError`.
  */
-export function assertModalitiesSupported(
-  context: ProviderContext,
-  providerId: string,
-  modelId: string
-): void {
+export function assertModalitiesSupported(context: ProviderContext, providerId: string, modelId: string): void {
   const needed = new Set<string>();
   for (const msg of context.messages) {
     if (!Array.isArray((msg as any)?.content)) continue;
@@ -147,16 +169,10 @@ export function assertModalitiesSupported(
   if (!supported) return;
   const missing = [...needed].filter((k) => !supported.includes(k));
   if (missing.length === 0) return;
-  const err = new Error(
-    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.`
+  throw new ValidationError(
+    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.`,
+    { provider: providerId, model: modelId }
   );
-  err.name = "AgentAccelProviderError";
-  Object.defineProperties(err, {
-    [CONCISE]: { value: true, enumerable: false },
-    provider: { value: providerId, enumerable: false },
-    model: { value: modelId, enumerable: false },
-  });
-  throw err;
 }
 
 /**
@@ -169,13 +185,9 @@ export function assertModalitiesSupported(
  * `openrouter/stealth/space-bunny-alpha` under the old Responses skin despite
  * its catalog `video` flag, which is chat-transport oriented). Fail fast with
  * a clear one-liner instead; video stays Gemini-only, and OpenRouter Chat
- * Completions carries `video_url` natively (no guard there).
+ * Completions carries `video_url` natively (no guard there). Throws a `ValidationError`.
  */
-export function assertNoVideoPartsOnResponses(
-  context: ProviderContext,
-  providerId: string,
-  modelId: string
-): void {
+export function assertNoVideoPartsOnResponses(context: ProviderContext, providerId: string, modelId: string): void {
   let hasVideo = false;
   for (const msg of context.messages) {
     if (!Array.isArray((msg as any)?.content)) continue;
@@ -197,14 +209,8 @@ export function assertNoVideoPartsOnResponses(
     // contradict the rejection).
     if (known && known.length > 0) supported = known.filter((m) => m !== "video").join(", ") || "text";
   } catch {}
-  const err = new Error(
-    `[${displayModel(providerId, modelId)}] unsupported video input (the Responses API accepts text/image/file only; supports: ${supported}). Use a video-capable model (e.g. google/gemini-*) or drop the video part.`
+  throw new ValidationError(
+    `[${displayModel(providerId, modelId)}] unsupported video input (the Responses API accepts text/image/file only; supports: ${supported}). Use a video-capable model (e.g. google/gemini-*) or drop the video part.`,
+    { provider: providerId, model: modelId }
   );
-  err.name = "AgentAccelProviderError";
-  Object.defineProperties(err, {
-    [CONCISE]: { value: true, enumerable: false },
-    provider: { value: providerId, enumerable: false },
-    model: { value: modelId, enumerable: false },
-  });
-  throw err;
 }

package/src/utils/headers.ts

@@ -24,7 +24,7 @@ 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.8";
+  return "0.6.0";
 }
 
 // User-Agent string with version and platform; in: AGENT_ACCEL_USER_AGENT, out: a string.
@@ -93,11 +93,7 @@ function findHeaderKey(headers: Record<string, string>, name: string): string |
  * coexist on the wire.
  * @example `setHeaderCaseInsensitive(headers, "Authorization", "Bearer k");`
  */
-export function setHeaderCaseInsensitive(
-  headers: Record<string, string>,
-  name: string,
-  value: string
-): void {
+export function setHeaderCaseInsensitive(headers: Record<string, string>, name: string, value: string): void {
   const existing = findHeaderKey(headers, name);
   if (existing !== undefined && existing !== name) delete headers[existing];
   headers[name] = value;
@@ -111,10 +107,7 @@ export function setHeaderCaseInsensitive(
  * Returns true when a stored signature may be echoed on `currentProvider`:
  * untagged (legacy) echoes everywhere, tagged echoes only on a match.
  */
-export function shouldEchoSignature(
-  storedProvider: unknown,
-  currentProvider: string
-): boolean {
+export function shouldEchoSignature(storedProvider: unknown, currentProvider: string): boolean {
   if (!storedProvider) return true;
   return storedProvider === currentProvider;
 }

package/src/utils/media.ts

@@ -2,6 +2,7 @@
 // paths are loaded via a lazy dynamic import so browsers never resolve it.
 import { bytesToBase64, base64ToBytes } from "./base64.ts";
 import { fetchRemoteBytes } from "./safe-io.ts";
+import { ValidationError } from "../types/errors.ts";
 
 export interface NormalizedMedia {
   mimeType: string;
@@ -63,7 +64,12 @@ export function sniffMimeType(bytes: Uint8Array): string | undefined {
   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, "M4A") || ascii(bytes, 8, "M4B") ? "audio/m4a" : 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;
@@ -72,9 +78,15 @@ export function sniffMimeType(bytes: Uint8Array): string | undefined {
 const GENERIC_MIME = new Set(["", "application/octet-stream", "binary/octet-stream"]);
 
 /** Picks the best MIME type: explicit hint, then a specific candidate, then magic bytes, then the fallback. */
-function resolveMime(explicit: string | undefined, candidate: string | null | undefined, bytes: Uint8Array, fallback: string): string {
+function resolveMime(
+  explicit: string | undefined,
+  candidate: string | null | undefined,
+  bytes: Uint8Array,
+  fallback: string
+): string {
   if (explicit) return explicit;
-  const specific = candidate && !GENERIC_MIME.has(candidate.split(";")[0]!.trim().toLowerCase()) ? candidate : undefined;
+  const specific =
+    candidate && !GENERIC_MIME.has(candidate.split(";")[0]!.trim().toLowerCase()) ? candidate : undefined;
   return specific || sniffMimeType(bytes) || candidate || fallback;
 }
 
@@ -130,7 +142,7 @@ export async function normalizeMediaInput(
     // but redirects are re-checked and the download is size-capped.
     const response = await fetchRemoteBytes(input, { allowPrivateNetwork: true });
     if (!response.ok) {
-      throw new Error(`Failed to fetch media from URL: ${input} (${response.statusText})`);
+      throw new ValidationError(`Failed to fetch media from URL: ${input} (${response.statusText})`);
     }
     const buffer = response.bytes;
     const mimeType = resolveMime(explicitMimeType, response.contentType, buffer, inferMimeType(input));
@@ -175,10 +187,11 @@ export async function normalizeMediaInput(
         base64Data,
         dataUrl: `data:${mimeType};base64,${base64Data}`,
       };
-    } catch (err) {
+    } catch {
       // S11: don't silently return path string as base64 (would 400). Re-check if it's actually base64 with "/"
       const trimmed = input.replace(/\s/g, "");
-      const isMaybeBase64 = trimmed.length > 100 && /^[A-Za-z0-9+/=\n\r]+$/.test(trimmed.slice(0, 500)) && trimmed.length % 4 === 0;
+      const isMaybeBase64 =
+        trimmed.length > 100 && /^[A-Za-z0-9+/=\n\r]+$/.test(trimmed.slice(0, 500)) && trimmed.length % 4 === 0;
       if (isMaybeBase64) {
         const mimeType = explicitMimeType || sniffBase64(trimmed) || "image/jpeg";
         return {
@@ -187,9 +200,11 @@ export async function normalizeMediaInput(
           dataUrl: `data:${mimeType};base64,${trimmed}`,
         };
       }
-      throw new Error(`Failed to normalize media input: not a valid file path, data URL, http URL, or base64 string: ${input.slice(0, 80)}`);
+      throw new ValidationError(
+        `Failed to normalize media input: not a valid file path, data URL, http URL, or base64 string: ${input.slice(0, 80)}`
+      );
     }
   }
 
-  throw new Error(`Unsupported media input type: ${typeof input}`);
+  throw new ValidationError(`Unsupported media input type: ${typeof input}`);
 }

package/src/utils/raw-capture.ts

@@ -16,7 +16,11 @@ function byteLength(value: unknown): number {
 function toolNames(tools: unknown): string[] | undefined {
   if (!Array.isArray(tools)) return undefined;
   const names = tools
-    .map((t) => (t as { name?: unknown; function?: { name?: unknown } })?.name ?? (t as { function?: { name?: unknown } })?.function?.name)
+    .map(
+      (t) =>
+        (t as { name?: unknown; function?: { name?: unknown } })?.name ??
+        (t as { function?: { name?: unknown } })?.function?.name
+    )
     .filter((n): n is string => typeof n === "string");
   return names.length > 0 ? names : undefined;
 }
@@ -56,7 +60,10 @@ function summarizeResponseBody(body: unknown): unknown {
  *   model output never leak through `response.raw` / `toJSON()` into logs.
  * - `false`: keep only URL, method and HTTP status.
  */
-export function applyCaptureRaw(raw: ProviderRawData | undefined, mode: CaptureRawMode | undefined): ProviderRawData | undefined {
+export function applyCaptureRaw(
+  raw: ProviderRawData | undefined,
+  mode: CaptureRawMode | undefined
+): ProviderRawData | undefined {
   if (!raw || mode === true) return raw;
   const redactedMode = mode !== false; // undefined -> default "redacted"
   const request = raw.request

package/src/utils/retry.ts

@@ -1,33 +1,7 @@
-import { toConciseProviderError } from "./errors.ts";
+import { toConciseProviderError, isTransientError } from "./errors.ts";
 import { isAbortError } from "../types/errors.ts";
 
-export { isAbortError };
-
-/**
- * Checks whether a provider error is transient and safe to retry.
- * Structured-data only: status / code / transient flag. Never message text,
- * so a 400 mentioning "512 tokens" is not retried.
- */
-export function isTransientError(error: unknown): boolean {
-  if (!error) return false;
-  if (isAbortError(error)) return false;
-  const err = error as Record<string, unknown>;
-  if (err["transient"] === true) return true;
-  if ((err as { retryable?: unknown }).retryable === true) return true;
-  const status = Number(
-    (err["status"] as number | undefined) ??
-      (err["statusCode"] as number | undefined) ??
-      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
-      ((err["lastError"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
-      NaN
-  );
-  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
-  const code = String((err["code"] as string | undefined) ?? "").toUpperCase();
-  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "EPIPE", "ETIMEDOUT"].includes(code)) {
-    return true;
-  }
-  return false;
-}
+export { isAbortError, isTransientError };
 
 /**
  * Whether a FAILED RUN (the provider layer already retried the call) is worth trying again: the failure is transient
@@ -39,7 +13,18 @@ export function isRetryableRun(error: unknown): boolean {
   if (!error || isAbortError(error)) return false;
   const name = (error as { name?: unknown }).name;
   if (name === "TimeoutError") return true; // the loop's own request / first-byte / idle timeouts
-  if (["BudgetExceededError", "ConfigError", "ValidationError", "SecurityPolicyError", "SessionLoadError", "ThinkingLevelError", "ToolError"].includes(String(name))) return false;
+  if (
+    [
+      "BudgetExceededError",
+      "ConfigError",
+      "ValidationError",
+      "SecurityPolicyError",
+      "SessionLoadError",
+      "ThinkingLevelError",
+      "ToolError",
+    ].includes(String(name))
+  )
+    return false;
   return isTransientError(error);
 }
 
@@ -50,8 +35,9 @@ export function readRetryAfterMs(error: unknown): number | undefined {
   const direct = err["retryAfterMs"];
   if (typeof direct === "number" && Number.isFinite(direct) && direct >= 0) return Math.min(60_000, direct);
   const raw =
-    ((err["response"] as Record<string, unknown> | undefined)?.["headers"] as Record<string, unknown> | undefined)?.["retry-after"] ??
-    ((err["headers"] as Record<string, unknown> | undefined)?.["retry-after"]);
+    ((err["response"] as Record<string, unknown> | undefined)?.["headers"] as Record<string, unknown> | undefined)?.[
+      "retry-after"
+    ] ?? (err["headers"] as Record<string, unknown> | undefined)?.["retry-after"];
   if (raw === undefined) return undefined;
   const secs = Number(Array.isArray(raw) ? raw[0] : raw);
   if (!Number.isFinite(secs) || secs < 0) return undefined;