agent-accelerator 0.5.9 → 0.6.5

package/src/providers/openrouter.ts

@@ -6,7 +6,7 @@
  * never in the canonical layer (`src/providers.ts`).
  *
  * Wire contract: `references/testings/openrouter/CONTRACT.md` (docs + live
- * captures on `stealth/space-bunny-alpha`, 2026-09-24). Capability matrix:
+ * captures, 2026-09-24). Capability matrix:
  * `references/testings/openrouter/CAPABILITY-MATRIX.md`.
  *
  * This is the STABLE transport. The beta Responses skin
@@ -24,9 +24,10 @@
  * - 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.
- * - Prior-turn reasoning is NOT resent (chat history is messages + tool
- *   calls only). This matches the Responses adapter behavior and avoids 400s
- *   on strict routes; documented in the capability matrix.
+ * - Prior-turn reasoning is resent as `reasoning_details` exactly as returned (kept on the assistant message as
+ *   `providerSteps`), which tool turns need (reasoning-tokens.md, "Preserving Reasoning"). Plain `reasoning` text alone is
+ *   never resent. Parsed-PDF `file` annotations ride the same way and go back as `annotations`, so the router does not parse
+ *   the same PDF again (pdf-inputs.md, "Skip Parsing Costs").
  */
 import type {
   Provider,
@@ -47,11 +48,11 @@ import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported } from "../utils/errors.ts";
 import { ConfigError, isAbortError } from "../types/errors.ts";
+import { DEFAULT_PROMPTS } from "../prompts/prompts.ts";
 import {
   newToolCallId,
   redactedHeaders,
   readErrorPayload,
-  incompleteStreamError,
   hasUnfinishedToolCall,
   linkStreamAbort,
   withAbortTimer,
@@ -85,6 +86,8 @@ import {
   augmentSystemPromptWithStructuredOutput,
   emitProviderWarning,
   warnIgnoredMediaResolution,
+  warnIgnoredVideoProcessing,
+  warnIgnoredToolMedia,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -109,6 +112,8 @@ type ChatMessage =
         type: "function";
         function: { name: string; arguments: string };
       }>;
+      reasoning_details?: unknown[];
+      annotations?: unknown[];
       name?: string;
     }
   | { role: "tool"; content: string; tool_call_id: string; name?: string }
@@ -119,11 +124,17 @@ interface ChatRequestBody {
   messages: ChatMessage[];
   tools?: Array<Record<string, unknown>>;
   tool_choice?: string | { type: "function"; function: { name: string } };
-  reasoning?: { effort: string };
+  reasoning?: { effort?: string; exclude?: boolean };
+  provider?: Record<string, unknown>;
+  parallel_tool_calls?: boolean;
+  user?: string;
   service_tier?: string;
   session_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 } };
+  response_format?: {
+    type: "json_schema";
+    json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string };
+  };
   stream?: boolean;
   [k: string]: unknown;
 }
@@ -133,8 +144,13 @@ 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 };
+  prompt_tokens_details?: {
+    cached_tokens?: number;
+    cache_write_tokens?: number;
+    audio_tokens?: number;
+    video_tokens?: number;
+  };
+  completion_tokens_details?: { reasoning_tokens?: number; audio_tokens?: number; image_tokens?: number };
   cost?: number;
   [k: string]: unknown;
 }
@@ -173,13 +189,84 @@ function cleanModelId(model: string | ModelSpec): string {
 }
 
 // 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 };
+const RETRYABLE_ERROR_TYPE_STATUS: Record<string, number> = {
+  rate_limit_exceeded: 429,
+  provider_overloaded: 503,
+  provider_unavailable: 502,
+  timeout: 504,
+  server: 500,
+};
 // HTTP-like status of an error chunk inside a stream, or undefined when unknown; in: streamInto's error branch, out: the status that makes the error retryable.
 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;
 }
 
