agent-accelerator 0.4.0 → 0.5.0

package/src/providers/openrouter.ts

@@ -52,11 +52,18 @@ import {
   redactedHeaders,
   readErrorPayload,
   incompleteStreamError,
+  hasTruncatedToolArguments,
   combinedSignal,
   timeoutFor,
+  hasAuthHeader,
+  clampToolCallId,
+  openStreamResponse,
+  retryOptionsFrom,
+  headersToRecord,
+  parseRetryAfterMs,
 } from "./shared.ts";
 import { createGenericModelSpec } from "../models/catalog.ts";
-import { getModelFromCatalog, getModelsForProvider } from "../models/catalog.ts";
+import { getModelFromCatalog, getModelsForProvider, modelSupportsStructuredOutput } from "../models/catalog.ts";
 import {
   mapThinkingLevelToOpenRouterChat,
   mapServiceTierToOpenRouter,
@@ -64,6 +71,12 @@ import {
   mapToolChoiceToOpenRouterChat,
   noteProviderTurn,
   parseStreamedToolArguments,
+  selectRawArguments,
+  mapOutputToOpenRouterChat,
+  mapGenerationParamsToChat,
+  normalizeStructuredOutput,
+  augmentSystemPromptWithStructuredOutput,
+  emitProviderWarning,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -102,6 +115,7 @@ interface ChatRequestBody {
   service_tier?: string;
   session_id?: string;
   plugins?: Array<{ id: string }>;
+  response_format?: { type: "json_schema"; json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string } };
   stream?: boolean;
   [k: string]: unknown;
 }
@@ -193,7 +207,10 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
 }
 
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
-  return options?.apiKey || getApiKey("openrouter", undefined, options?.env);
+  const key = getApiKey("openrouter", options?.apiKey, options?.env);
+  if (key) return key;
+  if (hasAuthHeader(options?.headers)) return "unused";
+  return undefined;
 }
 
 /**
@@ -352,11 +369,17 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
     messages.push({ role: "system", content: context.systemPrompt });
   }
   let hasFiles = false;
+  let lastRole: string | null = "system";
   for (const m of context.messages) {
     if (m.role === "system") continue;
     if (m.role === "user") {
+      // Strict routes reject `user` directly after `tool`: bridge with a
+      // synthetic assistant turn (pi api/openai-completions.ts:1233).
+      if (lastRole === "tool") {
+        messages.push({ role: "assistant", content: "I have processed the tool results." });
+      }
       if (typeof m.content === "string") {
-        if (m.content) messages.push({ role: "user", content: m.content });
+        if (m.content) { messages.push({ role: "user", content: m.content }); lastRole = "user"; }
       } else {
         const { blocks, fileUrls, hasFiles: hf } = await contentPartsToBlocks(m.content);
         if (hf) hasFiles = true;
@@ -364,7 +387,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
         for (const url of fileUrls) {
           blocks.push({ type: "text", text: url });
         }
-        if (blocks.length > 0) messages.push({ role: "user", content: blocks });
+        if (blocks.length > 0) { messages.push({ role: "user", content: blocks }); lastRole = "user"; }
       }
     } else if (m.role === "assistant") {
       if (typeof m.content === "string") {
@@ -378,7 +401,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
       for (const part of m.content) {
         if (part.type === "tool_call") {
           calls.push({
-            id: part.callId || part.id,
+            id: clampToolCallId(part.callId || part.id),
             type: "function",
             function: { name: part.name, arguments: JSON.stringify(part.arguments || {}) },
           });
@@ -388,20 +411,25 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
         // Prior-turn reasoning is NOT resent: chat history is messages +
         // tool calls only (documented decision; avoids strict-route 400s).
       }
+      // Skip empty assistant turns (no text + no tool calls): strict
+      // routes reject them, and they carry no signal (pi drop rule).
+      if (texts.length === 0 && calls.length === 0) continue;
       messages.push({
         role: "assistant",
         content: texts.length > 0 ? texts.join("\n") : null,
         ...(calls.length > 0 ? { tool_calls: calls } : {}),
       });
+      lastRole = "assistant";
     } else if (m.role === "tool") {
       if (typeof m.content === "string") {
         const queue = (m.name && idsByName.get(m.name)) || [];
         messages.push({
           role: "tool",
-          tool_call_id: queue.shift() || newToolCallId(),
+          tool_call_id: clampToolCallId(queue.shift() || newToolCallId()),
           content: m.content,
           name: m.name,
         });
+        lastRole = "tool";
         continue;
       }
       if (!Array.isArray(m.content)) continue;
@@ -409,10 +437,11 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
         if (part.type === "tool_result") {
           messages.push({
             role: "tool",
-            tool_call_id: pairing.get(part.id) || part.id,
+            tool_call_id: clampToolCallId(pairing.get(part.id) || part.id),
             content: resultToOutput(part.result),
             name: part.name,
           });
+          lastRole = "tool";
         }
       }
     }
@@ -490,7 +519,7 @@ function parseResponse(
   for (const tc of message?.tool_calls ?? []) {
     const args = parseArguments(tc.function?.arguments);
     toolCalls.push({
-      id: tc.id || newToolCallId(),
+      id: tc.id && !tc.id.includes("|") && tc.id.length <= 40 ? tc.id : clampToolCallId(tc.id || newToolCallId()),
       name: tc.function?.name || "unknown",
       arguments: args,
       rawArguments:
@@ -559,7 +588,33 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     const serviceTier = mapServiceTierToOpenRouter(options?.serviceTier);
     applyCacheForOpenRouter(options?.cache, `openrouter/${modelId}`);
 
-    const { messages, hasFiles } = await fullHistoryMessages(context);
+    // Structured outputs: native `response_format` when supported, else
+    // emulated via system-prompt instruction + client validation (catalog
+    // `structured_output: false` models would 400 on the wire shape).
+    let effectiveContext = context;
+    let outputEmulated = false;
+    let outputSpec: import("../types/model.ts").StructuredOutputSpec | undefined;
+    try {
+      outputSpec = normalizeStructuredOutput(options?.output ?? (options as { outputSchema?: unknown })?.outputSchema);
+    } catch {
+      // why: invalid output shapes fail fast at Agent construction/loop validation.
+      outputSpec = undefined;
+    }
+    if (outputSpec && !modelSupportsStructuredOutput("openrouter", modelId)) {
+      outputEmulated = true;
+      effectiveContext = {
+        ...context,
+        systemPrompt: augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec),
+      };
+      emitProviderWarning({
+        provider: "openrouter",
+        capability: "structured output",
+        requested: `${outputSpec.name} (openrouter/${modelId})`,
+        reason: "the catalog reports structured_output: false for this model, so native response_format is unsupported.",
+        fallback: "emulated JSON instruction + client validation (no response_format is sent)",
+      });
+    }
+    const { messages, hasFiles } = await fullHistoryMessages(effectiveContext);
     const body: ChatRequestBody = {
       model: modelId,
       messages,
@@ -573,12 +628,22 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     if (toolChoice !== undefined) body.tool_choice = toolChoice;
     if (effort) body.reasoning = { effort };
     if (serviceTier) body.service_tier = serviceTier;
+    // Documented Chat Completions generation controls (only those the caller set).
+    Object.assign(body, mapGenerationParamsToChat(options));
+    // Structured outputs: Chat Completions `response_format{type:json_schema,json_schema}`.
+    // Skipped when emulated (unsupported model): instruction already in messages.
+    if (outputSpec && !outputEmulated) {
+      try {
+        const mapped = mapOutputToOpenRouterChat(outputSpec);
+        if (mapped) body.response_format = mapped.response_format;
+      } catch {
+        // why: invalid output shapes fail fast at Agent construction/loop validation.
+      }
+    }
     // PDF ingestion is a documented plugin, not a message shape: enable it
     // only when file parts are present (never by default).
     if (hasFiles) body.plugins = [{ id: "file-parser" }];
-    // No temperature/top_p/max_tokens/stop/response_format/user/seed knobs
-    // (no canonical options exist; omitting also keeps provider cache keys
-    // stable). No store/previous_response_id/conversation: they do not exist
+    // No store/previous_response_id/conversation: they do not exist
     // on this endpoint.
     // Session affinity: top-level `session_id` is the documented sticky-routing
     // key on Chat Completions (prompt-caching guide) and takes precedence over
@@ -608,7 +673,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
       if (INTERNAL_HEADERS.has(k.toLowerCase())) delete headers[k];
     }
     setHeaderCaseInsensitive(headers, "Content-Type", "application/json");
-    setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
+    if (apiKey !== "unused") setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
@@ -622,7 +687,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
   ): Promise<{ status: number; statusText: string; headers: Record<string, string>; text: string }> {
     const { signal: effective, cleanup } = combinedSignal(signal, timeoutFor(options as { timeoutMs?: number } | undefined));
     try {
-      const res = await fetch(url, this.requestInit(body, options, apiKey, sessionId, effective));
+      const res = await (options?.fetch ?? fetch)(url, this.requestInit(body, options, apiKey, sessionId, effective));
       const text = await res.text();
       const headers: Record<string, string> = {};
       res.headers.forEach((v, k) => {
@@ -638,17 +703,27 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     status: number,
     url: string,
     bodyText: string,
-    modelId: string
+    modelId: string,
+    headers?: Record<string, string>
   ): void {
     if (status >= 200 && status < 300) return;
-    const { message, code, errorType } = readErrorPayload(bodyText);
-    const err: Record<string, unknown> & Error = new Error(message) as Record<string, unknown> & Error;
+    const { message, code, errorType, raw } = readErrorPayload(bodyText);
+    const hint =
+      status === 401
+        ? " Check OPENROUTER_API_KEY (no quotes/spaces, correct provider) and that the key is loaded (bun --env-file=.env.local)."
+        : "";
+    const fullMessage = `${message}${hint}`;
+    const err: Record<string, unknown> & Error = new Error(fullMessage) as Record<string, unknown> & Error;
     (err as Record<string, unknown>)["statusCode"] = status;
     (err as Record<string, unknown>)["status"] = status;
     (err as Record<string, unknown>)["responseBody"] = bodyText.slice(0, 500);
     (err as Record<string, unknown>)["url"] = url.split("?")[0];
+    (err as Record<string, unknown>)["data"] = { error: { message: fullMessage } };
     if (code !== undefined) (err as Record<string, unknown>)["code"] = code;
     if (errorType) (err as Record<string, unknown>)["errorType"] = errorType;
+    if (raw) (err as Record<string, unknown>)["raw"] = raw;
+    const retryAfterMs = parseRetryAfterMs(headers);
+    if (retryAfterMs !== undefined) (err as Record<string, unknown>)["retryAfterMs"] = retryAfterMs;
     throw toConciseProviderError(err, "openrouter", modelId);
   }
 
@@ -695,7 +770,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
 
     const doCall = async (): Promise<ProviderGenerateResult> => {
       const res = await this.doFetch(url, body, options, apiKey, sessionId, options?.signal);
-      this.throwIfError(res.status, url, res.text, clean);
+      this.throwIfError(res.status, url, res.text, clean, res.headers);
       let response: ChatResponse;
       try {
         response = JSON.parse(res.text) as ChatResponse;
@@ -723,8 +798,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
 
     try {
       return await withRetries(doCall, {
-        maxRetries: options?.maxRetries,
-        maxRetryDelayMs: options?.maxRetryDelayMs,
+        ...retryOptionsFrom(options),
         signal: options?.signal,
         label: { providerId: "openrouter", modelId: clean },
       });
@@ -792,25 +866,30 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         };
 
         const streamTimeoutMs = timeoutFor(options as { timeoutMs?: number } | undefined);
-        const streamTimeoutTimer =
-          streamTimeoutMs && streamTimeoutMs > 0
-            ? setTimeout(() => {
-                try {
-                  linked.abort();
-                } catch {}
-              }, streamTimeoutMs)
-            : undefined;
-        let res: Response;
-        try {
-          res = await fetch(url, this.requestInit(body, options, apiKey, sessionId, linked.signal));
-        } finally {
-          if (streamTimeoutTimer) clearTimeout(streamTimeoutTimer);
-        }
-        if (!res.ok || !res.body) {
-          const text = !res.ok ? await res.text().catch(() => "") : "";
-          if (!res.ok) this.throwIfError(res.status, url, text, clean);
-          throw toConciseProviderError(new Error("OpenRouter streaming response had no body"), "openrouter", clean);
-        }
+        // Transient failures (429/5xx/network) are retried here, before the
+        // first byte; once the stream is live it is never retried.
+        const res = await openStreamResponse({
+          fetchOnce: async () => {
+            const timer =
+              streamTimeoutMs && streamTimeoutMs > 0
+                ? setTimeout(() => {
+                    try {
+                      linked.abort();
+                    } catch {}
+                  }, streamTimeoutMs)
+                : undefined;
+            try {
+              return await (options?.fetch ?? fetch)(url, this.requestInit(body, options, apiKey, sessionId, linked.signal));
+            } finally {
+              if (timer) clearTimeout(timer);
+            }
+          },
+          onHttpError: (r, text) => this.throwIfError(r.status, url, text, clean, headersToRecord(r.headers)),
+          noBodyError: () => toConciseProviderError(new Error("OpenRouter streaming response had no body"), "openrouter", clean),
+          retry: retryOptionsFrom(options),
+          signal: linked.signal,
+          label: { providerId: "openrouter", modelId: clean },
+        });
         const responseHeaders: Record<string, string> = {};
         res.headers.forEach((v, k) => {
           responseHeaders[k] = v;
@@ -819,7 +898,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         eventStream.push({ type: "start", raw: { request: rawRequest } } as never);
 
         const parser = new SSEParser();
-        const reader = res.body.getReader();
+        const reader = res.body!.getReader(); // openStreamResponse guarantees a body
         const decoder = new TextDecoder();
         let text = "";
         let thinking = "";
@@ -995,10 +1074,10 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         for (const c of calls.values()) {
           const args = parseStreamedToolArguments(c.startArgs, c.deltaArgs);
           const record: ToolCallRecord = {
-            id: c.id || newToolCallId(),
+            id: c.id && !c.id.includes("|") && c.id.length <= 40 ? c.id : clampToolCallId(c.id || newToolCallId()),
             name: c.name,
             arguments: args,
-            rawArguments: c.startArgs + c.deltaArgs,
+            rawArguments: selectRawArguments(c.startArgs, c.deltaArgs),
           };
           toolCalls.push(record);
           eventStream.push({ type: "tool_call_complete", toolCall: record });
@@ -1027,6 +1106,13 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           eventStream.fail(incompleteStreamError("openrouter", clean));
           return;
         }
+        // Refuse unfinished tool calls whose args never parsed (output_item.done
+        // never arrived): truncated `{raw}` must not reach the executor (pi
+        // api/openai-responses-shared.ts:766 rule). Non-SSE mocks preserve legacy.
+        if (!hasTerminal && toolCalls.some((c) => hasTruncatedToolArguments(c.arguments)) && isSSEPayload) {
+          eventStream.fail(incompleteStreamError("openrouter", clean));
+          return;
+        }
 
         const cleanThinking = cleanThinkingEarly;
         const finalResponse = new AgentResponse({
@@ -1052,8 +1138,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         const isAbort =
           linked.signal.aborted ||
           eventStream.isCancelled() ||
-          (raw as { name?: string }).name === "AbortError" ||
-          /abort|cancell?ed/i.test(String((raw as { message?: string }).message ?? raw));
+          (raw as { name?: string }).name === "AbortError";
         eventStream.fail(
           isAbort ? Object.assign(new Error("Stream aborted"), { name: "AbortError" }) : raw
         );

package/src/providers/shared.ts

@@ -6,8 +6,11 @@
  * across the four REST transports, plus timeout/signal and id helpers.
  */
 import { toConciseProviderError } from "../utils/errors.ts";
