agent-accelerator 0.5.4 → 0.5.6

package/src/providers/openrouter.ts

@@ -14,10 +14,13 @@
  * lossy error codes, beta event-vocabulary drift.
  *
  * Notes:
+ * - EVERY request streams, `generate()` included (it collects its own `stream()`): OpenRouter only cancels a request that
+ *   streams ("Stream cancellation" in its docs), so a plain non-streaming request could not be stopped by an interrupt.
  * - STATELESS per request: every turn sends the full canonical `messages`
- *   array explicitly. Completions defines no `store`/`previous_response_id`/
- *   `conversation`/`prompt_cache_key`/`session_id` body primitives, so none
- *   are ever sent; affinity is headers-only best effort (`x-session-id`).
+ *   array explicitly. Completions has no `store`/`previous_response_id`/
+ *   `conversation`/`prompt_cache_key`, so none are ever sent. Session affinity is
+ *   the documented top-level body `session_id` (the sticky-routing key, which wins
+ *   over the header) plus the `x-session-id` / `x-client-request-id` headers.
  * - IDs are provider-generated (`gen-…` generations, `call_…`/uuid tool ids)
  *   and echoed verbatim (`tool_call_id`). The `call_${random}` fallback in
  *   parsers is a local canonical correlation id only; it is never sent.
@@ -37,22 +40,26 @@ import type { ProviderContext, ContentPart } from "../types/message.ts";
 import type { StandardToolDeclaration, ToolCallRecord } from "../types/tool.ts";
 import type { TokenUsage } from "../types/core.ts";
 import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
-import { SSEParser } from "../streaming/sse-parser.ts";
 import { AgentResponse } from "../types/response.ts";
 import { getApiKey, getEnv } from "../utils/env.ts";
 import { buildSessionHeaders, setHeaderCaseInsensitive } from "../utils/headers.ts";
 import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported } from "../utils/errors.ts";
-import { withRetries } from "../utils/retry.ts";
+import { isAbortError } from "../types/errors.ts";
 import {
-  parseArguments,
-  normalizeThinkingParts,
   newToolCallId,
   redactedHeaders,
   readErrorPayload,
   incompleteStreamError,
-  hasTruncatedToolArguments,
+  hasUnfinishedToolCall,
+  linkStreamAbort,
+  withAbortTimer,
+  readSseData,
+  incompleteStreamCheck,
+  failStream,
+  toolArgumentsJson,
+  toolTurnFinishReason,
   combinedSignal,
   timeoutFor,
   hasAuthHeader,
@@ -86,7 +93,7 @@ import {
 
 type ChatContentPart =
   | { type: "text"; text: string }
-  | { type: "image_url"; image_url: { url: string } }
+  | { type: "image_url"; image_url: { url: string; detail?: string } }
   | { type: "video_url"; video_url: { url: string } }
   | { type: "input_audio"; input_audio: { data: string; format: string } }
   | { type: "file"; file: { filename?: string; file_data?: string; file_url?: string } }
@@ -115,68 +122,20 @@ interface ChatRequestBody {
   reasoning?: { effort: string };
   service_tier?: string;
   session_id?: string;
-  plugins?: Array<{ id: string }>;
   cache_control?: { type: "ephemeral"; ttl: "5m" | "1h" };
   response_format?: { type: "json_schema"; json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string } };
   stream?: boolean;
   [k: string]: unknown;
 }
 
-interface ChatChoice {
-  index?: number;
-  message?: {
-    role?: string;
-    content?: string | null;
-    tool_calls?: Array<{
-      id?: string;
-      type?: string;
-      index?: number;
-      function?: { name?: string; arguments?: string };
-    }>;
-    reasoning?: string | null;
-    reasoning_details?: Array<{ type?: string; text?: string }>;
-    refusal?: string | null;
-  };
-  delta?: {
-    role?: string;
-    content?: string | null;
-    tool_calls?: Array<{
-      index?: number;
-      id?: string;
-      type?: string;
-      function?: { name?: string; arguments?: string };
-    }>;
-    reasoning_content?: string;
-    reasoning?: string;
-    reasoning_details?: Array<{ type?: string; text?: string }>;
-    refusal?: string | null;
-  };
-  finish_reason?: string | null;
-  native_finish_reason?: string | null;
-  error?: { message?: string; code?: string | number };
-}
-
-interface ChatResponse {
-  id?: string;
-  object?: string;
-  created?: number;
-  model?: string;
-  provider?: string;
-  choices?: ChatChoice[];
-  usage?: {
-    prompt_tokens?: number;
-    completion_tokens?: number;
-    total_tokens?: number;
-    prompt_tokens_details?: { cached_tokens?: number; cache_write_tokens?: number };
-    completion_tokens_details?: { reasoning_tokens?: number };
-    cost?: number;
-    [k: string]: unknown;
-  };
-  error?: {
-    message?: string;
-    code?: string | number;
-    metadata?: { error_type?: string; provider_code?: string | number; [k: string]: unknown };
-  };
+/** The usage block of a Chat Completions chunk (the last chunk of a stream carries it, with OpenRouter's `cost`). */
+interface ChatUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+  prompt_tokens_details?: { cached_tokens?: number; cache_write_tokens?: number };
+  completion_tokens_details?: { reasoning_tokens?: number };
+  cost?: number;
   [k: string]: unknown;
 }
 
@@ -211,6 +170,13 @@ function cleanModelId(model: string | ModelSpec): string {
   return rawId.replace(/^openrouter\//i, "");
 }
 
+// The HTTP status of an error chunk inside a stream (the HTTP status itself is 200): its numeric `code`, else the status of its retryable `error_type` (errors-and-debugging.md, "Typed Error Codes"); in: the chunk's error, out: streamInto, where it makes the error retryable.
+const RETRYABLE_ERROR_TYPE_STATUS: Record<string, number> = { rate_limit_exceeded: 429, provider_overloaded: 503, provider_unavailable: 502, timeout: 504, server: 500 };
+function midStreamStatus(code: unknown, errorType: unknown): number | undefined {
+  if (typeof code === "number" && Number.isInteger(code) && code >= 100 && code <= 599) return code;
+  return typeof errorType === "string" ? RETRYABLE_ERROR_TYPE_STATUS[errorType] : undefined;
+}
+
 function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -224,20 +190,31 @@ function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<stri
   }));
 }
 