+// OpenRouter options that come from env vars, never from AgentConfig (provider routing, `parallel_tool_calls`, `reasoning.exclude`, `user`). A per-Agent `env` wins over the process env; nothing is sent when no variable is set; a bad value is a ConfigError before any network call. NOT supported on purpose (the owner does not want them for now): `reasoning.max_tokens` and `trace`; in: buildBody, out: the extra body fields.
+const ROUTING_LISTS = { OPENROUTER_ORDER: "order", OPENROUTER_ONLY: "only", OPENROUTER_IGNORE: "ignore" } as const;
+const ROUTING_FLAGS = {
+  OPENROUTER_ALLOW_FALLBACKS: "allow_fallbacks",
+  OPENROUTER_REQUIRE_PARAMETERS: "require_parameters",
+  OPENROUTER_ZDR: "zdr",
+} as const;
+function openRouterEnvOptions(options?: ProviderRequestOptions): {
+  provider?: Record<string, unknown>;
+  parallel_tool_calls?: boolean;
+  reasoning_exclude?: boolean;
+  user?: string;
+} {
+  const read = (name: string): string | undefined => {
+    const own = options?.env?.[name]?.trim();
+    return own ? own : getEnv(name);
+  };
+  const bad = (name: string, value: string, expected: string): never => {
+    throw new ConfigError(`[Agent Accelerator] Invalid ${name} ${JSON.stringify(value)}: expected ${expected}.`);
+  };
+  const flag = (name: string): boolean | undefined => {
+    const v = read(name);
+    if (v === undefined) return undefined;
+    const t = v.toLowerCase();
+    if (t === "true" || t === "1") return true;
+    if (t === "false" || t === "0") return false;
+    return bad(name, v, "true or false");
+  };
+  const provider: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(ROUTING_LISTS)) {
+    const v = read(name);
+    if (v === undefined) continue;
+    const list = v
+      .split(",")
+      .map((x) => x.trim())
+      .filter(Boolean);
+    if (list.length === 0) bad(name, v, "a comma-separated list of provider slugs");
+    provider[field] = list;
+  }
+  for (const [name, field] of Object.entries(ROUTING_FLAGS)) {
+    const v = flag(name);
+    if (v !== undefined) provider[field] = v;
+  }
+  const collection = read("OPENROUTER_DATA_COLLECTION");
+  if (collection !== undefined) {
+    if (collection !== "allow" && collection !== "deny") bad("OPENROUTER_DATA_COLLECTION", collection, "allow or deny");
+    provider["data_collection"] = collection;
+  }
+  const sort = read("OPENROUTER_SORT");
+  if (sort !== undefined) {
+    if (sort !== "price" && sort !== "throughput" && sort !== "latency")
+      bad("OPENROUTER_SORT", sort, "price, throughput or latency");
+    provider["sort"] = sort;
+  }
+  const parallel = flag("OPENROUTER_PARALLEL_TOOL_CALLS");
+  const exclude = flag("OPENROUTER_REASONING_EXCLUDE");
+  const user = read("OPENROUTER_USER");
+  return {
+    ...(Object.keys(provider).length > 0 ? { provider } : {}),
+    ...(parallel !== undefined ? { parallel_tool_calls: parallel } : {}),
+    ...(exclude !== undefined ? { reasoning_exclude: exclude } : {}),
+    ...(user ? { user } : {}),
+  };
+}
+
 // Canonical tool declarations as Chat Completions function tools; in: options.tools, out: request `tools`.
 function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
@@ -195,7 +282,18 @@ 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" };
+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",
+};
 // The `input_audio.format` for an audio MIME type (see AUDIO_FORMAT above); in: contentPartsToBlocks, out: the format string.
 function audioFormatFor(mimeType?: string): string {
   const subtype = (mimeType || "").toLowerCase().split(";")[0]!.split("/")[1]?.replace(/^x-/, "") ?? "";
@@ -203,7 +301,12 @@ function audioFormatFor(mimeType?: string): string {
 }
 
 // `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" };
+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 {
@@ -211,7 +314,9 @@ function hasRemoteMedia(messages: ChatMessage[]): boolean {
     (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;
+        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);
       })
   );
@@ -258,10 +363,7 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPa
       const mimeType = (part as { mimeType?: string }).mimeType;
       // OpenAI chat audio shape (router parsed it live; capability routing
       // decides per model). Always inline — `input_audio` carries data only.
