agent-accelerator 0.4.5 → 0.5.0

package/src/utils/cache.ts

@@ -71,7 +71,7 @@ export interface CreateExplicitCacheOptions {
 
 /**
  * Creates an explicit cached content object using Google Gemini's cachedContents API.
- * REST: POST https://generativelanguage.googleapis.com/v1beta/cachedContents?key=...
+ * REST: POST https://generativelanguage.googleapis.com/v1beta/cachedContents (key in the `x-goog-api-key` header)
  */
 /**
  * Creates a Google Gemini cachedContents resource through the REST API.
@@ -125,11 +125,13 @@ export async function createExplicitCache(
     (payload as any).tool_config = options.toolConfig;
   }
 
-  const url = `${baseUrl}/cachedContents?key=${apiKey}`;
+  // The key travels in a header, never in the URL (URLs end up in proxy and access logs).
+  const url = `${baseUrl}/cachedContents`;
   const response = await fetch(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
+      "x-goog-api-key": apiKey,
     },
     body: JSON.stringify(payload),
   });
@@ -152,8 +154,15 @@ export async function createExplicitCache(
 /** Header-name deny-list (case-insensitive substring match). */
 const REDACT_HEADER_SUBSTRINGS = ["key", "token", "secret", "cookie", "authorization"];
 
-/** Secret-looking value prefixes. */
-const REDACT_VALUE_PREFIXES = ["sk-", "AIza", "gsk-", "xox-"];
+/**
+ * Credential-looking values. Anchored on a non-alphanumeric boundary so plain
+ * words that merely contain "sk-" (e.g. `Task-Manager`, `Disk-Cache`) are NOT
+ * redacted, while `sk-…`, `gsk_…`, `xoxb-…` and `AIza…` tokens are.
+ */
+const SENSITIVE_VALUE_PATTERNS: RegExp[] = [
+  /(^|[^A-Za-z0-9])(sk|gsk|xox[a-z]?)[-_][A-Za-z0-9_-]{8,}/,
+  /(^|[^A-Za-z0-9])AIza[A-Za-z0-9_-]{10,}/,
+];
 
 function headerNameIsSensitive(name: string): boolean {
   const lower = String(name ?? "").toLowerCase();
@@ -163,7 +172,7 @@ function headerNameIsSensitive(name: string): boolean {
 function valueLooksSensitive(value: unknown): boolean {
   if (typeof value !== "string") return false;
   const v = value.trim();
-  if (REDACT_VALUE_PREFIXES.some((p) => v.includes(p))) return true;
+  if (SENSITIVE_VALUE_PATTERNS.some((re) => re.test(v))) return true;
   // Bearer-style long tokens: "Bearer <20+ chars>"
   if (/^bearer\s+\S{20,}/i.test(v)) return true;
   return false;

package/src/utils/documents.ts

@@ -6,6 +6,7 @@ import { normalizeMediaInput } from "./media.ts";
 import { base64ToBytes } from "./base64.ts";
 import { escapeXml } from "./serialization.ts";
 import { getModelFromCatalog } from "../models/catalog.ts";
+import { assertPathAllowed, fetchRemoteBytes, RemoteFetchError } from "./safe-io.ts";
 
 /**
  * Client-side document conversion (anydoc engine).
@@ -104,6 +105,16 @@ export interface ConvertDocumentOptions {
   maxChars?: number;
   /** Abort signal honored by the remote-fetch leg. */
   signal?: AbortSignal;
+  /**
+   * Allowed local roots for path inputs (see `AgentConfig.fileAccess`).
+   * Omitted = unrestricted (developer-supplied inputs); `[]` denies every path.
+   */
+  roots?: readonly string[];
+  /**
+   * Input is model/user-controlled: private/internal hosts are refused for
+   * remote URLs. The built-in tool always sets this.
+   */
+  untrusted?: boolean;
 }
 
 /** Normalized conversion result (pre-XML-envelope). */
@@ -296,7 +307,23 @@ export async function convertDocumentInput(
   try {
     // Remote URL leg: fetch bytes first (anydoc reads files, not URLs).
     if (typeof input === "string" && isHttpUrl(input)) {
-      const res = await fetch(input, { signal: opts.signal });
+      let res;
+      try {
+        res = await fetchRemoteBytes(input, {
+          signal: opts.signal,
+          maxBytes: MAX_DOCUMENT_FETCH_BYTES,
+          allowPrivateNetwork: !opts.untrusted,
+        });
+      } catch (err) {
+        if (err instanceof RemoteFetchError) {
+          throw new DocumentConversionError(
+            err.reason === "too_large" ? "resourceLimit" : "blocked",
+            `[Agent Accelerator] Could not download document "${input}": ${err.message}`,
+            input
+          );
+        }
+        throw err;
+      }
       if (!res.ok) {
         throw new DocumentConversionError(
           "io",
@@ -304,19 +331,12 @@ export async function convertDocumentInput(
           input
         );
       }
-      const buf = new Uint8Array(await res.arrayBuffer());
-      if (buf.byteLength > MAX_DOCUMENT_FETCH_BYTES) {
-        throw new DocumentConversionError(
-          "resourceLimit",
-          `[Agent Accelerator] Remote document "${input}" is ${(buf.byteLength / 1_000_000).toFixed(1)} MB, over the ${MAX_DOCUMENT_FETCH_BYTES / 1_000_000} MB fetch cap.`,
-          input
-        );
-      }
+      const buf = res.bytes;
       const name = filenameOpt || basenameOf(input);
       const inferred = resolveDocumentFormat({
         filename: name,
         format: opts.format,
-        mimeType: res.headers.get("content-type") || opts.mimeType,
+        mimeType: res.contentType || opts.mimeType,
       });
       let wire = canonicalizeFormat(anydoc, inferred);
       if (!wire) {
@@ -340,6 +360,17 @@ export async function convertDocumentInput(
 
     // Local path leg: the engine reads + detects from the path itself.
     if (typeof input === "string" && looksLikePath(input)) {
+      if (opts.roots) {
+        try {
+          await assertPathAllowed(input, opts.roots);
+        } catch (err) {
+          throw new DocumentConversionError(
+            "blocked",
+            `[Agent Accelerator] Could not read document "${input.slice(0, 120)}": ${err instanceof Error ? err.message : String(err)}`,
+            input
+          );
+        }
+      }
       const name = filenameOpt || basenameOf(input);
       const markdown = await anydoc.toMarkdown(input);
       const inferred = resolveDocumentFormat({ filename: name, format: opts.format });
@@ -424,7 +455,7 @@ export function modelSupportsFileInput(providerId: string, modelId: string): boo
  */
 export async function preprocessFilePartsForBypass(
   messages: Message[],
-  opts: { providerId: string; modelId: string; signal?: AbortSignal; maxChars?: number }
+  opts: { providerId: string; modelId: string; signal?: AbortSignal; maxChars?: number; roots?: readonly string[] }
 ): Promise<void> {
   if (modelSupportsFileInput(opts.providerId, opts.modelId)) return;
   for (const m of messages) {
@@ -451,6 +482,7 @@ export async function preprocessFilePartsForBypass(
           mimeType,
           maxChars: opts.maxChars,
           signal: opts.signal,
+          roots: opts.roots,
         });
         const destination =
           filename ||
@@ -466,8 +498,75 @@ export async function preprocessFilePartsForBypass(
   }
 }
 
+/** Options for {@link createConvertDocumentTool}. */
+export interface ConvertDocumentToolOptions {
+  /**
+   * Local roots the model may read from. Defaults to `[process.cwd()]`; pass
+   * `[]` to deny every local path (URLs only).
+   */
+  roots?: readonly string[];
+}
+
+/**
+ * Builds the model-callable document converter. The `destination` is chosen
+ * by the model, so it is always treated as untrusted: local paths must sit
+ * inside `roots`, and remote URLs may not target private/internal hosts.
+ *
+ * @example `const tool = createConvertDocumentTool({ roots: ["./docs"] });`
+ */
+export function createConvertDocumentTool(options: ConvertDocumentToolOptions = {}): ToolDefinition {
+  return tool({
+    name: "convert_document_to_markdown",
+    description:
+      "Convert a document file to Markdown text. Call this when the user provides a document file path or URL, or asks about the contents of a document. " +
+      "Supported formats: PDF (.pdf), Word (.doc, .docx, .docm), PowerPoint (.ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm), " +
+      "Excel (.xls, .xlsx, .xlsm, .xlsb), OpenDocument (.odt, .ods, .odp), RTF (.rtf), EPUB (.epub), CSV (.csv). " +
+      "Returns the content wrapped in <Document name destination> tags. Do not use for images, audio, or video.",
+    input: z.object({
+      destination: z
+        .string()
+        .min(1)
+        .describe("Local file path or http(s) URL of the document to convert."),
+      format: z
+        .string()
+        .optional()
+        .describe(
+          "Explicit format override, e.g. 'pdf', 'docx', 'xlsx', 'csv'. Inferred from the destination when omitted."
+        ),
+      maxChars: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Maximum Markdown characters to return (default 100000). Excess is truncated with a marker."),
+    }),
+    timeoutMs: 60_000,
+    execute: async ({ destination, format, maxChars }, ctx) => {
+      const dest = String(destination ?? "").trim();
+      if (!dest) {
+        return "Error: convert_document_to_markdown needs a non-empty destination (local file path or http(s) URL).";
+      }
+      try {
+        const doc = await convertDocumentInput(dest, {
+          format,
+          maxChars,
+          signal: ctx?.signal,
+          untrusted: true,
+          roots: options.roots ?? [process.cwd()],
+        });
+        return buildDocumentXml(doc.name, dest, doc.markdown);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return `Error: ${detail}`;
+      }
+    },
+  });
+}
+
 /**
- * Built-in model-callable document converter. Register it and move on:
+ * Built-in model-callable document converter with the default policy (local
+ * paths limited to the working directory, no private-network URLs). Use
+ * {@link createConvertDocumentTool} to choose other roots.
  *
  * @example
  * ```ts
@@ -475,43 +574,4 @@ export async function preprocessFilePartsForBypass(
  * const agent = new Agent({ model, tools: { convert_document_to_markdown } });
  * ```
  */
-export const convert_document_to_markdown: ToolDefinition = tool({
-  name: "convert_document_to_markdown",
-  description:
-    "Convert a document file to Markdown text. Call this when the user provides a document file path or URL, or asks about the contents of a document. " +
-    "Supported formats: PDF (.pdf), Word (.doc, .docx, .docm), PowerPoint (.ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm), " +
-    "Excel (.xls, .xlsx, .xlsm, .xlsb), OpenDocument (.odt, .ods, .odp), RTF (.rtf), EPUB (.epub), CSV (.csv). " +
-    "Returns the content wrapped in <Document name destination> tags. Do not use for images, audio, or video.",
-  input: z.object({
-    destination: z
-      .string()
-      .min(1)
-      .describe("Local file path or http(s) URL of the document to convert."),
-    format: z
-      .string()
-      .optional()
-      .describe(
-        "Explicit format override, e.g. 'pdf', 'docx', 'xlsx', 'csv'. Inferred from the destination when omitted."
-      ),
-    maxChars: z
-      .number()
-      .int()
-      .positive()
-      .optional()
-      .describe("Maximum Markdown characters to return (default 100000). Excess is truncated with a marker."),
-  }),
-  timeoutMs: 60_000,
-  execute: async ({ destination, format, maxChars }, ctx) => {
-    const dest = String(destination ?? "").trim();
-    if (!dest) {
-      return "Error: convert_document_to_markdown needs a non-empty destination (local file path or http(s) URL).";
-    }
-    try {
-      const doc = await convertDocumentInput(dest, { format, maxChars, signal: ctx?.signal });
-      return buildDocumentXml(doc.name, dest, doc.markdown);
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      return `Error: ${detail}`;
-    }
-  },
-});
+export const convert_document_to_markdown: ToolDefinition = createConvertDocumentTool();

package/src/utils/errors.ts

@@ -86,6 +86,17 @@ export function toConciseProviderError(error: unknown, providerId: string, model
     ...(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?.code === "string" || typeof err?.code === "number") && err.code !== ""
+      ? { code: { 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.
+    ...(typeof err?.retryAfterMs === "number" && Number.isFinite(err.retryAfterMs)
+      ? { retryAfterMs: { value: err.retryAfterMs, enumerable: false } }
+      : {}),
     ...(typeof (err as { raw?: unknown })?.raw === "string"
       ? { raw: { value: (err as { raw: string }).raw.slice(0, 500), enumerable: false } }
       : {}),

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.4.5";
+  return "0.5.0";
 }
 
 function getAgentAccelUserAgent(): string {
@@ -55,9 +55,9 @@ export interface AttributionConfig {
 let attribution: AttributionConfig = {};
 
 /**
- * Configures global attribution headers. Defaults to none (no hardcoded
- * site); OpenRouter keeps its legacy `sashvat.com` / `Agent Accelerator`
- * fallback when no custom attribution is set (backward compat).
+ * Configures global attribution headers (OpenRouter `HTTP-Referer` / `X-Title`).
+ * Defaults to none: nothing is sent unless you call this, so your traffic is
+ * never credited to a site or app you did not choose.
  * @example `setAttribution({ referer: "https://example.com", title: "My App" });`
  */
 export function setAttribution(cfg: AttributionConfig): void {
@@ -151,9 +151,8 @@ function stripForBrowser(headers: Record<string, string>): Record<string, string
 /**
  * Builds provider-specific session, cache-affinity, and attribution headers.
  *
- * Q-17: attribution is configurable via `setAttribution()` (default none).
- * OpenRouter keeps its legacy `https://sashvat.com` / `Agent Accelerator`
- * fallback when no custom attribution is set. Custom (non-first-class)
+ * Q-17: attribution is configurable via `setAttribution()` (default none; no
+ * referer/title is ever sent unless you set one). Custom (non-first-class)
  * prefixes receive minimal `x-session-id`/`x-client-request-id` affinity only
  * (no `session_id` alias, no attribution) when a session id is present.
  * `customHeaders` merge case-insensitively against canonical names.
@@ -193,14 +192,18 @@ export function buildSessionHeaders(
     return key !== undefined ? headers[key] : undefined;
   };
 
+  // OpenRouter app attribution is strictly opt-in (`setAttribution`): by default
+  // a user's traffic is not credited to any third-party app or site.
+  const applyOpenRouterAttribution = (): void => {
+    if (attr.referer !== undefined && getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = attr.referer;
+    if (attr.title !== undefined && getHeader("X-Title") === undefined) headers["X-Title"] = attr.title;
+  };
+
   if (sessionId && !browser) {
     if (provider === "openrouter") {
       setHeaderCaseInsensitive(headers, "x-session-id", sessionId);
       setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
-      const referer = attr.referer ?? "https://sashvat.com";
-      const title = attr.title ?? "Agent Accelerator";
-      if (getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = referer;
-      if (getHeader("X-Title") === undefined) headers["X-Title"] = title;
+      applyOpenRouterAttribution();
     } else if (provider === "google") {
       if (getHeader("x-goog-api-client") === undefined) {
         headers["x-goog-api-client"] = "agent-accel/1.0";
@@ -219,10 +222,7 @@ export function buildSessionHeaders(
       setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
     }
   } else if (provider === "openrouter") {
-    const referer = attr.referer ?? "https://sashvat.com";
-    const title = attr.title ?? "Agent Accelerator";
-    if (getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = referer;
-    if (getHeader("X-Title") === undefined) headers["X-Title"] = title;
+    applyOpenRouterAttribution();
   }
 
   if (provider === "google" && !browser && getHeader("x-goog-api-client") === undefined) {

package/src/utils/home.ts

@@ -0,0 +1,30 @@
+import * as path from "node:path";
+import { getEnv } from "./env.ts";
+
+/**
+ * The Agent Accelerator home: ONE folder that holds everything the SDK stores
+ * (`sessions/`, `scheduled_actions/`, `telemetry/`, `catalog/`), so nothing is
+ * scattered across the project or the package.
+ */
+let defaultHome: string | undefined;
+const listeners = new Set<() => void>();
+
+/**
+ * Sets where the home lives for every Agent created afterwards, so nothing lands
+ * in the working directory unless you want it there. Call once at startup;
+ * `setHome()` clears it.
+ */
+export function setHome(dir?: string): void {
+  defaultHome = dir ? path.resolve(dir) : undefined;
+  for (const fn of listeners) fn();
+}
+
+/** The home folder: explicit `home`, else `setHome()`, else `AGENT_ACCEL_HOME`, else `.agent-accel/` in the working directory. */
+export function resolveHome(home?: string): string {
+  return path.resolve(home || defaultHome || getEnv("AGENT_ACCEL_HOME") || ".agent-accel");
+}
+
+/** Runs `fn` whenever `setHome` changes the default (the catalog cache reloads from the new place). */
+export function onHomeChange(fn: () => void): void {
+  listeners.add(fn);
+}

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);
     }