@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/core/middlewares/tool-repetition-guard.ts

@@ -6,22 +6,83 @@ import {
 import { type AgentMiddleware, createMiddleware } from 'langchain';
 import type { Logger } from '../../plugin-api/types';
 import { NOOP_LOGGER } from '../utils';
+import { isCapabilityGateRefusal } from './capability-gate';
+import { turnCarryOf, turnStart } from './turn-boundary';
+
+export { turnStart };
+
+/** Identical successful calls a turn may make, per effect. */
+export interface RepetitionCaps {
+  reads: number;
+  writes: number;
+}
+
+export const DEFAULT_REPETITION_CAPS: RepetitionCaps = { reads: 5, writes: 1 };
+
+/**
+ * Parse `TURN_MAX_IDENTICAL_READS` / `TURN_MAX_IDENTICAL_WRITES`; anything
+ * that is not a positive number keeps its default (as `turnLimitsFromEnv`).
+ */
+export function repetitionCapsFromEnv(env: {
+  TURN_MAX_IDENTICAL_READS?: unknown;
+  TURN_MAX_IDENTICAL_WRITES?: unknown;
+}): RepetitionCaps {
+  const positive = (raw: unknown, fallback: number): number => {
+    if (typeof raw !== 'number' && typeof raw !== 'string') return fallback;
+    if (raw === '') return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;
+  };
+  return {
+    reads: positive(
+      env.TURN_MAX_IDENTICAL_READS,
+      DEFAULT_REPETITION_CAPS.reads,
+    ),
+    writes: positive(
+      env.TURN_MAX_IDENTICAL_WRITES,
+      DEFAULT_REPETITION_CAPS.writes,
+    ),
+  };
+}
 
 export interface ToolRepetitionGuardMiddlewareOptions {
   /**
-   * How many messages back to scan for a prior identical failed call.
-   * Default 20 — enough to catch in-turn loops without trawling whole histories.
+   * At most this many messages back to scan for a prior identical failed
+   * call. The scan never reaches past the start of the current turn;
+   * unset, it covers the whole turn.
    */
   lookback?: number;
+  /**
+   * Effect of a tool by name (the main agent passes its read/write map;
+   * a sub-agent dispatch is a write). Unset, every tool is capped as a read.
+   */
+  effectOf?: (toolName: string) => 'read' | 'write';
+  /** Identical successful calls of a read allowed per turn (default 5, `TURN_MAX_IDENTICAL_READS`). */
+  maxIdenticalReads?: number;
+  /** Identical successful calls of a write allowed per turn (default 1, `TURN_MAX_IDENTICAL_WRITES`). */
+  maxIdenticalWrites?: number;
   /** Optional logger; defaults to a no-op. */
   logger?: Logger;
 }
 
 /**
  * Detects when the agent issues the same `(toolName, args)` pair after that
- * exact call already failed inside the recent window, and short-circuits
- * before the tool is invoked again. The short-circuit message quotes the
- * earlier error and tells the model to change tools/args instead.
+ * exact call already failed in the current turn, and short-circuits before
+ * the tool is invoked again. The short-circuit message quotes the earlier
+ * error and tells the model to change tools/args instead.
+ *
+ * A turn starts at the latest human message (the user's, or a sub-agent's
+ * task) — not at a human message a tool injects mid-turn (see `turnStart`).
+ * A failure from an earlier turn never blocks: the user may have fixed its
+ * cause and asked again ("I granted access, try again").
+ *
+ * It also caps identical calls that SUCCEEDED in the turn: a write may run
+ * once per turn with the same arguments (again would repeat its effect —
+ * the user can ask again in a new message), a read up to
+ * `maxIdenticalReads` times (room for polling, not for a loop). An
+ * identical call earlier in the same model response counts too, since the
+ * calls of one response run side by side and neither sees the other's
+ * result.
  *
  * `toolRetryMiddleware` retries inside one call; this guard prevents the
  * model from making the *next* identical call.
@@ -30,7 +91,10 @@ export const createToolRepetitionGuardMiddleware = (
   options: ToolRepetitionGuardMiddlewareOptions = {},
 ): AgentMiddleware => {
   const logger = options.logger ?? NOOP_LOGGER;
-  const lookback = options.lookback ?? 20;
+  const lookback = options.lookback ?? Number.POSITIVE_INFINITY;
+  const maxReads = options.maxIdenticalReads ?? DEFAULT_REPETITION_CAPS.reads;
+  const maxWrites =
+    options.maxIdenticalWrites ?? DEFAULT_REPETITION_CAPS.writes;
 
   return createMiddleware({
     name: 'ToolRepetitionGuardMiddleware',
@@ -41,19 +105,22 @@ export const createToolRepetitionGuardMiddleware = (
 
       const argsKey = canonicalArgsKey(toolCall.args);
       const messages = state.messages ?? [];
-      const start = Math.max(0, messages.length - lookback);
-
-      for (let i = messages.length - 1; i >= start; i--) {
-        const msg = messages[i];
-        if (!(msg instanceof ToolMessage)) continue;
-        if (msg.status !== 'error') continue;
-        if (msg.name !== toolName) continue;
-
-        const priorArgs = findToolCallArgsById(messages, msg.tool_call_id);
-        if (priorArgs === undefined) continue;
-        if (canonicalArgsKey(priorArgs) !== argsKey) continue;
+      const opening = turnStart(messages);
+      const start = Math.max(opening, messages.length - lookback, 0);
+      const argsById = toolCallArgsById(messages, start);
+      // The turn's calls a mid-turn summary condensed away (oldest first):
+      // only while the lookback still reaches the summary.
+      const openingMessage = messages[opening];
+      const carried = (
+        start === opening && openingMessage
+          ? (turnCarryOf(openingMessage) ?? [])
+          : []
+      ).filter(
+        (call) =>
+          call.name === toolName && canonicalArgsKey(call.args) === argsKey,
+      );
 
-        const priorError = toolMessageText(msg);
+      const failedInTurn = (priorError: string): ToolMessage => {
         logger.warn(
           `Repetition guard: short-circuiting duplicate failed call to ${toolName}`,
           { toolName, priorError },
@@ -72,13 +139,129 @@ export const createToolRepetitionGuardMiddleware = (
           name: toolName,
           status: 'error',
         });
+      };
+
+      for (let i = messages.length - 1; i >= start; i--) {
+        const msg = messages[i];
+        if (!(msg instanceof ToolMessage)) continue;
+        if (msg.status !== 'error') continue;
+        // The capability gate refused it without running it; after a
+        // `load_capability` the same call is the expected next step.
+        if (isCapabilityGateRefusal(msg)) continue;
+        if (msg.name !== toolName) continue;
+
+        const priorArgs = argsById.get(msg.tool_call_id);
+        if (priorArgs === undefined) continue;
+        if (canonicalArgsKey(priorArgs) !== argsKey) continue;
+
+        return failedInTurn(toolMessageText(msg));
+      }
+      const carriedFailure = carried.findLast(
+        (call) => call.status === 'error',
+      );
+      if (carriedFailure) return failedInTurn(carriedFailure.result);
+
+      // Identical calls that succeeded in this turn, plus identical calls
+      // earlier in this same model response (still running beside this one).
+      let identical = 0;
+      let lastResult: string | undefined;
+      for (const call of carried) {
+        if (call.status === 'error') continue;
+        identical += 1;
+        lastResult = call.result;
+      }
+      for (let i = start; i < messages.length; i++) {
+        const msg = messages[i];
+        if (!(msg instanceof ToolMessage)) continue;
+        if (msg.status === 'error' || msg.name !== toolName) continue;
+        const priorArgs = argsById.get(msg.tool_call_id);
+        if (priorArgs === undefined) continue;
+        if (canonicalArgsKey(priorArgs) !== argsKey) continue;
+        identical += 1;
+        lastResult = toolMessageText(msg);
+      }
+      for (const sibling of stepCallsBefore(messages, toolCall.id, start)) {
+        if (
+          sibling.name === toolName &&
+          canonicalArgsKey(sibling.args) === argsKey
+        )
+          identical += 1;
       }
+      const effect = options.effectOf?.(toolName) ?? 'read';
+      const cap = effect === 'write' ? maxWrites : maxReads;
+      if (identical < cap) return handler(toolCallRequest);
 
-      return handler(toolCallRequest);
+      logger.warn(
+        `Repetition guard: ${toolName} already ran ${identical} time(s) this turn with these exact arguments (${effect} cap ${cap}); not run again`,
+      );
+      const earlier =
+        lastResult !== undefined
+          ? ['', 'It returned:', '', excerpt(lastResult)]
+          : [];
+      return new ToolMessage({
+        content: (effect === 'write'
+          ? [
+              lastResult !== undefined
+                ? `\`${toolName}\` already ran with these exact arguments in this turn, so it was NOT run again: running it twice would repeat its effect.`
+                : `An identical \`${toolName}\` call is already part of this step, so this one was NOT run: running it twice would repeat its effect.`,
+              ...earlier,
+              '',
+              'Use that outcome. If the user wants it done again, confirm with them — they can ask again in a new message.',
+            ]
+          : [
+              `You have already called \`${toolName}\` with these exact arguments ${identical} times in this turn, so it was NOT called again.`,
+              ...earlier,
+              '',
+              'Use the result you have, change the arguments, or pick a different tool.',
+            ]
+        ).join('\n'),
+        tool_call_id: toolCall.id ?? '',
+        name: toolName,
+        status: 'error',
+      });
     },
   });
 };
 
+const EXCERPT_CHARS = 800;
+
+function excerpt(text: string): string {
+  return text.length <= EXCERPT_CHARS
+    ? text
+    : `${text.slice(0, EXCERPT_CHARS)}… (${text.length - EXCERPT_CHARS} more characters)`;
+}
+
+/** Tool call id → arguments for every AI tool call from `start` on. */
+function toolCallArgsById(
+  messages: readonly BaseMessage[],
+  start: number,
+): Map<string, unknown> {
+  const out = new Map<string, unknown>();
+  for (let i = start; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || !AIMessage.isInstance(m)) continue;
+    for (const tc of m.tool_calls ?? []) if (tc.id) out.set(tc.id, tc.args);
+  }
+  return out;
+}
+
+/** The calls that precede `callId` in the model response that issued it. */
+function stepCallsBefore(
+  messages: readonly BaseMessage[],
+  callId: string | undefined,
+  start: number,
+): Array<{ name: string; args: unknown }> {
+  if (!callId) return [];
+  for (let i = messages.length - 1; i >= start; i--) {
+    const m = messages[i];
+    if (!m || !AIMessage.isInstance(m)) continue;
+    const calls = m.tool_calls ?? [];
+    const at = calls.findIndex((tc) => tc.id === callId);
+    if (at >= 0) return calls.slice(0, at);
+  }
+  return [];
+}
+
 function canonicalArgsKey(args: unknown): string {
   if (args === null || args === undefined) return 'null';
   if (typeof args !== 'object') return JSON.stringify(args);
@@ -107,19 +290,3 @@ function toolMessageText(msg: ToolMessage): string {
   }
   return '';
 }