-      const norm = await normalizeMediaInput(
-        raw as string | Uint8Array | ArrayBuffer,
-        mimeType
-      );
+      const norm = await normalizeMediaInput(raw as string | Uint8Array | ArrayBuffer, mimeType);
       blocks.push({
         type: "input_audio",
         input_audio: { data: norm.base64Data, format: audioFormatFor(norm.mimeType) },
@@ -273,7 +375,12 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPa
       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;
+          : (
+              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: fileData },
@@ -283,6 +390,48 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPa
   return blocks;
 }
 
+// Folds one streamed `reasoning_details` chunk into the turn's blocks: chunks with the same index (else id) are one block whose text, summary, data and signature are concatenated or filled in, in order; in: the stream handler, out: the blocks replayed on the next request.
+function mergeReasoningDetails(blocks: Array<Record<string, unknown>>, chunk: unknown): void {
+  if (!chunk || typeof chunk !== "object" || Array.isArray(chunk)) return;
+  const c = chunk as Record<string, unknown>;
+  const same = blocks.find((b) =>
+    typeof c["index"] === "number" ? b["index"] === c["index"] : c["id"] != null && b["id"] === c["id"]
+  );
+  if (!same) {
+    blocks.push({ ...c });
+    return;
+  }
+  for (const [k, v] of Object.entries(c)) {
+    if (v === null || v === undefined) continue;
+    if ((k === "text" || k === "summary" || k === "data") && typeof v === "string" && typeof same[k] === "string")
+      same[k] = (same[k] as string) + v;
+    else same[k] = v;
+  }
+}
+
+// Adds a streamed `file` annotation (a parsed PDF) once per `file.hash`; in: the stream handler, out: the annotations replayed on the next request.
+function mergeAnnotation(blocks: Array<Record<string, unknown>>, chunk: unknown): void {
+  if (!chunk || typeof chunk !== "object" || (chunk as { type?: unknown }).type !== "file") return;
+  const hash = (chunk as { file?: { hash?: unknown } }).file?.hash;
+  if (typeof hash === "string" && blocks.some((b) => (b as { file?: { hash?: unknown } }).file?.hash === hash)) return;
+  blocks.push(chunk as Record<string, unknown>);
+}
+
+// The reasoning blocks and the parsed-PDF annotations of an assistant turn as OpenRouter returned them (both live in `providerSteps`, told apart by `type: "file"`); in: a stored assistant message, out: fullHistoryMessages.
+function storedReplay(m: { providerSteps?: { provider: string; steps: unknown[] } }): {
+  reasoning_details?: unknown[];
+  annotations?: unknown[];
+} {
+  if (m.providerSteps?.provider !== "openrouter") return {};
+  const isFile = (x: unknown): boolean => (x as { type?: unknown } | null)?.type === "file";
+  const annotations = m.providerSteps.steps.filter(isFile);
+  const details = m.providerSteps.steps.filter((x) => !isFile(x));
+  return {
+    ...(details.length > 0 ? { reasoning_details: details } : {}),
+    ...(annotations.length > 0 ? { annotations } : {}),
+  };
+}
+
 // A tool result as the text of a tool message; in: fullHistoryMessages, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
@@ -295,7 +444,10 @@ function resultToOutput(result: unknown): string {
  * carries everything. Assistant items carry no provider `id`/`status`
  * requirements (unlike the discontinued Responses skin).
  */
-async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessage[]> {
+async function fullHistoryMessages(
+  context: ProviderContext,
+  bridge = DEFAULT_PROMPTS.toolBridge
+): 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>();
@@ -326,18 +478,25 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
       // 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." });
+        messages.push({ role: "assistant", content: bridge });
       }
       if (typeof m.content === "string") {
-        if (m.content) { messages.push({ role: "user", content: m.content }); lastRole = "user"; }
+        if (m.content) {
+          messages.push({ role: "user", content: m.content });
+          lastRole = "user";
+        }
       } else {
         const blocks = await contentPartsToBlocks(m.content);
-        if (blocks.length > 0) { messages.push({ role: "user", content: blocks }); lastRole = "user"; }
+        if (blocks.length > 0) {
+          messages.push({ role: "user", content: blocks });
+          lastRole = "user";
+        }
       }
     } else if (m.role === "assistant") {
+      const replay = storedReplay(m);
       if (typeof m.content === "string") {
         if (m.content) {
-          messages.push({ role: "assistant", content: m.content });
+          messages.push({ role: "assistant", content: m.content, ...replay });
         }
         continue;
       }
@@ -353,8 +512,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
         } else if (part.type === "text" && part.text) {
           texts.push(part.text);
         }
-        // Prior-turn reasoning is NOT resent: chat history is messages +
-        // tool calls only (documented decision; avoids strict-route 400s).
+        // Reasoning is not rebuilt from text: the stored `reasoning_details` blocks are replayed verbatim below.
       }
       // Skip empty assistant turns (no text + no tool calls): strict
       // routes reject them, and they carry no signal (pi drop rule).