+import { withRetries } from "../utils/retry.ts";
+import { redactHeadersCentral } from "../utils/cache.ts";
+import { TRUNCATED_ARGS_KEY, isTruncatedArguments } from "../types/tool.ts";
 
-/** Parses a JSON tool-argument string; non-objects degrade to `{ raw }`. */
+/** Parses a JSON tool-argument string; non-objects degrade to the truncated-arguments marker. */
 export function parseArguments(raw: string | undefined): Record<string, unknown> {
   if (!raw) return {};
   try {
@@ -15,9 +18,9 @@ export function parseArguments(raw: string | undefined): Record<string, unknown>
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       return parsed as Record<string, unknown>;
     }
-    return { raw };
+    return { [TRUNCATED_ARGS_KEY]: raw };
   } catch {
-    return { raw };
+    return { [TRUNCATED_ARGS_KEY]: raw };
   }
 }
 
@@ -30,39 +33,40 @@ export function normalizeThinkingParts(parts: string[]): string | undefined {
 }
 
 /**
- * Redacts secret-bearing headers for the raw audit trail. Superset of the
- * four adapter versions: `authorization` (any case) and `x-goog-api-key` are
- * redacted; all other headers pass through untouched.
+ * Redacts secret-bearing headers for the raw audit trail via the central
+ * deny-list: any header whose NAME contains key / token / secret / cookie /
+ * authorization (so `x-api-key`, `api-key`, `cf-aig-authorization` …), plus any
+ * value that looks like a credential. Everything else passes through.
  */
 export function redactedHeaders(headers: Record<string, string>): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(headers)) {
-    const lower = k.toLowerCase();
-    out[k] = lower === "authorization" || lower === "x-goog-api-key" ? "[REDACTED]" : v;
-  }
-  return out;
+  return redactHeadersCentral(headers) as Record<string, string>;
 }
 
 /**
- * Extracts `{ message, code, errorType }` from a non-2xx JSON body. Handles
- * OpenAI `type`, OpenRouter `metadata.error_type`, and Google `status` code
- * shapes; unknown bodies degrade to a 300-char slice.
+ * Extracts `{ message, code, errorType, raw }` from a non-2xx JSON body. Handles
+ * OpenAI `type`, OpenRouter `metadata.error_type` + `metadata.raw`, and Google
+ * `status` code shapes; unknown bodies degrade to a 300-char slice.
  */
 export function readErrorPayload(
   bodyText: string
-): { message: string; code?: string | number; errorType?: string } {
+): { message: string; code?: string | number; errorType?: string; raw?: string } {
   try {
     const parsed: unknown = JSON.parse(bodyText);
     const first = Array.isArray(parsed) ? parsed[0] : parsed;
-    const err = (first as { error?: { message?: string; code?: string | number; type?: string; status?: string | number; metadata?: { error_type?: string } } })?.error;
+    const err = (first as { error?: { message?: string; code?: string | number; type?: string; status?: string | number; metadata?: { error_type?: string; raw?: unknown } } })?.error;
     if (err && typeof err.message === "string") {
       const code = err.code ?? err.status;
       const errorType =
         err.type ?? err.metadata?.error_type ?? (first as { error_type?: string })?.error_type;
+      const rawCandidate =
+        (err as { metadata?: { raw?: unknown } }).metadata?.raw ??
+        (first as { metadata?: { raw?: unknown } })?.metadata?.raw;
+      const raw = typeof rawCandidate === "string" && rawCandidate.trim() ? rawCandidate.trim().slice(0, 500) : undefined;
       return {
         message: err.message,
         ...(code !== undefined ? { code } : {}),
         ...(typeof errorType === "string" ? { errorType } : {}),
+        ...(raw ? { raw } : {}),
       };
     }
     return { message: bodyText.slice(0, 300) };
@@ -87,6 +91,30 @@ export function incompleteStreamError(provider: string, modelId: string): Error
   return err;
 }
 
+/**
+ * True when an error signals an evicted/invalid chained interaction
+ * (Google Interactions `404` / `{code: not_found}` on REST, `{event_type:
+ * error, error: {code: not_found}}` on SSE). Structured-data only: HTTP
+ * status, `code`, or `errorType` — never message text.
+ */
+export function isNotFoundChainError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const err = error as Record<string, unknown>;
+  const status = Number(
+    (err["status"] as number | undefined) ??
+      (err["statusCode"] as number | undefined) ??
+      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      NaN
+  );
+  if (status === 404) return true;
+  const code = String(
+    (err["code"] as string | undefined) ??
+      (err["errorType"] as string | undefined) ??
+      ""
+  ).toLowerCase();
+  return code === "not_found";
+}
+
 /** Per-request timeout ms from provider options (Q-22). */
 export function timeoutFor(options: { timeoutMs?: number } | undefined): number | undefined {
   const t = (options as { timeoutMs?: unknown } | undefined)?.timeoutMs;
@@ -130,3 +158,127 @@ export function newToolCallId(prefix = "call"): string {
   } catch {}
   return `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
 }
+
+/**
+ * True when custom headers already carry auth (proxy/Copilot flows).
+ * Case-insensitive, non-empty `Authorization` or `cf-aig-authorization`.
+ * Callers return `"unused"` instead of throwing missing-key.
+ */
+export function hasAuthHeader(headers: Record<string, string> | undefined): boolean {
+  if (!headers) return false;
+  for (const [k, v] of Object.entries(headers)) {
+    const lower = k.toLowerCase();
+    if ((lower === "authorization" || lower === "cf-aig-authorization") && typeof v === "string" && v.trim().length > 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** True for truncated streamed tool args (the `__truncated_raw` marker from `parseStreamedToolArguments`). */
+export function hasTruncatedToolArguments(args: unknown): boolean {
+  return isTruncatedArguments(args);
+}
+
+/** Short hash for tool-ID clamping (FNV-1a, 8 hex chars, no deps). */
+export function shortHashId(value: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Clamps a tool-call ID to the 40-char OpenAI limit (pi `api/openai-completions.ts:1194`).
+ * Pipe IDs (`callId|itemId`) become `callId_itemHash`; overlong IDs truncate
+ * with hash suffix. Plain IDs pass through (truncated if needed).
+ */
+export function clampToolCallId(id: string): string {
+  const clean = String(id ?? "").replace(/[^a-zA-Z0-9_-]/g, "_");
+  if (!clean.includes("|")) {
+    return clean.length > 40 ? clean.slice(0, 40) : clean || "call_unknown";
+  }
+  const sep = clean.indexOf("|");
+  const callId = clean.slice(0, sep).replace(/_+$/, "") || "call";
+  const itemId = clean.slice(sep + 1).replace(/_+$/, "");
+  const combined = itemId ? `${callId}_${itemId}` : callId;
+  if (combined.length <= 40) return combined;
+  const hash = shortHashId(id).slice(0, 8);
+  const prefix = callId.slice(0, Math.max(1, 40 - hash.length - 1));
+  return `${prefix}_${hash}`;
+}
+
+/** Plain lower-cased header record from a fetch `Headers` object. */
+export function headersToRecord(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((v, k) => {
+    out[k] = v;
+  });
+  return out;
+}
+
+/**
+ * Parses a rate-limit hint from response headers into milliseconds:
+ * `retry-after-ms`, then `retry-after` (delta-seconds or HTTP-date).
+ * Returns undefined when absent or unparseable.
+ */
+export function parseRetryAfterMs(headers: Record<string, string> | undefined, now = Date.now()): number | undefined {
+  if (!headers) return undefined;
+  const get = (name: string): string | undefined => {
+    for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === name) return v;
+    return undefined;
+  };
+  const ms = get("retry-after-ms");
+  if (ms !== undefined && ms.trim() !== "" && Number.isFinite(Number(ms)) && Number(ms) >= 0) return Math.round(Number(ms));
+  const ra = get("retry-after");
+  if (ra === undefined || ra.trim() === "") return undefined;
+  const secs = Number(ra);
+  if (Number.isFinite(secs)) return secs >= 0 ? Math.round(secs * 1000) : undefined;
+  const at = Date.parse(ra);
+  return Number.isFinite(at) ? Math.max(0, at - now) : undefined;
+}
+
+/**
+ * Opens an SSE response, retrying transient failures (429/5xx/network) BEFORE
+ * any byte is consumed, so a streaming caller gets the same resilience as
+ * `generate()`. Once this resolves the stream is live and never retried.
+ * `onHttpError` must throw (usually the adapter's concise `throwIfError`).
+ */
+export function openStreamResponse(args: {
+  fetchOnce: () => Promise<Response>;
+  onHttpError: (res: Response, bodyText: string) => void;
+  noBodyError: () => Error;
+  retry: ReturnType<typeof retryOptionsFrom>;
+  signal: AbortSignal;
+  label: { providerId: string; modelId: string };
+}): Promise<Response> {
+  return withRetries(
+    async () => {
+      const res = await args.fetchOnce();
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        args.onHttpError(res, text);
+      }
+      if (!res.body) throw args.noBodyError();
+      return res;
+    },
+    { ...args.retry, signal: args.signal, label: args.label }
+  );
+}
+
+/** Retry knobs from provider request options, in the shape `withRetries` expects. */
+export function retryOptionsFrom(options: {
+  maxRetries?: number;
+  maxRetryDelayMs?: number;
+  retryBaseDelayMs?: number;
+  retryBudgetMs?: number;
+} | undefined): { maxRetries?: number; maxRetryDelayMs?: number; baseDelayMs?: number; retryBudgetMs?: number } {
+  return {
+    maxRetries: options?.maxRetries,
+    maxRetryDelayMs: options?.maxRetryDelayMs,
+    baseDelayMs: options?.retryBaseDelayMs,
+    retryBudgetMs: options?.retryBudgetMs,
+  };
+}