-
-function findToolCallArgsById(
-  messages: BaseMessage[],
-  callId: string | undefined,
-): unknown {
-  if (!callId) return undefined;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const m = messages[i];
-    if (!AIMessage.isInstance(m)) continue;
-    const toolCalls = m.tool_calls;
-    if (!toolCalls) continue;
-    const hit = toolCalls.find((tc) => tc.id === callId);
-    if (hit) return hit.args;
-  }
-  return undefined;
-}

package/src/core/middlewares/turn-boundary.ts

@@ -0,0 +1,162 @@
+/**
+ * Where the current turn starts in a thread's messages, and what a mid-turn
+ * summary keeps of the turn it condensed.
+ *
+ * A turn opens at the latest human message the user (or, in a sub-agent,
+ * the dispatching agent) wrote. The runtime writes human messages of its
+ * own — the summary that replaces a condensed history, the re-attachment
+ * `view_attachment` appends — and neither opens a turn.
+ *
+ * The summarizer can fire between two model steps of one turn and replace
+ * everything but the last few messages, the turn's opening message and its
+ * earlier tool calls included. The summary it writes then carries the
+ * calls of the turn it removed (`turn_carry`) and stands in as the turn's
+ * opening, so the repetition guard still knows what already ran this turn.
+ * A summary written at a turn boundary carries nothing and opens nothing.
+ */
+import {
+  AIMessage,
+  HumanMessage,
+  ToolMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
+import { isAttachmentViewMessage } from '../../attachments/retention';
+import { isCapabilityGateRefusal } from './capability-gate';
+
+export const SUMMARY_PREFIX = 'Here is a summary of the conversation to date:';
+
+/**
+ * `true` for the condensed-history message the summarization middleware
+ * writes into graph state. List endpoints use this to keep it out of the
+ * user-visible transcript.
+ */
+export function isSummarizationMessage(message: BaseMessage): boolean {
+  if (message.additional_kwargs?.lc_source === 'summarization') return true;
+  const { content } = message;
+  return typeof content === 'string' && content.startsWith(SUMMARY_PREFIX);
+}
+
+/** A tool call of the current turn that a mid-turn summary condensed away. */
+export interface CarriedToolCall {
+  name: string;
+  args: unknown;
+  /** `error` when its result was an error (the capability gate's refusals are not carried). */
+  status: 'success' | 'error';
+  /** The start of its result, for the repetition guard to quote. */
+  result: string;
+}
+
+/** `additional_kwargs` key of the calls a mid-turn summary carries. */
+const TURN_CARRY = 'turn_carry';
+
+/** Characters of a carried result kept (the guard quotes at most this much). */
+export const CARRIED_RESULT_CHARS = 800;
+
+/** The calls `message` carries when it is a summary written mid-turn, else `undefined`. */
+export function turnCarryOf(
+  message: BaseMessage,
+): CarriedToolCall[] | undefined {
+  if (!isSummarizationMessage(message)) return undefined;
+  const raw: unknown = message.additional_kwargs?.[TURN_CARRY];
+  if (!Array.isArray(raw)) return undefined;
+  return raw.flatMap((entry: unknown): CarriedToolCall[] => {
+    if (!entry || typeof entry !== 'object') return [];
+    const name: unknown = Reflect.get(entry, 'name');
+    const status: unknown = Reflect.get(entry, 'status');
+    const result: unknown = Reflect.get(entry, 'result');
+    if (typeof name !== 'string') return [];
+    if (status !== 'success' && status !== 'error') return [];
+    return [
+      {
+        name,
+        args: Reflect.get(entry, 'args'),
+        status,
+        result: typeof result === 'string' ? result : '',
+      },
+    ];
+  });
+}
+
+/**
+ * Index of the message that opens the current turn: the latest human
+ * message other than the ones the runtime writes itself, or a summary that
+ * carries the calls of a turn it condensed mid-way. 0 when there is none.
+ */
+export function turnStart(messages: readonly BaseMessage[]): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message || !HumanMessage.isInstance(message)) continue;
+    if (isSummarizationMessage(message)) {
+      if (turnCarryOf(message) !== undefined) return i;
+      continue;
+    }
+    if (!isAttachmentViewMessage(message)) return i;
+  }
+  return 0;
+}
+
+function resultText(message: ToolMessage): string {
+  const { content } = message;
+  const text =
+    typeof content === 'string'
+      ? content
+      : content
+          .map((block) =>
+            typeof block === 'string'
+              ? block
+              : 'text' in block && typeof block.text === 'string'
+                ? block.text
+                : '',
+          )
+          .join('\n');
+  return text.length <= CARRIED_RESULT_CHARS
+    ? text
+    : `${text.slice(0, CARRIED_RESULT_CHARS)}…`;
+}
+
+/**
+ * The calls of the current turn that a summary of `before` would remove: the
+ * turn's opening is among the removed messages (it is not in `keptIds`), so
+ * the turn continues after the summary. `undefined` when the summary falls
+ * on a turn boundary (the whole current turn is kept). Calls an earlier
+ * mid-turn summary of this same turn carried are carried on.
+ */
+export function carriedCallsOfTurn(
+  before: readonly BaseMessage[],
+  keptIds: ReadonlySet<string>,
+): CarriedToolCall[] | undefined {
+  const start = turnStart(before);
+  const opening = before[start];
+  if (!opening || !HumanMessage.isInstance(opening)) return undefined;
+  if (opening.id !== undefined && keptIds.has(opening.id)) return undefined;
+  const carried: CarriedToolCall[] = [...(turnCarryOf(opening) ?? [])];
+  const calls = new Map<string, { name: string; args: unknown }>();
+  for (let i = start; i < before.length; i += 1) {
+    const message = before[i];
+    if (!message || (message.id !== undefined && keptIds.has(message.id)))
+      continue;
+    if (AIMessage.isInstance(message)) {
+      for (const call of message.tool_calls ?? [])
+        if (call.id) calls.set(call.id, { name: call.name, args: call.args });
+      continue;
+    }
+    if (!ToolMessage.isInstance(message) || isCapabilityGateRefusal(message))
+      continue;
+    const call = calls.get(message.tool_call_id);
+    if (!call) continue;
+    carried.push({
+      name: message.name ?? call.name,
+      args: call.args,
+      status: message.status === 'error' ? 'error' : 'success',
+      result: resultText(message),
+    });
+  }
+  return carried;
+}
+
+/** `additional_kwargs` that make a summary carry `calls` (see `turnCarryOf`). */
+export function turnCarryKwargs(
+  calls: readonly CarriedToolCall[],
+): Record<string, unknown> {
+  return { [TURN_CARRY]: calls.map((call) => ({ ...call })) };
+}