@@ -363,6 +521,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
         role: "assistant",
         content: texts.length > 0 ? texts.join("\n") : null,
         ...(calls.length > 0 ? { tool_calls: calls } : {}),
+        ...replay,
       });
       lastRole = "assistant";
     } else if (m.role === "tool") {
@@ -414,7 +573,27 @@ function mapUsage(raw?: ChatUsage): 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) { // an explicit 0 (a free model, a response-cache hit) is a known cost, not a missing one
+  // Media tokens are listed only when the provider reported more than zero of them.
+  const count = (n: unknown): number | undefined =>
+    typeof n === "number" && Number.isFinite(n) && n > 0 ? n : undefined;
+  const inDet = {
+    audioTokens: count(raw?.prompt_tokens_details?.audio_tokens),
+    videoTokens: count(raw?.prompt_tokens_details?.video_tokens),
+  };
+  const outDet = {
+    audioTokens: count(raw?.completion_tokens_details?.audio_tokens),
+    imageTokens: count(raw?.completion_tokens_details?.image_tokens),
+  };
+  const keep = (d: Record<string, number | undefined>): Record<string, number> | undefined => {
+    const kept = Object.fromEntries(Object.entries(d).filter(([, v]) => v !== undefined)) as Record<string, number>;
+    return Object.keys(kept).length > 0 ? kept : undefined;
+  };
+  const inKept = keep(inDet);
+  const outKept = keep(outDet);
+  if (inKept) usage.inputDetails = inKept;
+  if (outKept) usage.outputDetails = outKept;
+  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;
@@ -460,8 +639,15 @@ 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, /^~?anthropic\//.test(modelId) ? ["implicit", "5m", "1h"] : ["implicit"], `openrouter/${modelId}`);
+    const cache = resolveCache(
+      "openrouter",
+      options?.cache,
+      /^~?anthropic\//.test(modelId) ? ["implicit", "5m", "1h"] : ["implicit"],
+      `openrouter/${modelId}`
+    );
     warnIgnoredMediaResolution("openrouter", context.messages, `openrouter/${modelId}`, ["video"]);
+    warnIgnoredVideoProcessing("openrouter", context.messages, `openrouter/${modelId}`);
+    warnIgnoredToolMedia("openrouter", context.messages, `openrouter/${modelId}`);
 
     // Structured outputs: native `response_format` when supported, else
     // emulated via system-prompt instruction + client validation (catalog
@@ -479,17 +665,22 @@ export class OpenRouterChatCompletionsProvider implements Provider {
       outputEmulated = true;
       effectiveContext = {
         ...context,
-        systemPrompt: augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec),
+        systemPrompt: augmentSystemPromptWithStructuredOutput(
+          context.systemPrompt,
+          outputSpec,
+          options?.prompts?.structuredOutput
+        ),
       };
       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.",
+        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 = await fullHistoryMessages(effectiveContext);
+    const messages = await fullHistoryMessages(effectiveContext, options?.prompts?.toolBridge);
     const body: ChatRequestBody = {
       model: modelId,
       messages,
@@ -497,15 +688,21 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     };
     const orTools = toOpenRouterTools(tools);
     if (orTools) body.tools = orTools;
-    const toolChoice = mapToolChoiceToOpenRouterChat(
-      options?.toolChoice as "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
-    );
+    const toolChoice = mapToolChoiceToOpenRouterChat(options?.toolChoice);
     if (toolChoice !== undefined) body.tool_choice = toolChoice;
-    if (effort) body.reasoning = { effort };
+    const env = openRouterEnvOptions(options);
+    if (effort || env.reasoning_exclude !== undefined)
+      body.reasoning = {
+        ...(effort ? { effort } : {}),
+        ...(env.reasoning_exclude !== undefined ? { exclude: env.reasoning_exclude } : {}),
+      };
+    if (env.provider) body.provider = env.provider;
+    if (env.parallel_tool_calls !== undefined && orTools) body.parallel_tool_calls = env.parallel_tool_calls;
+    if (env.user) body.user = env.user;
     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, "openrouter", `openrouter/${modelId}`));