+// The `input_audio.format` for a MIME type: Chat Completions takes any format string the provider supports (audio.md: wav, mp3, aiff, aac, ogg, flac, m4a, pcm16 ...), so the real format is sent, never a guess; in: an audio part's MIME type, out: contentPartsToBlocks.
+const AUDIO_FORMAT: Record<string, string> = { wav: "wav", wave: "wav", mpeg: "mp3", mp3: "mp3", mp4: "m4a", m4a: "m4a", aac: "aac", ogg: "ogg", flac: "flac", aiff: "aiff" };
 function audioFormatFor(mimeType?: string): string {
-  const mime = (mimeType || "").toLowerCase();
-  if (mime.includes("wav")) return "wav";
-  return "mp3";
+  const subtype = (mimeType || "").toLowerCase().split(";")[0]!.split("/")[1]?.replace(/^x-/, "") ?? "";
+  return AUDIO_FORMAT[subtype] ?? (subtype || "mp3");
+}
+
+// `ImagePart.resolution` as OpenRouter's `image_url.detail` (api-ref ChatContentImage: auto, low, high, original; `original` is downgraded to `high` where unsupported); videos have no such field; in: an image part, out: contentPartsToBlocks.
+const IMAGE_DETAIL: Record<string, "low" | "auto" | "high" | "original"> = { low: "low", medium: "auto", high: "high", ultra_high: "original" };
+
+// True when a request's messages carry an image or video by web link (the router fetches those itself); in: the built messages, out: throwIfError's hint.
+function hasRemoteMedia(messages: ChatMessage[]): boolean {
+  return messages.some(
+    (m) =>
+      Array.isArray(m.content) &&
+      (m.content as ChatContentPart[]).some((p) => {
+        const url = (p as { image_url?: { url?: string }; video_url?: { url?: string } }).image_url?.url ?? (p as { video_url?: { url?: string } }).video_url?.url;
+        return typeof url === "string" && /^https?:\/\//.test(url);
+      })
+  );
 }
 