package/src/core/openrouter-pricing.ts

@@ -11,12 +11,28 @@
  *
  * Per isolate rather than per process: a cold isolate pays one ~100 ms fetch
  * on its first `/models`, then serves from memory until evicted.
+ *
+ * Every turn reads it (the context-window resolver), so it never holds a
+ * turn up for long: the fetch is cut off after `OPENROUTER_FETCH_TIMEOUT_MS`,
+ * concurrent callers share one fetch, an expired listing is served while a
+ * fresh one is fetched in the background, and a failure is remembered for
+ * `OPENROUTER_FAILURE_TTL_MS` before the next attempt.
  */
 import { z } from 'zod';
 import type { ModelPrice } from './llm';
 
 export const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
 export const OPENROUTER_PRICE_CACHE_TTL_MS = 60 * 60 * 1000;
+/** How long a `/models` fetch (response and body) may take before it counts as failed. */
+export const OPENROUTER_FETCH_TIMEOUT_MS = 3_000;
+/** How long a failed fetch is remembered before the next one is attempted. */
+export const OPENROUTER_FAILURE_TTL_MS = 60_000;
+/**
+ * Past its timeout plus this, a shared fetch that never settled (the runtime
+ * dropped the request that started it, its timer with it) is abandoned and
+ * the next caller starts a new one.
+ */
+export const OPENROUTER_INFLIGHT_MARGIN_MS = 1_000;
 
 /**
  * OpenRouter returns `pricing.prompt` / `pricing.completion` as strings in USD
@@ -52,6 +68,20 @@ interface PriceCache {
 }
 
 let cache: PriceCache | null = null;
+interface InflightFetch {
+  done: Promise<void>;
+  /** When it started, by the caller's clock. */
+  startedAt: number;
+  /** How long it may stay shared (its timeout plus the margin). */
+  limitMs: number;
+}
+
+/** The fetch in flight, shared by every caller that needs it. */
+let inflight: InflightFetch | null = null;
+/** When the last fetch failed (by the caller's clock); `null` after a success. */
+let failedAt: number | null = null;
+/** Bumped by a reset: a refresh started before it settles without writing. */
+let generation = 0;
 
 function parseContextLengths(
   data: z.infer<typeof openRouterModelsSchema>['data'],
@@ -96,33 +126,62 @@ export interface FetchOpenRouterPricesOptions {
   fetch?: (input: string, init?: RequestInit) => Promise<Response>;
   now?: () => number;
   logger?: { warn: (message: string) => void };
+  /** Fetch timeout (default `OPENROUTER_FETCH_TIMEOUT_MS`). */
+  timeoutMs?: number;
+  /**
+   * Keeps a background refresh alive after the caller has its answer
+   * (`ctx.waitUntil` on Workers). Without it the refresh is merely detached.
+   */
+  waitUntil?: (work: Promise<unknown>) => void;
 }
 
-/**
- * Live OpenRouter prices keyed by model id ($/million tokens). Cached for an
- * hour. Never throws: on any failure it returns the last cached map, or an
- * empty map (so the caller falls back to the catalog's baseline prices).
- */
-export async function fetchOpenRouterPrices(
-  opts: FetchOpenRouterPricesOptions = {},
-): Promise<ReadonlyMap<string, ModelPrice>> {
+/** `work`, or a rejection once `ms` have passed (the timer never outlives it). */
+function withTimeout<T>(
+  work: Promise<T>,
+  ms: number,
+  controller: AbortController,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error(`OpenRouter /models timed out after ${ms} ms`);
+      error.name = 'TimeoutError';
+      controller.abort(error);
+      reject(error);
+    }, ms);
+  });
+  return Promise.race([work, timeout]).finally(() => clearTimeout(timer));
+}
+
+/** One fetch of the listing into `cache`; a failure is logged and remembered, never thrown. */
+async function refresh(opts: FetchOpenRouterPricesOptions): Promise<void> {
   const now = opts.now ?? Date.now;
-  if (cache && now() - cache.fetchedAt < OPENROUTER_PRICE_CACHE_TTL_MS) {
-    return cache.prices;
-  }
   // The global `fetch` must be called as a function of the global scope on
   // workerd ("Illegal invocation" when handed around as a bare reference).
   const fetchImpl =
     opts.fetch ?? ((input: string, init?: RequestInit) => fetch(input, init));
   const logger = opts.logger ?? console;
+  const controller = new AbortController();
+  const startedIn = generation;
   try {
-    const response = await fetchImpl(OPENROUTER_MODELS_URL, {
-      headers: opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {},
-    });
-    if (!response.ok) {
-      throw new Error(`OpenRouter /models returned HTTP ${response.status}`);
-    }
-    const parsed = openRouterModelsSchema.safeParse(await response.json());
+    const parsed = await withTimeout(
+      (async () => {
+        const response = await fetchImpl(OPENROUTER_MODELS_URL, {
+          headers: opts.apiKey
+            ? { Authorization: `Bearer ${opts.apiKey}` }
+            : {},
+          signal: controller.signal,
+        });
+        if (!response.ok) {
+          throw new Error(
+            `OpenRouter /models returned HTTP ${response.status}`,
+          );
+        }
+        return openRouterModelsSchema.safeParse(await response.json());
+      })(),
+      opts.timeoutMs ?? OPENROUTER_FETCH_TIMEOUT_MS,
+      controller,
+    );
     if (!parsed.success) {
       throw new Error(`Unexpected /models payload: ${parsed.error.message}`);
     }
@@ -130,19 +189,87 @@ export async function fetchOpenRouterPrices(
     if (prices.size === 0) {
       throw new Error('OpenRouter /models returned no usable pricing');
     }
+    if (generation !== startedIn) return;
     cache = {
       fetchedAt: now(),
       prices,
       contextLengths: parseContextLengths(parsed.data.data),
     };
-    return prices;
+    failedAt = null;
   } catch (error) {
+    if (generation !== startedIn) return;
+    failedAt = now();
     logger.warn(
-      `[models] live OpenRouter pricing unavailable — serving baseline prices: ${
+      `[models] live OpenRouter pricing unavailable — serving ${cache ? 'the last listing' : 'baseline prices'}: ${
         error instanceof Error ? error.message : String(error)
       }`,
     );
-    return cache?.prices ?? new Map<string, ModelPrice>();
+  }
+}
+
+/**
+ * Live OpenRouter prices keyed by model id ($/million tokens). Cached for an
+ * hour. Never throws: on any failure it returns the last cached map, or an
+ * empty map (so the caller falls back to the catalog's baseline prices).
+ * Waits at most the fetch timeout, and only when nothing is cached.
+ */
+export async function fetchOpenRouterPrices(
+  opts: FetchOpenRouterPricesOptions = {},
+): Promise<ReadonlyMap<string, ModelPrice>> {
+  const now = opts.now ?? Date.now;
+  if (cache && now() - cache.fetchedAt < OPENROUTER_PRICE_CACHE_TTL_MS) {
+    return cache.prices;
+  }
+  // A clock that went backwards does not keep a failure remembered.
+  const sinceFailure = failedAt === null ? null : now() - failedAt;
+  const failedRecently =
+    sinceFailure !== null &&
+    sinceFailure >= 0 &&
+    sinceFailure < OPENROUTER_FAILURE_TTL_MS;
+  if (!failedRecently) {
+    const limitMs =
+      (opts.timeoutMs ?? OPENROUTER_FETCH_TIMEOUT_MS) +
+      OPENROUTER_INFLIGHT_MARGIN_MS;
+    if (inflight) {
+      const age = now() - inflight.startedAt;
+      if (age < 0 || age > inflight.limitMs) inflight = null;
+    }
+    const shared = inflight ?? startRefresh(opts, now(), limitMs);
+    if (!cache) await settledWithin(shared.done, limitMs);
+    else opts.waitUntil?.(shared.done);
+  }
+  return cache?.prices ?? new Map<string, ModelPrice>();
+}
+
+function startRefresh(
+  opts: FetchOpenRouterPricesOptions,
+  startedAt: number,
+  limitMs: number,
+): InflightFetch {
+  const entry: InflightFetch = {
+    done: refresh(opts).finally(() => {
+      // An abandoned fetch that settles late leaves its successor alone.
+      if (inflight === entry) inflight = null;
+    }),
+    startedAt,
+    limitMs,
+  };
+  inflight = entry;
+  return entry;
+}
+
+/** Waits for `work`, or for `ms` on this caller's own timer, whichever is first. */
+async function settledWithin(work: Promise<void>, ms: number): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      work,
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, ms);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
   }
 }
 
@@ -159,7 +286,13 @@ export async function fetchOpenRouterContextLengths(
   return cache?.contextLengths ?? new Map<string, number>();
 }
 
-/** Test seam: clear the in-memory price cache between cases. */
+/**
+ * Test seam: clear the in-memory price cache, the shared fetch and the
+ * remembered failure. A refresh still running settles without writing.
+ */
 export function resetOpenRouterPriceCache(): void {
   cache = null;
+  inflight = null;
+  failedAt = null;
+  generation += 1;
 }