+    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) {
@@ -537,11 +734,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
   ): RequestInit {
     // Attribution + session headers mirror the previous transport exactly
     // (HTTP-Referer / X-Title / x-session-id / x-client-request-id).
-    const headers: Record<string, string> = buildSessionHeaders(
-      "openrouter",
-      options?.headers,
-      sessionId
-    );
+    const headers: Record<string, string> = buildSessionHeaders("openrouter", options?.headers, sessionId);
     setHeaderCaseInsensitive(headers, "Content-Type", "application/json");
     if (apiKey !== "unused") setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
     return { method: "POST", headers, body: JSON.stringify(body), signal };
@@ -593,10 +786,16 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     options?: ProviderRequestOptions
   ): Promise<ProviderGenerateResult> {
     // 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));
+    const { signal, cleanup } = combinedSignal(
+      options?.signal,
+      timeoutFor(options as { timeoutMs?: number } | undefined)
+    );
     try {
       // 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 events = this.streamInto(new AssistantMessageEventStream({ buffer: false }), model, context, {
+        ...options,
+        signal,
+      });
       const res = await events.result();
       return {
         text: res.text,
@@ -610,6 +809,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         provider: "openrouter",
         raw: res.raw,
         durationMs: res.durationMs,
+        providerSteps: res.providerSteps,
       };
     } catch (err) {
       // A stream reports its own generic abort; the caller's reason (`interrupt(new Error("..."))`) is what the run should carry.
@@ -675,9 +875,14 @@ 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: () => 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),
+          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,
           label: { providerId: "openrouter", modelId: clean },
@@ -686,7 +891,11 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         res.headers.forEach((v, k) => {
           responseHeaders[k] = v;
         });
-        const responseMeta: Record<string, unknown> & { status: number; statusText: string; headers: Record<string, string> } = { status: res.status, statusText: res.statusText, headers: responseHeaders };
+        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);
 
         let text = "";
@@ -696,6 +905,10 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         // Index of the most recent tool-call delta: unindexed chunks continue
         // it (falling back to calls.size would fork a phantom call per chunk).
         let lastToolIndex = 0;
+        // The turn's reasoning blocks exactly as returned, replayed on the next request (tool turns need them).
+        const reasoningBlocks: Array<Record<string, unknown>> = [];
+        // Parsed PDFs (`file` annotations) of the turn: sent back so OpenRouter does not parse the same file again.
+        const annotationBlocks: Array<Record<string, unknown>> = [];
         let usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finishReason = "stop";
         let sawFinishReason = false;
@@ -721,7 +934,9 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           }
           // Mid-stream provider error: top-level `error`, HTTP stays 200.
           // Must surface — resolving empty success hides it.