-async function contentPartsToBlocks(parts: ContentPart[]): Promise<{
-  blocks: ChatContentPart[];
-  fileUrls: string[];
-  hasFiles: boolean;
-}> {
+// Maps canonical text and media parts to Chat Completions content blocks; in: a user message's parts, out: fullHistoryMessages.
+async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPart[]> {
   const blocks: ChatContentPart[] = [];
-  const fileUrls: string[] = [];
-  let hasFiles = false;
   for (const part of parts) {
     if (part.type === "text" && part.text) {
       blocks.push({ type: "text", text: part.text });
@@ -245,15 +222,16 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<{
       const raw = (part as { image?: unknown }).image;
       // Remote URLs pass through (router downloads; `image_download_failed`
       // surfaces if unreachable). Inline only local/base64/binary.
+      const detail = IMAGE_DETAIL[(part as { resolution?: string }).resolution ?? ""];
       if (typeof raw === "string" && (raw.startsWith("http://") || raw.startsWith("https://"))) {
-        blocks.push({ type: "image_url", image_url: { url: raw } });
+        blocks.push({ type: "image_url", image_url: { url: raw, ...(detail ? { detail } : {}) } });
         continue;
       }
       const norm = await normalizeMediaInput(
         raw as string | Uint8Array | ArrayBuffer,
         (part as { mimeType?: string }).mimeType
       );
-      blocks.push({ type: "image_url", image_url: { url: norm.dataUrl } });
+      blocks.push({ type: "image_url", image_url: { url: norm.dataUrl, ...(detail ? { detail } : {}) } });
     } else if (part.type === "video") {
       const raw = (part as { video?: unknown }).video;
       // `video_url` is the completions video shape (live: shape accepted,
@@ -267,7 +245,9 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<{
         raw as string | Uint8Array | ArrayBuffer,
         (part as { mimeType?: string }).mimeType
       );
-      blocks.push({ type: "video_url", video_url: { url: norm.dataUrl } });
+      // video-inputs.md names the QuickTime type `video/mov`.
+      const url = norm.mimeType === "video/quicktime" ? `data:video/mov;base64,${norm.base64Data}` : norm.dataUrl;
+      blocks.push({ type: "video_url", video_url: { url } });
     } else if (part.type === "audio") {
       const raw = (part as { audio?: unknown }).audio;
       const mimeType = (part as { mimeType?: string }).mimeType;
@@ -282,37 +262,20 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<{
         input_audio: { data: norm.base64Data, format: audioFormatFor(norm.mimeType) },
       });
     } else if (part.type === "file") {
-      hasFiles = true;
       const raw = (part as { file?: unknown }).file;
       const filename = (part as { filename?: string }).filename;
-      if (typeof raw === "string" && (raw.startsWith("http://") || raw.startsWith("https://"))) {
-        // Bare `{type:file}` parts are ignored by the route (observed live),
-        // so the URL must ALSO ride in text for the file-parser plugin (see
-        // fullHistoryMessages). Still sent forward-compat.
-        fileUrls.push(raw);
-        blocks.push({
-          type: "file",
-          file: {
-            ...(typeof filename === "string" && filename ? { filename } : {}),
-            file_url: raw,
-          },
-        });
-        continue;
-      }
-      const norm = await normalizeMediaInput(
-        raw as string | Uint8Array | ArrayBuffer,
-        (part as { mimeType?: string }).mimeType
-      );
+      // `file_data` takes a public URL or a base64 data URL (api-ref ChatContentFile; a `file_url` field does not exist).
+      const fileData =
+        typeof raw === "string" && (raw.startsWith("http://") || raw.startsWith("https://"))
+          ? raw
+          : (await normalizeMediaInput(raw as string | Uint8Array | ArrayBuffer, (part as { mimeType?: string }).mimeType)).dataUrl;
       blocks.push({
         type: "file",
-        file: {
-          ...(typeof filename === "string" && filename ? { filename } : {}),
-          file_data: norm.dataUrl,
-        },
+        file: { ...(typeof filename === "string" && filename ? { filename } : {}), file_data: fileData },
       });
     }
   }
-  return { blocks, fileUrls, hasFiles };
+  return blocks;
 }
 
 function resultToOutput(result: unknown): string {
@@ -325,15 +288,8 @@ function resultToOutput(result: unknown): string {
  * Stateless transport: no chaining primitives exist here, so every turn
  * carries everything. Assistant items carry no provider `id`/`status`
  * requirements (unlike the discontinued Responses skin).
- *
- * File handling: remote file URLs must be visible in text for the
- * `file-parser` plugin (bare `{type:file}` parts are ignored by the route),
- * so each remote file URL is appended as its own text part.
  */
-async function fullHistoryMessages(context: ProviderContext): Promise<{
-  messages: ChatMessage[];
-  hasFiles: boolean;
-}> {
+async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessage[]> {
   // Map assistant tool_call ids so tool results pair even though the
   // executor keys results by the call id.
   const pairing = new Map<string, string>();
@@ -357,7 +313,6 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
   if (context.systemPrompt) {
     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;
@@ -370,12 +325,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
       if (typeof m.content === "string") {
         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;
-        // Surface remote file URLs in text for the file-parser plugin.
-        for (const url of fileUrls) {
-          blocks.push({ type: "text", text: url });
-        }
+        const blocks = await contentPartsToBlocks(m.content);
         if (blocks.length > 0) { messages.push({ role: "user", content: blocks }); lastRole = "user"; }
       }
     } else if (m.role === "assistant") {
@@ -392,7 +342,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
           calls.push({
             id: clampToolCallId(part.callId || part.id),
             type: "function",
-            function: { name: part.name, arguments: JSON.stringify(part.arguments || {}) },
+            function: { name: part.name, arguments: toolArgumentsJson(part.arguments) },
           });
         } else if (part.type === "text" && part.text) {
           texts.push(part.text);
@@ -435,14 +385,14 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
       }
     }
   }
-  return { messages, hasFiles };
+  return messages;
 }
 
 // ---------------------------------------------------------------------------
 // Response mapping (Chat Completions -> canonical)
 // ---------------------------------------------------------------------------
 
-function mapUsage(raw?: ChatResponse["usage"]): TokenUsage {
+function mapUsage(raw?: ChatUsage): TokenUsage {
   const input = raw?.prompt_tokens ?? 0;
   const output = raw?.completion_tokens ?? 0;
   // Canonical invariant: cache hits are a SUBSET of input (no turn may
@@ -457,87 +407,12 @@ function mapUsage(raw?: ChatResponse["usage"]): TokenUsage {
     cacheWriteTokens: raw?.prompt_tokens_details?.cache_write_tokens ?? 0,
     thinkingTokens: raw?.completion_tokens_details?.reasoning_tokens ?? 0,
   };
-  if (typeof raw?.cost === "number" && raw.cost > 0) {
+  if (typeof raw?.cost === "number" && raw.cost >= 0) { // an explicit 0 (a free model, a response-cache hit) is a known cost, not a missing one
     usage.cost = { totalCost: raw.cost };
   }
   return usage;
 }
 
-function throwResponseError(response: ChatResponse, modelId: string): void {
-  const message =
-    response.error && typeof response.error.message === "string" && response.error.message
-      ? response.error.message
-      : "OpenRouter response failed";
-  const failure: Record<string, unknown> & Error = new Error(message) as Record<string, unknown> & Error;
-  if (response.error?.code !== undefined) failure["code"] = response.error.code;
-  // Chat skin keeps the stable typed code INSIDE metadata (unlike Responses'
-  // top-level `error_type`).
-  const errorType = (response.error?.metadata as { error_type?: string } | undefined)?.error_type;
-  if (typeof errorType === "string") failure["errorType"] = errorType;
-  throw toConciseProviderError(failure, "openrouter", modelId);
-}
-
-function parseResponse(
-  response: ChatResponse,
-  modelId: string,
-  durationMs: number,
-  raw: ProviderRawData
-): ProviderGenerateResult {
-  // Provider-interrupted generations arrive as HTTP 200 carrying ONLY `error`
-  // (no `choices`) — must check the body, not just the status.
-  if (response.error) throwResponseError(response, modelId);
-
-  const choice = response.choices?.[0];
-  const message = choice?.message;
-  // Q-23: refusal content surfaces as text with a `refusal` finish reason.
-  const refusal = typeof message?.refusal === "string" && message.refusal ? message.refusal : "";
-  const text = typeof message?.content === "string" && message.content ? message.content : refusal;
-  // Thinking: `reasoning_details[].text` duplicates `message.reasoning` when
-  // both ride along (observed live) — prefer details, else the plain field.
-  const thinkingParts: string[] = [];
-  const detailTexts: string[] = [];
-  for (const block of message?.reasoning_details ?? []) {
-    if (block?.type === "reasoning.text" && block.text) detailTexts.push(block.text);
-  }
-  if (detailTexts.length > 0) {
-    thinkingParts.push(...detailTexts);
-  } else if (typeof message?.reasoning === "string" && message.reasoning) {
-    thinkingParts.push(message.reasoning);
-  }
-  const toolCalls: ToolCallRecord[] = [];
-  for (const tc of message?.tool_calls ?? []) {
-    const args = parseArguments(tc.function?.arguments);
-    toolCalls.push({
-      id: tc.id && !tc.id.includes("|") && tc.id.length <= 40 ? tc.id : clampToolCallId(tc.id || newToolCallId()),
-      name: tc.function?.name || "unknown",
-      arguments: args,
-      rawArguments:
-        typeof tc.function?.arguments === "string"
-          ? tc.function.arguments
-          : JSON.stringify(tc.function?.arguments ?? {}),
-    });
-  }
-
-  // Normalized finish reasons: tool_calls|stop|length|content_filter|error.
-  // Q-23: refusal content forces `refusal` (even when the wire says stop).
-  const wireReason = choice?.finish_reason ?? undefined;
-  const finishReason =
-    toolCalls.length > 0 ? "tool_calls" : refusal ? "refusal" : wireReason || "stop";
-  return {
-    text,
-    thinking: normalizeThinkingParts(thinkingParts),
-    thoughtSignature: undefined,
-    toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
-    usage: mapUsage(response.usage),
-    finishReason,
-    responseId: response.id,
-    model: modelId,
-    provider: "openrouter",
-    raw,
-    durationMs,
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Provider
 // ---------------------------------------------------------------------------
@@ -576,8 +451,8 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     const { effort } = mapThinkingLevelToOpenRouterChat(options?.thinking?.level);
     const serviceTier = mapServiceTierToOpenRouter(options?.serviceTier);
     // Anthropic models take a top-level `cache_control` TTL; every other route caches implicitly (docs: prompt-caching.md).
-    const cache = resolveCache("openrouter", options?.cache, modelId.startsWith("anthropic/") ? ["implicit", "5m", "1h"] : ["implicit"], `openrouter/${modelId}`);
-    warnIgnoredMediaResolution("openrouter", context.messages, `openrouter/${modelId}`);
+    const cache = resolveCache("openrouter", options?.cache, /^~?anthropic\//.test(modelId) ? ["implicit", "5m", "1h"] : ["implicit"], `openrouter/${modelId}`);
+    warnIgnoredMediaResolution("openrouter", context.messages, `openrouter/${modelId}`, ["video"]);
 
     // Structured outputs: native `response_format` when supported, else
     // emulated via system-prompt instruction + client validation (catalog
@@ -605,7 +480,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         fallback: "emulated JSON instruction + client validation (no response_format is sent)",
       });
     }
-    const { messages, hasFiles } = await fullHistoryMessages(effectiveContext);
+    const messages = await fullHistoryMessages(effectiveContext);
     const body: ChatRequestBody = {
       model: modelId,
       messages,
@@ -621,7 +496,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     if (serviceTier) body.service_tier = serviceTier;
     if (cache === "5m" || cache === "1h") body.cache_control = { type: "ephemeral", ttl: cache };
     // Documented Chat Completions generation controls (only those the caller set).
-    Object.assign(body, mapGenerationParamsToChat(options));
+    Object.assign(body, mapGenerationParamsToChat(options, "openrouter", `openrouter/${modelId}`));
     // Structured outputs: Chat Completions `response_format{type:json_schema,json_schema}`.
     // Skipped when emulated (unsupported model): instruction already in messages.
     if (outputSpec && !outputEmulated) {
@@ -632,9 +507,6 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         // 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 store/previous_response_id/conversation: they do not exist
     // on this endpoint.
     // Session affinity: top-level `session_id` is the documented sticky-routing
@@ -665,41 +537,23 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
-  private async doFetch(
-    url: string,
-    body: ChatRequestBody,
-    options: ProviderRequestOptions | undefined,
-    apiKey: string,
-    sessionId: string | undefined,
-    signal?: AbortSignal
-  ): 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 (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) => {
-        headers[k] = v;
-      });
-      return { status: res.status, statusText: res.statusText, headers, text };
-    } finally {
-      cleanup();
-    }
-  }
-
   private throwIfError(
     status: number,
     url: string,
     bodyText: string,
     modelId: string,
-    headers?: Record<string, string>
+    headers?: Record<string, string>,
+    remoteMedia = false
   ): void {
     if (status >= 200 && status < 300) return;
-    const { message, code, errorType, raw } = readErrorPayload(bodyText);
+    const { message, code, errorType, raw, limitSource } = 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)."
-        : "";
+        : // A bad or unreachable image/video link comes back as the bare "Provider returned error" without saying which part failed.
+          status === 400 && remoteMedia && message === "Provider returned error"
+          ? " The request carries a remote image or video link: it may be unreachable or not accepted by this route. Try passing the file itself (a local path or bytes) instead."
+          : "";
     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;
@@ -712,84 +566,49 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     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);
+    const concise = toConciseProviderError(err, "openrouter", modelId);
+    // A 402 from the in-flight spending budget clears by itself once running requests settle (errors-and-debugging.md, Retry-After): retry it after the header's wait. A 402 for missing credits does not.
+    if (status === 402 && limitSource === "openrouter_in_flight_budget") {
+      (concise as unknown as Record<string, unknown>)["retryable"] = true;
+      (concise as unknown as Record<string, unknown>)["transient"] = true;
+    }
+    throw concise;
   }
 
+  // OpenRouter can only cancel a request that streams ("Stream cancellation": for a non-streaming request the model keeps processing and you are billed in full), so even a plain generate is sent as a stream and collected here: an interrupt then closes the connection and stops processing and billing at the providers OpenRouter can cancel; in: the loop's non-streaming turn, out: the same ProviderGenerateResult a JSON reply gave.
   async generate(
     model: string | ModelSpec,
     context: ProviderContext,
     options?: ProviderRequestOptions
   ): Promise<ProviderGenerateResult> {
-    const startTime = Date.now();
-    const clean = cleanModelId(model);
-    const apiKey = resolveApiKey(options);
-    if (!apiKey) {
-      throw new Error(
-        "[Agent Accelerator] Missing OpenRouter API key. Set OPENROUTER_API_KEY or pass apiKey."
-      );
-    }
-    // Fail fast before any network call when the catalog knows the model
-    // lacks the requested modality (clear one-liner instead of a confusing
-    // router 404/400). Unknown models skip the guard; the router verdict
-    // surfaces concisely.
-    assertModalitiesSupported(context, "openrouter", clean);
-    const baseUrl = resolveBaseUrl(options);
-    const url = `${baseUrl}/chat/completions`;
-    const sessionId = options?.sessionId;
-    const tools = options?.tools as StandardToolDeclaration[] | undefined;
-    const body = await this.buildBody(clean, context, options, sessionId, tools, false);
-
-    // Audit trail: record the actual wire headers (attribution + session
-    // affinity included), redacted.
-    const auditRaw: Record<string, string> = {
-      ...buildSessionHeaders("openrouter", options?.headers, sessionId),
-      "Content-Type": "application/json",
-      Authorization: "[REDACTED]",
-    };
-    const rawRequest = {
-      url,
-      method: "POST",
-      headers: redactedHeaders(auditRaw),
-      body,
-    };
-
-    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, res.headers);
-      let response: ChatResponse;
-      try {
-        response = JSON.parse(res.text) as ChatResponse;
-      } catch {
-        throw toConciseProviderError(
-          Object.assign(new Error("Invalid JSON response from OpenRouter Chat Completions API"), {
-            statusCode: res.status,
-            responseBody: res.text.slice(0, 500),
-            url,
-          }),
-          "openrouter",
-          clean
-        );
-      }
-      // Stateless turns never establish chains, but the session store still
-      // records the turn so other providers' switch detection keeps working.
-      noteProviderTurn(sessionId, "openrouter");
-      return parseResponse(
-        response,
-        clean,
-        Date.now() - startTime,
-        { request: rawRequest, response: { status: res.status, statusText: res.statusText, headers: res.headers, body: response } }
-      );
-    };
-
+    // The whole call stays bounded by `timeoutMs`; the stream's own timer only covers the wait for its first byte.
+    const { signal, cleanup } = combinedSignal(options?.signal, timeoutFor(options as { timeoutMs?: number } | undefined));
     try {
-      return await withRetries(doCall, {
-        ...retryOptionsFrom(options),
-        signal: options?.signal,
-        label: { providerId: "openrouter", modelId: clean },
-      });
+      // Nobody reads the deltas here, so the stream keeps none (a burst of frames would overflow its buffer for nothing).
+      const events = this.streamInto(new AssistantMessageEventStream({ buffer: false }), model, context, { ...options, signal });
+      const res = await events.result();
+      return {
+        text: res.text,
+        thinking: res.thinking,
+        thoughtSignature: undefined,
+        toolCalls: res.toolCalls.length > 0 ? res.toolCalls : undefined,
+        usage: res.usage,
+        finishReason: res.finishReason,
+        responseId: res.responseId,
+        model: res.model,
+        provider: "openrouter",
+        raw: res.raw,
+        durationMs: res.durationMs,
+      };
     } catch (err) {
-      if (err instanceof Error && (err as { name?: string }).name === "AbortError") throw err;
+      // A stream reports its own generic abort; the caller's reason (`interrupt(new Error("..."))`) is what the run should carry.
+      const reason = options?.signal?.reason;
+      if (options?.signal?.aborted && reason instanceof Error && isAbortError(err)) {
+        throw Object.assign(new Error(reason.message), { name: "AbortError" });
+      }
       throw err;
+    } finally {
+      cleanup();
     }
   }
 
