agent-accelerator 0.4.0 → 0.5.0

package/src/utils/media.ts

@@ -1,6 +1,7 @@
 // NOTE: no static node:fs import — it breaks browser bundles. Local file
 // paths are loaded via a lazy dynamic import so browsers never resolve it.
-import { bytesToBase64 } from "./base64.ts";
+import { bytesToBase64, base64ToBytes } from "./base64.ts";
+import { fetchRemoteBytes } from "./safe-io.ts";
 
 export interface NormalizedMedia {
   mimeType: string;
@@ -32,6 +33,51 @@ export function inferMimeType(input: string, fallback = "application/octet-strea
   return fallback;
 }
 
+const ascii = (bytes: Uint8Array, start: number, text: string): boolean =>
+  bytes.length >= start + text.length && [...text].every((ch, i) => bytes[start + i] === ch.charCodeAt(0));
+
+/**
+ * Identifies common image/audio/video/document formats from their magic bytes.
+ * Used when no MIME type was supplied (raw bytes, base64, extension-less or
+ * `application/octet-stream` downloads) so providers receive a real type
+ * instead of a generic one they would reject.
+ *
+ * @example `sniffMimeType(pngBytes) // "image/png"`
+ */
+export function sniffMimeType(bytes: Uint8Array): string | undefined {
+  if (bytes.length < 4) return undefined;
+  if (bytes[0] === 0x89 && ascii(bytes, 1, "PNG")) return "image/png";
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (ascii(bytes, 0, "GIF8")) return "image/gif";
+  if (ascii(bytes, 0, "RIFF") && ascii(bytes, 8, "WEBP")) return "image/webp";
+  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, "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 (bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3) return "video/webm";
+  return 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 {
+  if (explicit) return explicit;
+  const specific = candidate && !GENERIC_MIME.has(candidate.split(";")[0]!.trim().toLowerCase()) ? candidate : undefined;
+  return specific || sniffMimeType(bytes) || candidate || fallback;
+}
+
+/** Magic-byte sniff of a base64 payload from its first bytes only (no full decode). */
+function sniffBase64(b64: string): string | undefined {
+  try {
+    const head = b64.replace(/\s/g, "").slice(0, 32);
+    return sniffMimeType(base64ToBytes(head.slice(0, head.length - (head.length % 4))));
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Normalizes an image, audio, or video input into raw base64 and data URL
  */
@@ -47,7 +93,7 @@ export async function normalizeMediaInput(
   // 1. If input is ArrayBuffer or Uint8Array
   if (input instanceof Uint8Array || input instanceof ArrayBuffer) {
     const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
-    const mimeType = explicitMimeType || "application/octet-stream";
+    const mimeType = resolveMime(explicitMimeType, undefined, bytes, "application/octet-stream");
     const base64Data = bytesToBase64(bytes);
     return {
       mimeType,
@@ -70,16 +116,14 @@ export async function normalizeMediaInput(
 
   // 3. If input is a remote HTTP URL (check before base64 to avoid misclassifying URL as base64)
   if (typeof input === "string" && (input.startsWith("http://") || input.startsWith("https://"))) {
-    const response = await fetch(input);
+    // Developer-supplied URL: private hosts are allowed (intranet assets),
+    // 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})`);
     }
-    const arrayBuffer = await response.arrayBuffer();
-    const buffer = new Uint8Array(arrayBuffer);
-    const mimeType =
-      explicitMimeType ||
-      response.headers.get("content-type") ||
-      inferMimeType(input);
+    const buffer = response.bytes;
+    const mimeType = resolveMime(explicitMimeType, response.contentType, buffer, inferMimeType(input));
     const base64Data = bytesToBase64(buffer);
     return {
       mimeType,
@@ -100,7 +144,7 @@ export async function normalizeMediaInput(
     /^[A-Za-z0-9+/=\n\r]+$/.test(input.slice(0, 200)) &&
     input.length % 4 === 0
   ) {
-    const mimeType = explicitMimeType || "image/jpeg";
+    const mimeType = explicitMimeType || sniffBase64(input) || "image/jpeg";
     return {
       mimeType,
       base64Data: input.replace(/\s/g, ""),
@@ -113,7 +157,8 @@ export async function normalizeMediaInput(
     try {
       const { promises: fs } = await import("node:fs");
       const buffer = await fs.readFile(input);
-      const mimeType = explicitMimeType || inferMimeType(input);
+      const byExtension = inferMimeType(input, "");
+      const mimeType = resolveMime(explicitMimeType, byExtension, buffer, "application/octet-stream");
       const base64Data = bytesToBase64(buffer);
       return {
         mimeType,
@@ -125,7 +170,7 @@ export async function normalizeMediaInput(
       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;
       if (isMaybeBase64) {
-        const mimeType = explicitMimeType || "image/jpeg";
+        const mimeType = explicitMimeType || sniffBase64(trimmed) || "image/jpeg";
         return {
           mimeType,
           base64Data: trimmed,

package/src/utils/raw-capture.ts

@@ -0,0 +1,76 @@
+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;
+
+function byteLength(value: unknown): number {
+  try {
+    return JSON.stringify(value)?.length ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+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)
+    .filter((n): n is string => typeof n === "string");
+  return names.length > 0 ? names : undefined;
+}
+
+/** Body summary that keeps the audit-useful shape and none of the content. */
+function summarizeRequestBody(body: unknown): unknown {
+  if (body === null || body === undefined) return body;
+  const b = (typeof body === "object" ? body : {}) as Record<string, unknown>;
+  const items = Array.isArray(b["messages"]) ? b["messages"] : Array.isArray(b["input"]) ? b["input"] : undefined;
+  return {
+    redacted: true,
+    bytes: byteLength(body),
+    ...(typeof b["model"] === "string" ? { model: b["model"] } : {}),
+    ...(items ? { items: items.length } : {}),
+    ...(toolNames(b["tools"]) ? { tools: toolNames(b["tools"]) } : {}),
+    ...(b["stream"] === true ? { stream: true } : {}),
+  };
+}
+
+function summarizeResponseBody(body: unknown): unknown {
+  if (body === null || body === undefined) return body;
+  const b = (typeof body === "object" ? body : {}) as Record<string, unknown>;
+  return {
+    redacted: true,
+    bytes: byteLength(body),
+    ...(typeof b["id"] === "string" ? { id: b["id"] } : {}),
+    ...(typeof b["status"] === "string" ? { status: b["status"] } : {}),
+  };
+}
+
+/**
+ * Applies the `captureRaw` policy to a provider audit record.
+ * - `true`: keep everything (headers are always redacted by the adapters).
+ * - `"redacted"` (default): keep URL, method, headers and status, but replace
+ *   request/response BODIES with a content-free summary. Prompts, files and
+ *   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 {
+  if (!raw || mode === true) return raw;
+  const redactedMode = mode !== false; // undefined -> default "redacted"
+  const request = raw.request
+    ? {
+        url: raw.request.url,
+        method: raw.request.method,
+        headers: redactedMode ? raw.request.headers : {},
+        body: redactedMode ? summarizeRequestBody(raw.request.body) : null,
+      }
+    : raw.request;
+  const response = raw.response
+    ? {
+        status: raw.response.status,
+        statusText: raw.response.statusText,
+        headers: redactedMode ? raw.response.headers : {},
+        body: redactedMode ? summarizeResponseBody(raw.response.body) : null,
+      }
+    : undefined;
+  return { request, ...(response ? { response } : {}) } as ProviderRawData;
+}

package/src/utils/retry.ts

@@ -31,8 +31,10 @@ export function isTransientError(error: unknown): boolean {
 
 function readRetryAfterMs(error: unknown): number | undefined {
   const err = error as Record<string, unknown>;
+  // Preferred: milliseconds attached by the adapter from the Retry-After header.
+  const direct = err["retryAfterMs"];
+  if (typeof direct === "number" && Number.isFinite(direct) && direct >= 0) return Math.min(60_000, direct);
   const raw =
-    (err["retryAfterMs"] as unknown) ??
     ((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;
@@ -73,11 +75,13 @@ export async function withRetries<T>(
     signal?: AbortSignal;
     label?: { providerId?: string; modelId?: string };
     retryBudgetMs?: number;
+    baseDelayMs?: number;
   }
 ): Promise<T> {
   const maxRetries = options?.maxRetries ?? 2;
   const maxDelay = options?.maxRetryDelayMs ?? 5000;
   const budgetMs = options?.retryBudgetMs ?? 30_000;
+  const baseDelay = options?.baseDelayMs ?? 250;
   const started = Date.now();
   const fail = (error: unknown): never => {
     if (options?.label?.providerId && options?.label?.modelId) {
@@ -94,8 +98,12 @@ export async function withRetries<T>(
       if (attempt >= maxRetries || !isTransientError(error)) fail(error);
       if (Date.now() - started >= budgetMs) fail(error);
       const retryAfter = readRetryAfterMs(error);
-      const backoff = Math.min(maxDelay, 250 * 2 ** attempt + Math.random() * 100);
-      const delay = retryAfter !== undefined ? Math.min(maxDelay, Math.max(backoff, retryAfter)) : backoff;
+      const backoff = Math.min(maxDelay, baseDelay * 2 ** attempt + Math.random() * 100);
+      // A server-provided Retry-After is honored in full (it is the provider's
+      // own instruction), but never past the retry budget: waiting that long is
+      // pointless, so surface the 429 now instead of sleeping and failing anyway.
+      const delay = retryAfter !== undefined ? Math.max(backoff, retryAfter) : backoff;
+      if (retryAfter !== undefined && Date.now() - started + delay > budgetMs) fail(error);
       attempt += 1;
       await sleep(delay, options?.signal);
     }

package/src/utils/safe-io.ts

@@ -0,0 +1,252 @@
+// NOTE: no static node:fs / node:path / node:dns imports: they break browser
+// bundles. Everything Node-specific is loaded lazily inside the helpers.
+import type { Message } from "../types/message.ts";
+import { SecurityPolicyError } from "../types/errors.ts";
+
+/** Default cap for one remote media/document download (bytes). */
+export const MAX_REMOTE_FETCH_BYTES = 200_000_000;
+
+/**
+ * True when a media/document string would be read from the local filesystem
+ * by `normalizeMediaInput` (i.e. it is not a data URL, an http(s) URL, or an
+ * embedded base64 payload). Mirrors the classification order used there.
+ */
+export function isLocalPathInput(input: unknown): input is string {
+  if (typeof input !== "string" || !input) return false;
+  if (input.startsWith("data:")) return false;
+  if (input.startsWith("http://") || input.startsWith("https://")) return false;
+  if (
+    !input.includes("\\") &&
+    input.length > 100 &&
+    /^[A-Za-z0-9+/=\n\r]+$/.test(input.slice(0, 200)) &&
+    input.length % 4 === 0
+  ) {
+    return false;
+  }
+  return true;
+}
+
+const MAX_REDIRECTS = 5;
+
+/** Raised when a remote fetch is blocked by policy or exceeds its size cap. */
+export class RemoteFetchError extends SecurityPolicyError {
+  readonly reason: "blocked" | "too_large";
+  constructor(reason: "blocked" | "too_large", message: string, url?: string) {
+    super(message, url ? { url } : undefined);
+    this.name = "RemoteFetchError";
+    this.reason = reason;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Local path containment (`fileAccess.roots`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Throws {@link SecurityPolicyError} unless `target` resolves (after symlinks)
+ * inside one of `roots`. An empty `roots` list denies every local path. URL
+ * schemes other than plain paths (`file:`, `ftp:`, …) are always rejected.
+ */
+export async function assertPathAllowed(target: string, roots: readonly string[]): Promise<void> {
+  if (/^[a-z][a-z0-9+.-]+:/i.test(target)) {
+    throw new SecurityPolicyError(
+      `[Agent Accelerator] Path "${target.slice(0, 80)}" uses a URL scheme; only plain local paths or http(s) URLs are allowed.`
+    );
+  }
+  const path = await import("node:path");
+  const fs = await import("node:fs");
+  const real = (p: string): string => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  const resolved = real(path.resolve(target));
+  for (const root of roots) {
+    const base = real(path.resolve(root));
+    const rel = path.relative(base, resolved);
+    if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) return;
+  }
+  throw new SecurityPolicyError(
+    `[Agent Accelerator] Path "${target.slice(0, 120)}" is outside the allowed fileAccess roots` +
+      `${roots.length === 0 ? " (no local paths are allowed)" : ""}.`
+  );
+}
+
+const MEDIA_KEYS = ["image", "audio", "video", "file"] as const;
+
+/**
+ * Validates every local-path media part in `messages` against `roots`. Used by
+ * the loop each turn so developer-supplied parts, steered prompts and
+ * imported sessions all obey `fileAccess.roots` the same way.
+ */
+export async function enforceFileAccess(messages: Message[], roots: readonly string[]): Promise<void> {
+  for (const m of messages) {
+    if (!Array.isArray(m.content)) continue;
+    for (const part of m.content) {
+      const p = part as unknown as Record<string, unknown>;
+      const key = MEDIA_KEYS.find((k) => k === p?.type);
+      if (!key) continue;
+      const value = p[key];
+      if (isLocalPathInput(value)) await assertPathAllowed(value, roots);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Remote fetch guard (SSRF + size cap)
+// ---------------------------------------------------------------------------
+
+function ipv4Private(a: number, b: number): boolean {
+  return (
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168)
+  );
+}
+
+/** True for loopback, link-local, private, CGNAT and unique-local addresses. */
+export function isPrivateAddress(address: string): boolean {
+  const host = address.replace(/^\[|\]$/g, "").toLowerCase();
+  const v4 = host.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (v4) return ipv4Private(Number(v4[1]), Number(v4[2]));
+  if (host.includes(":")) {
+    if (host === "::" || host === "::1") return true;
+    const mapped = host.match(/^::ffff:(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+    if (mapped) return ipv4Private(Number(mapped[1]), Number(mapped[2]));
+    return /^f[cd]/.test(host) || /^fe[89ab]/.test(host);
+  }
+  return false;
+}
+
+function isPrivateHostname(host: string): boolean {
+  return (
+    host === "localhost" ||
+    host.endsWith(".localhost") ||
+    host.endsWith(".local") ||
+    host.endsWith(".internal") ||
+    isPrivateAddress(host)
+  );
+}
+
+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);
+  }
+  if (allowPrivateNetwork) return;
+  const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (isPrivateHostname(host)) {
+    throw new RemoteFetchError("blocked", `[Agent Accelerator] Refusing to fetch private/internal host "${host}".`, url.href);
+  }
+  if (/^[\d.]+$/.test(host) || host.includes(":")) return; // IP literal already checked
+  try {
+    const dns = await import("node:dns");
+    const addrs = await dns.promises.lookup(host, { all: true });
+    if (addrs.some((a) => isPrivateAddress(a.address))) {
+      throw new RemoteFetchError("blocked", `[Agent Accelerator] Host "${host}" resolves to a private/internal address.`, url.href);
+    }
+  } catch (err) {
+    if (err instanceof RemoteFetchError) throw err;
+    // Resolution failed (or non-Node runtime): fetch will surface its own error.
+  }
+}
+
+async function readCapped(res: Response, maxBytes: number, url: string): Promise<Uint8Array> {
+  const tooLarge = () =>
+    new RemoteFetchError(
+      "too_large",
+      `[Agent Accelerator] Remote resource exceeds the ${(maxBytes / 1_000_000).toFixed(0)} MB fetch cap.`,
+      url
+    );
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    try { await res.body?.cancel(); } catch {}
+    throw tooLarge();
+  }
+  if (!res.body) {
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength > maxBytes) throw tooLarge();
+    return buf;
+  }
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      try { await reader.cancel(); } catch {}
+      throw tooLarge();
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+
+/** Result of {@link fetchRemoteBytes}; `bytes` is empty when `ok` is false. */
+export interface RemoteBytes {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  contentType: string | null;
+  bytes: Uint8Array;
+}
+
+/**
+ * Fetches a URL with redirect re-validation and a hard byte cap. Redirects
+ * are followed manually (max 5) so every hop is checked. With
+ * `allowPrivateNetwork: false` loopback/LAN/link-local/cloud-metadata hosts
+ * (including DNS names that resolve to them) are refused.
+ */
+export async function fetchRemoteBytes(
+  input: string,
+  opts: { signal?: AbortSignal; maxBytes?: number; allowPrivateNetwork?: boolean } = {}
+): Promise<RemoteBytes> {
+  const maxBytes = opts.maxBytes ?? MAX_REMOTE_FETCH_BYTES;
+  const allowPrivate = opts.allowPrivateNetwork ?? false;
+  let current = new URL(input);
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    await assertRemoteUrlAllowed(current, allowPrivate);
+    const res = await fetch(current.href, { signal: opts.signal, redirect: "manual" });
+    if ((res as { type?: string }).type === "opaqueredirect") {
+      // Browser runtimes hide the Location header: only trusted callers may follow blindly.
+      if (!allowPrivate) {
+        throw new RemoteFetchError("blocked", "[Agent Accelerator] Redirects cannot be validated in this runtime.", current.href);
+      }
+      const followed = await fetch(current.href, { signal: opts.signal });
+      return {
+        ok: followed.ok,
+        status: followed.status,
+        statusText: followed.statusText,
+        contentType: followed.headers.get("content-type"),
+        bytes: followed.ok ? await readCapped(followed, maxBytes, current.href) : new Uint8Array(0),
+      };
+    }
+    const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
+    if (location) {
+      try { await res.body?.cancel(); } catch {}
+      current = new URL(location, current);
+      continue;
+    }
+    return {
+      ok: res.ok,
+      status: res.status,
+      statusText: res.statusText,
+      contentType: res.headers.get("content-type"),
+      bytes: res.ok ? await readCapped(res, maxBytes, current.href) : new Uint8Array(0),
+    };
+  }
+  throw new RemoteFetchError("blocked", `[Agent Accelerator] Too many redirects (> ${MAX_REDIRECTS}).`, input);
+}

package/src/utils/session.ts

@@ -8,26 +8,25 @@ import type { ContentPart } from "../types/message.ts";
 import { ConfigError } from "../types/errors.ts";
 
 /**
- * Creates or formats a unique session ID for prompt caching affinity (clamped to 64 chars like agent-accel)
- */
-/**
- * Creates a unique, provider-safe session ID for cache affinity.
+ * Creates a unique, provider-safe session ID for cache affinity: a bare random
+ * UUID by default, or `${prefix}-<uuid>` when a prefix is given (clamped to 64 chars).
  *
- * @example `const sessionId = createSessionId("checkout");`
+ * @example `const sessionId = createSessionId();`
  */
-export function createSessionId(prefix = "accel"): string {
+export function createSessionId(prefix?: string): string {
+  const head = prefix ? `${prefix}-` : "";
   let id: string;
   try {
     const webCrypto =
       (globalThis as any)?.crypto ?? (typeof crypto !== "undefined" ? crypto : undefined);
     if (webCrypto && typeof webCrypto.randomUUID === "function") {
-      id = `${prefix}-${webCrypto.randomUUID()}`;
+      id = `${head}${webCrypto.randomUUID()}`;
     } else {
       throw new Error("no randomUUID");
     }
   } catch {
     // Fallback — still clamp
-    id = `${prefix}-${Math.random().toString(36).slice(2, 11)}-${Date.now().toString(36)}`;
+    id = `${head}${Math.random().toString(36).slice(2, 11)}-${Date.now().toString(36)}`;
   }
   return clampCacheKey(id) || id;
 }

package/src/data/README.md

@@ -1,84 +0,0 @@
-# Model Catalog Cache (`src/data/`)
-
-This directory is the local destination for the dynamic model catalog cache used by **Agent Accelerator**.
-
-Agent Accelerator references a catalog of **7,500+ models across 200+ providers** for token limits, context windows, modality support, reasoning configurations, and per-token pricing (input, output, cache-read, cache-write).
-
----
-
-## Zero-Bloat Distribution Architecture
-
-To keep the repository and published npm/Bun package lightweight and blazing fast:
-
-1. **Excluded from Production Package & Git**:
-   * The ~4.5 MB full catalog snapshot (`models.dev.json`) is **never** committed to git and is **excluded** from the npm/Bun distribution bundle.
-   * The file is tracked in `.gitignore` and `.npmignore`.
-
-2. **Dynamic 12-Hour Automated TTL Cache**:
-   * On agent execution (`runAgentLoop` / `streamAgentLoop`), Agent Accelerator checks the status of `src/data/models.dev.json`.
-   * **Cache Hit (< 12h)**: Instant memory/disk load with zero network overhead.
-   * **Cache Miss / Expired (≥ 12h)**: Automatically downloads the latest catalog directly from `https://models.dev/api.json`, caches it to `src/data/models.dev.json`, and loads the catalog into memory.
-   * **Resilience**: If an existing cache exists on disk, temporary upstream network issues will safely continue using the local cached copy.
-
----
-
-## Developer Controls & Management
-
-### 1. CLI Script
-
-You can manually inspect or refresh the model catalog anytime via the developer CLI script:
-
-```bash
-# Refresh catalog if expired (or download if missing)
-bun run update-models
-
-# Force download regardless of age
-bun run update-models --force
-
-# Custom TTL (e.g., 24 hours)
-bun src/update-models.ts --ttl=24h
-```
-
----
-
-### 2. Programmatic API
-
-All catalog cache lifecycle controls are exported from the root package:
-
-```typescript
-import {
-  refreshModelCatalog,
-  ensureModelCatalogFresh,
-  getCatalogStatus,
-  setCatalogTTL,
-  getModelFromCatalog,
-} from "agent-accelerator";
-
-// 1. Check current cache status
-const status = getCatalogStatus();
-console.log(status);
-// {
-//   isExpired: false,
-//   cachedAt: 1773400000000,
-//   ttlMs: 43200000,
-//   modelCount: 7696,
-//   providerCount: 213,
-//   source: "cache"
-// }
-
-// 2. Refresh on-demand (e.g. in a cron job or startup hook)
-await refreshModelCatalog({ force: true });
-
-// 3. Customize runtime TTL (e.g., 6 hours)
-setCatalogTTL(6 * 60 * 60 * 1000);
-```
-
----
-
-## Structure
-
-```text
-src/data/
-├── README.md               # This documentation
-└── models.dev.json         # Auto-generated on first run (gitignored, excluded from bundle)
-```