-          const topError = msg["error"] as { message?: string; code?: string | number; metadata?: { error_type?: string } } | undefined;
+          const topError = msg["error"] as
+            | { message?: string; code?: string | number; metadata?: { error_type?: string } }
+            | undefined;
           if (topError && typeof topError === "object") {
             const message =
               typeof topError.message === "string" && topError.message
@@ -738,7 +953,8 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           if (typeof msg["id"] === "string" && !responseId) {
             responseId = msg["id"] as string;
           }
-          const choice = (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
+          const choice =
+            (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
           const delta = (choice["delta"] as Record<string, unknown>) ?? {};
           // Text delta (content-free accounting frames carry "" — ignored).
           // Refusal deltas surface as text with a `refusal` finish.
@@ -757,6 +973,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           const details = delta["reasoning_details"];
           if (Array.isArray(details)) {
             for (const block of details) {
+              mergeReasoningDetails(reasoningBlocks, block);
               const t = (block as { text?: string })?.text;
               if (typeof t === "string" && t) {
                 thinking += t;
@@ -778,6 +995,8 @@ export class OpenRouterChatCompletionsProvider implements Provider {
               partialThinking: thinking,
             });
           }
+          if (Array.isArray(delta["annotations"]))
+            for (const a of delta["annotations"]) mergeAnnotation(annotationBlocks, a);
           // Tool-call deltas accumulate per choice index.
           const deltaCalls = delta["tool_calls"];
           if (Array.isArray(deltaCalls)) {
@@ -887,6 +1106,9 @@ export class OpenRouterChatCompletionsProvider implements Provider {
             response: { ...responseMeta, body: completedBody, badFrames } as unknown as ProviderRawData["response"],
           },
           durationMs: Date.now() - startTime,
+          ...(reasoningBlocks.length + annotationBlocks.length > 0
+            ? { providerSteps: { provider: "openrouter", steps: [...reasoningBlocks, ...annotationBlocks] } }
+            : {}),
         });
         eventStream.push({ type: "done", delta: "", usage, finishReason, responseId });
         eventStream.end(finalResponse);

package/src/providers/registry.ts

@@ -31,12 +31,7 @@ providerRegistry.set("openai", openaiProvider);
 //   MODEL="cerebras/gpt-oss-120b"      + CEREBRAS_API_KEY + CEREBRAS_BASE_URL
 //   MODEL="ollama/qwen2.5-coder"        + OLLAMA_BASE_URL (key optional for local)
 // ---------------------------------------------------------------------------
-const FIRST_CLASS = new Set([
-  "google",
-  "gemini",
-  "openrouter",
-  "openai",
-]);
+const FIRST_CLASS = new Set(["google", "gemini", "openrouter", "openai"]);
 
 // Removed providers: fail loudly instead of misrouting. OpenCode free models
 // are harness-only since 2026, so the opencode/opencode-go prefixes no longer
@@ -168,9 +163,7 @@ export function resolveModel(model: string | ModelSpec): ResolvedModel {
   // Try catalog first for any provider/model
   const tryCatalogLookup = (prov: string, mid: string): ModelSpec | undefined => {
     return (
-      getModelFromCatalog(prov, mid) ||
-      getModelFromCatalog(prov.toLowerCase(), mid) ||
-      getModelFromCatalog(mid, mid)
+      getModelFromCatalog(prov, mid) || getModelFromCatalog(prov.toLowerCase(), mid) || getModelFromCatalog(mid, mid)
     );
   };
 
@@ -194,11 +187,7 @@ export function resolveModel(model: string | ModelSpec): ResolvedModel {
     }
 
     // 2. Unified layer: any non-first-class prefix routes to auto-created custom provider
-    const isExplicitOther = [
-      "google",
-      "gemini",
-      "openrouter",
-    ].includes(providerPrefix);
+    const isExplicitOther = ["google", "gemini", "openrouter"].includes(providerPrefix);
 
     if (!isExplicitOther && providerPrefix !== "openai") {
       const envName = providerPrefix.toUpperCase().replace(/[^A-Z0-9]/g, "_");
@@ -210,8 +199,7 @@ export function resolveModel(model: string | ModelSpec): ResolvedModel {
         getEnv(`${envName}_BASE_API_KEY`)
       );
 
-      const looksLikeOpenRouterScope =
-        parts.length === 2 && modelStr.includes(":") && !hasDedicatedEnv;
+      const looksLikeOpenRouterScope = parts.length === 2 && modelStr.includes(":") && !hasDedicatedEnv;
 
       if (!looksLikeOpenRouterScope) {
         const custom = ensureCustomProvider(providerPrefix);
@@ -251,9 +239,7 @@ export function resolveModel(model: string | ModelSpec): ResolvedModel {
     }
 
     // Check catalog for this exact provider/model
-    const catalogSpec =
-      tryCatalogLookup(providerPrefix, remainingModel) ||
-      tryCatalogLookup(providerPrefix, modelStr);
+    const catalogSpec = tryCatalogLookup(providerPrefix, remainingModel) || tryCatalogLookup(providerPrefix, modelStr);
     if (catalogSpec) {
       const internalProvider = getProvider(catalogSpec.provider);
       return { provider: internalProvider, modelId: catalogSpec.id, modelSpec: catalogSpec };
@@ -277,8 +263,7 @@ export function resolveModel(model: string | ModelSpec): ResolvedModel {
 
     // Fallback custom provider
     const fallbackCustom = ensureCustomProvider(providerPrefix);
-    const fallbackSpec =
-      fallbackCustom.getModel(remainingModel) || fallbackCustom.getModel(modelStr);
+    const fallbackSpec = fallbackCustom.getModel(remainingModel) || fallbackCustom.getModel(modelStr);
     return {
       provider: fallbackCustom,
       modelId: remainingModel,