@@ -798,27 +617,20 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     context: ProviderContext,
     options?: ProviderRequestOptions
   ): AssistantMessageEventStream {
-    const eventStream = new AssistantMessageEventStream();
+    return this.streamInto(new AssistantMessageEventStream(), model, context, options);
+  }
+
+  // Runs one streamed request, pushing its events into `eventStream`; in: stream() (a normal stream) and generate() (one that keeps no events), out: that same stream, finished with the AgentResponse.
+  private streamInto(
+    eventStream: AssistantMessageEventStream,
+    model: string | ModelSpec,
+    context: ProviderContext,
+    options?: ProviderRequestOptions
+  ): AssistantMessageEventStream {
     const startTime = Date.now();
     const clean = cleanModelId(model);
 
-    const linked = new AbortController();
-    const forwardUserAbort = () => {
-      try {
-        linked.abort((options?.signal as { reason?: unknown })?.reason);
-      } catch {
-        try {
-          linked.abort();
-        } catch {}
-      }
-    };
-    if (options?.signal?.aborted) forwardUserAbort();
-    else options?.signal?.addEventListener("abort", forwardUserAbort, { once: true });
-    const removeStreamCancel = eventStream.onCancel(() => {
-      try {
-        linked.abort();
-      } catch {}
-    });
+    const { linked, release } = linkStreamAbort(eventStream, options?.signal);
 
     (async () => {
       try {
@@ -851,22 +663,8 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         // 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)),
+          fetchOnce: () => withAbortTimer(linked, streamTimeoutMs, () => (options?.fetch ?? fetch)(url, this.requestInit(body, options, apiKey, sessionId, linked.signal))),
+          onHttpError: (r, text) => this.throwIfError(r.status, url, text, clean, headersToRecord(r.headers), hasRemoteMedia(body.messages)),
           noBodyError: () => toConciseProviderError(new Error("OpenRouter streaming response had no body"), "openrouter", clean),
           retry: retryOptionsFrom(options),
           signal: linked.signal,
@@ -879,9 +677,6 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         const responseMeta: Record<string, unknown> & { status: number; statusText: string; headers: Record<string, string> } = { status: res.status, statusText: res.statusText, headers: responseHeaders };
         eventStream.push({ type: "start", raw: { request: rawRequest } } as never);
 
-        const parser = new SSEParser();
-        const reader = res.body!.getReader(); // openStreamResponse guarantees a body
-        const decoder = new TextDecoder();
         let text = "";
         let thinking = "";
         // Tool calls keyed by choice index: { id, name, startArgs, deltaArgs }.
@@ -898,18 +693,6 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         let framesSeen = 0;
         let responseId: string | undefined;
         let completedBody: unknown = undefined;
-        let aborted = false;
-        linked.signal.addEventListener(
-          "abort",
-          () => {
-            aborted = true;
-            try {
-              void reader.cancel();
-            } catch {}
-          },
-          { once: true }
-        );
-
         const handleMessage = (data: string): void => {
           if (!data) return;
           if (data === "[DONE]") {
@@ -935,6 +718,8 @@ export class OpenRouterChatCompletionsProvider implements Provider {
             const failure: Record<string, unknown> & Error = new Error(message) as Record<string, unknown> & Error;
             if (topError.code !== undefined) failure["code"] = topError.code;
             if (typeof topError.metadata?.error_type === "string") failure["errorType"] = topError.metadata.error_type;
+            const status = midStreamStatus(topError.code, topError.metadata?.error_type);
+            if (status !== undefined) failure["statusCode"] = status; // lets the retry logic and the message treat it like an HTTP error
             failure["url"] = url;
             throw toConciseProviderError(failure, "openrouter", clean);
           }
@@ -1022,7 +807,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
             finishReason = fr;
             sawFinishReason = true;
           }
-          const chunkUsage = msg["usage"] as ChatResponse["usage"] | undefined;
+          const chunkUsage = msg["usage"] as ChatUsage | undefined;
           if (chunkUsage) {
             usage = mapUsage(chunkUsage);
             sawUsage = true;
@@ -1031,32 +816,13 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           }
         };
 
-        while (true) {
-          if (linked.signal.aborted || eventStream.isCancelled()) {
-            try {
-              await reader.cancel();
-            } catch {}
-            throw Object.assign(new Error("Stream aborted"), { name: "AbortError" });
-          }
-          const { done, value } = await reader.read();
-          if (done) break;
-          const chunk = decoder.decode(value, { stream: true });
-          for (const m of parser.feed(chunk)) handleMessage(m.data);
-        }
-        for (const m of parser.flush()) handleMessage(m.data);
-        try {
-          reader.releaseLock();
-        } catch {}
-
-        if (linked.signal.aborted || eventStream.isCancelled() || aborted) {
-          throw Object.assign(new Error("Stream aborted"), { name: "AbortError" });
-        }
+        await readSseData(res.body!, linked, eventStream, handleMessage); // openStreamResponse guarantees a body
 
         const toolCalls: ToolCallRecord[] = [];
         for (const c of calls.values()) {
           const args = parseStreamedToolArguments(c.startArgs, c.deltaArgs);
           const record: ToolCallRecord = {
-            id: c.id && !c.id.includes("|") && c.id.length <= 40 ? c.id : clampToolCallId(c.id || newToolCallId()),
+            id: clampToolCallId(c.id || newToolCallId()), // the id the history sends back, so the stored id and the wire id are one
             name: c.name,
             arguments: args,
             rawArguments: selectRawArguments(c.startArgs, c.deltaArgs),
@@ -1065,9 +831,11 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           eventStream.push({ type: "tool_call_complete", toolCall: record });
         }
 
+        // Did the stream really end? Read before the tool-call and refusal overrides below, which also set sawFinishReason.
+        const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;
         noteProviderTurn(sessionId, "openrouter");
         if (toolCalls.length > 0) {
-          finishReason = "tool_calls";
+          finishReason = toolTurnFinishReason(finishReason, toolCalls);
           sawFinishReason = true;
         } else if (refusalSeen && finishReason !== "content_filter") {
           finishReason = "refusal";
@@ -1077,26 +845,21 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
-        const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;
-        const cleanThinkingEarly = thinking.replace(/\n{3,}/g, "\n\n").trim();
-        const ctEntry = Object.entries(responseHeaders).find(([k]) => k.toLowerCase() === "content-type");
-        const isSSEPayload =
-          (typeof ctEntry?.[1] === "string" && ((ctEntry[1] as string).includes("event-stream") || (ctEntry[1] as string).startsWith("text/"))) ||
-          framesSeen > 0 ||
-          badFrames > 0;
-        if (!hasTerminal && !text && !cleanThinkingEarly && toolCalls.length === 0 && isSSEPayload) {
-          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));
+        const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();
+        const incomplete = incompleteStreamCheck({
+          provider: "openrouter",
+          modelId: clean,
+          hasTerminal,
+          empty: !text && !cleanThinking && toolCalls.length === 0,
+          unfinishedCall: hasUnfinishedToolCall(calls.values(), toolCalls),
+          responseHeaders,
+          framesSeen,
+          badFrames,
+        });
+        if (incomplete) {
+          eventStream.fail(incomplete);
           return;
         }
-
-        const cleanThinking = cleanThinkingEarly;
         const finalResponse = new AgentResponse({
           text,
           thinking: cleanThinking || undefined,
@@ -1116,21 +879,9 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         eventStream.push({ type: "done", delta: "", usage, finishReason, responseId });
         eventStream.end(finalResponse);
       } catch (err: unknown) {
-        const raw = err instanceof Error ? err : new Error(String(err));
-        const isAbort =
-          linked.signal.aborted ||
-          eventStream.isCancelled() ||
-          (raw as { name?: string }).name === "AbortError";
-        eventStream.fail(
-          isAbort ? Object.assign(new Error("Stream aborted"), { name: "AbortError" }) : raw
-        );
+        failStream(eventStream, linked, err);
       } finally {
-        try {
-          options?.signal?.removeEventListener("abort", forwardUserAbort);
-        } catch {}
-        try {
-          removeStreamCancel();
-        } catch {}
+        release();
       }
     })();