omnirush 0.8.6 → 0.9.0

package/assets/extensions/omnirush/subagents-lib.ts

@@ -0,0 +1,623 @@
+// subagents-lib — the sub-agent model and effort picker (as the desktop app's
+// Settings > Preferences > Model "Sub-agents: model" / "Sub-agent effort"
+// and its composer "Sub-agents" menu): which omnirush.ai model and effort
+// the spawn_agents children run on, at every nesting layer, and the fallback
+// to the main agent's model when that model cannot serve them.
+//
+// Who does what:
+//   - `/subagents` (subagents.ts) reads and writes the setting, kept in
+//     <omnirush dir>/settings.json under "subagents"; --subagent-model /
+//     --subagent-effort and OMNIRUSH_SUBAGENT_MODEL / _EFFORT override it for
+//     one run. Untouched ("same" for both) a child runs on the delegating
+//     agent's model and the main agent's effort.
+//   - spawn_agents (agents.ts) resolves every task against it
+//     (resolveSubagentModel) and starts the child with that --model and
+//     --thinking; a task's own `model` wins over the picked one.
+//   - A picked model that is not in the account's catalog (the list the
+//     launcher fetched from GET /v1/models), or that the gateway refused in
+//     the last five minutes, resolves to the main model instead (a
+//     "selection" fallback, noted on the sub-agent's result and trace title).
+//   - A child whose model differs from the main one gets the main model in
+//     its environment (OMNIRUSH_SUBAGENT_FALLBACK_MODEL / _EFFORT); its
+//     gateway guard (sota.ts) sends a request the gateway refuses
+//     (model_unavailable and friends at once, 429/503 after one more try)
+//     again on the main model, marks the model refused for five minutes
+//     (a file every process of this machine reads) and records the model
+//     that really answered on the message.
+//
+// Pure helpers plus small synchronous file helpers; node:test covers them.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+
+/** Every effort, lowest first (the gateway's spellings; pi says "off" for none). */
+export const EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type Effort = (typeof EFFORTS)[number];
+const EFFORT_RANK: Record<string, number> = Object.fromEntries(EFFORTS.map((effort, index) => [effort, index]));
+
+/** The Codex route's levels (Astra, Sol): the backend catalog's REASONING_LEVELS. */
+export const CODEX_LEVELS: readonly string[] = ["low", "high", "xhigh", "max"];
+/** The Muse relay's levels (MUSE_EFFORTS). */
+export const MUSE_LEVELS: readonly string[] = ["minimal", "low", "medium", "high", "xhigh"];
+
+export const PROVIDER_ID = "omnirush";
+/** How long a model the gateway refused for sub-agents is skipped. */
+export const REFUSAL_COOLDOWN_MS = 5 * 60_000;
+export const SETTINGS_FILE = "settings.json";
+export const REFUSALS_FILE = "subagent-model-refusals.json";
+export const CATALOG_FILE = "model-catalog.json";
+
+/** Child environment: the main model a sub-agent falls back to, its effort, and the main session's model/effort for nested layers. */
+export const ENV_FALLBACK_MODEL = "OMNIRUSH_SUBAGENT_FALLBACK_MODEL";
+export const ENV_FALLBACK_EFFORT = "OMNIRUSH_SUBAGENT_FALLBACK_EFFORT";
+export const ENV_MAIN_MODEL = "OMNIRUSH_SUBAGENT_MAIN_MODEL";
+export const ENV_MAIN_EFFORT = "OMNIRUSH_SUBAGENT_MAIN_EFFORT";
+/** The setting for one run (and, handed down, for every nested layer). */
+export const ENV_SETTING_MODEL = "OMNIRUSH_SUBAGENT_MODEL";
+export const ENV_SETTING_EFFORT = "OMNIRUSH_SUBAGENT_EFFORT";
+/** A child reports a gateway fallback on stderr with this prefix and a JSON object. */
+export const FALLBACK_MARKER = "omnirush:subagent-model-fallback ";
+
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+export interface SubagentSetting {
+  /** An omnirush.ai catalog model id; null = the delegating agent's model. */
+  model: string | null;
+  /** An effort; null = the main agent's effort (the nearest level the model offers). */
+  effort: Effort | null;
+}
+
+export const SAME: SubagentSetting = Object.freeze({ model: null, effort: null }) as SubagentSetting;
+
+export interface CatalogModel {
+  id: string;
+  name: string;
+  default: boolean;
+  /** The efforts the gateway takes for it (reasoning_levels). */
+  levels: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** An effort from any spelling ("off" and "ultra" too); null when unknown. */
+export function parseEffort(value: unknown): Effort | null {
+  if (typeof value !== "string") return null;
+  const raw = value.trim().toLowerCase();
+  const effort = raw === "ultra" ? "max" : raw === "off" ? "none" : raw;
+  return (EFFORTS as readonly string[]).includes(effort) ? (effort as Effort) : null;
+}
+
+/** pi's --thinking spelling of an effort. */
+export function piThinking(effort: string): string {
+  return effort === "none" ? "off" : effort;
+}
+
+export function isModelId(value: unknown): value is string {
+  return typeof value === "string" && MODEL_ID.test(value.trim());
+}
+
+/**
+ * A task's `model[:effort]` (the spawn_agents spelling, e.g. "gpt-6-sol:high",
+ * "muse-spark-1.1:low"): the model id and the effort, when the suffix is one.
+ */
+export function splitModelEffort(value: string): { model: string; effort: Effort | null } {
+  const text = value.trim();
+  const at = text.lastIndexOf(":");
+  if (at > 0) {
+    const effort = parseEffort(text.slice(at + 1));
+    if (effort) return { model: text.slice(0, at), effort };
+  }
+  return { model: text, effort: null };
+}
+
+/** A stored or typed setting; anything unusable reads as "same as main". */
+export function sanitizeSetting(raw: unknown): SubagentSetting {
+  if (!isRecord(raw)) return { ...SAME };
+  const model = isModelId(raw.model) && !/^(same|main|default|inherit)$/i.test(raw.model.trim()) ? raw.model.trim() : null;
+  return { model, effort: parseEffort(raw.effort) };
+}
+
+// --- the catalog --------------------------------------------------------------
+
+/** The account's models from a GET /v1/models payload, in its order; null when unusable. */
+export function catalogFromPayload(payload: unknown): CatalogModel[] | null {
+  const data = isRecord(payload) && Array.isArray(payload.data) ? payload.data : null;
+  if (!data) return null;
+  const out: CatalogModel[] = [];
+  for (const entry of data) {
+    if (!isRecord(entry) || !isModelId(entry.id)) continue;
+    const id = entry.id.trim();
+    if (out.some((model) => model.id === id)) continue;
+    const levels = Array.isArray(entry.reasoning_levels)
+      ? EFFORTS.filter((effort) => entry.reasoning_levels.some((level: unknown) => parseEffort(level) === effort))
+      : [...staticLevels(id)];
+    out.push({
+      id,
+      name: typeof entry.display_name === "string" && entry.display_name.trim() ? entry.display_name.trim() : id,
+      default: entry.default === true,
+      levels,
+    });
+  }
+  return out.length > 0 ? out : null;
+}
+
+/** The catalog the launcher cached for this run (<omnirush dir>/model-catalog.json); null when there is none. */
+export function loadCatalog(dir: string): CatalogModel[] | null {
+  try {
+    const cached = JSON.parse(readFileSync(path.join(dir, CATALOG_FILE), "utf8"));
+    return catalogFromPayload(isRecord(cached) ? cached.payload : null);
+  } catch {
+    return null;
+  }
+}
+
+/** The levels a model's route takes when the catalog does not say. */
+export function staticLevels(id: string): readonly string[] {
+  return /muse/i.test(id) ? MUSE_LEVELS : CODEX_LEVELS;
+}
+
+export function levelsFor(catalog: readonly CatalogModel[] | null, id: string): string[] {
+  const entry = catalog?.find((model) => model.id === id);
+  return entry ? [...entry.levels] : [...staticLevels(id)];
+}
+
+export function displayName(catalog: readonly CatalogModel[] | null, id: string): string {
+  return catalog?.find((model) => model.id === id)?.name ?? id;
+}
+
+/**
+ * The effort a model offers that is closest to `effort` (ties go to the
+ * higher one); null when the model offers none or the effort is unknown.
+ */
+export function nearestEffort(effort: string | null | undefined, levels: readonly string[]): string | null {
+  const wanted = parseEffort(effort);
+  if (!wanted || levels.length === 0) return null;
+  if (levels.includes(wanted)) return wanted;
+  const rank = EFFORT_RANK[wanted];
+  let best: string | null = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const level of levels) {
+    const levelRank = EFFORT_RANK[level];
+    if (levelRank === undefined) continue;
+    const distance = Math.abs(levelRank - rank);
+    if (distance < bestDistance || (distance === bestDistance && best !== null && levelRank > EFFORT_RANK[best])) {
+      best = level;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+
+/** The efforts to offer for a picked model (all the catalog's when the model is "same"). */
+export function effortOptions(catalog: readonly CatalogModel[] | null, model: string | null): string[] {
+  const offered = model
+    ? levelsFor(catalog, model)
+    : (catalog ?? []).flatMap((entry) => entry.levels);
+  const pool = offered.length > 0 ? offered : [...CODEX_LEVELS, ...MUSE_LEVELS];
+  return EFFORTS.filter((effort) => pool.includes(effort));
+}
+
+/**
+ * The setting after a change: an effort the newly picked model does not offer
+ * goes back to "same as main" rather than silently changing level (as the
+ * desktop's nextSubagentSetting).
+ */
+export function nextSetting(
+  catalog: readonly CatalogModel[] | null,
+  current: SubagentSetting,
+  patch: Partial<SubagentSetting>,
+): SubagentSetting {
+  const model = patch.model !== undefined ? patch.model : current.model;
+  const effort = patch.effort !== undefined ? patch.effort : current.effort;
+  return { model, effort: effort && effortOptions(catalog, model).includes(effort) ? effort : null };
+}
+
+// --- the setting on disk, and per run ------------------------------------------
+
+export function readSetting(dir: string): SubagentSetting {
+  try {
+    const raw = JSON.parse(readFileSync(path.join(dir, SETTINGS_FILE), "utf8"));
+    return sanitizeSetting(isRecord(raw) ? raw.subagents : null);
+  } catch {
+    return { ...SAME };
+  }
+}
+
+/** Keeps the file's other keys; atomic (temp file + rename). */
+export function writeSetting(dir: string, setting: SubagentSetting): SubagentSetting {
+  const clean = sanitizeSetting(setting);
+  const file = path.join(dir, SETTINGS_FILE);
+  let current: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (isRecord(parsed)) current = parsed;
+  } catch {
+    /* fresh file */
+  }
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const next = { ...current, subagents: { model: clean.model, effort: clean.effort } };
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, file);
+  return clean;
+}
+
+export type SettingSource = "flag" | "env" | "settings" | "default";
+
+/**
+ * The setting for this run: a --subagent-model / --subagent-effort flag, else
+ * OMNIRUSH_SUBAGENT_MODEL / _EFFORT, else the saved one, field by field.
+ * "same" (or an empty value) in a flag or the environment means "same as
+ * main" and still overrides the saved field.
+ */
+export function effectiveSetting(input: {
+  saved: SubagentSetting;
+  env?: NodeJS.ProcessEnv;
+  flags?: { model?: unknown; effort?: unknown };
+}): { setting: SubagentSetting; source: { model: SettingSource; effort: SettingSource } } {
+  const env = input.env ?? {};
+  const pick = <T>(flag: unknown, envValue: unknown, saved: T | null, parse: (value: string) => T | null) => {
+    if (typeof flag === "string" && flag.trim()) return { value: parse(flag.trim()), source: "flag" as SettingSource };
+    if (typeof envValue === "string" && envValue.trim()) return { value: parse(envValue.trim()), source: "env" as SettingSource };
+    return { value: saved, source: (saved ? "settings" : "default") as SettingSource };
+  };
+  const model = pick(input.flags?.model, env[ENV_SETTING_MODEL], input.saved.model, (value) => sanitizeSetting({ model: value }).model);
+  const effort = pick(input.flags?.effort, env[ENV_SETTING_EFFORT], input.saved.effort, (value) => parseEffort(value));
+  return { setting: { model: model.value, effort: effort.value }, source: { model: model.source, effort: effort.source } };
+}
+
+// --- refusals (shared by every process on this machine) -------------------------
+
+type Refusals = Record<string, { until: number; reason: string }>;
+
+function readRefusals(dir: string): Refusals {
+  try {
+    const parsed = JSON.parse(readFileSync(path.join(dir, REFUSALS_FILE), "utf8"));
+    return isRecord(parsed) ? (parsed as Refusals) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function markRefused(dir: string, model: string, reason: string, now: number = Date.now(), cooldownMs: number = REFUSAL_COOLDOWN_MS): void {
+  try {
+    const refusals = readRefusals(dir);
+    for (const [id, entry] of Object.entries(refusals)) {
+      if (!isRecord(entry) || typeof entry.until !== "number" || entry.until <= now) delete refusals[id];
+    }
+    refusals[model] = { until: now + cooldownMs, reason };
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, REFUSALS_FILE);
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(refusals), { mode: 0o600 });
+    renameSync(tmp, file);
+  } catch {
+    /* the cooldown is an optimisation: the gateway fallback still applies */
+  }
+}
+
+export function isRefused(dir: string, model: string, now: number = Date.now()): { reason: string } | null {
+  const entry = readRefusals(dir)[model];
+  return isRecord(entry) && typeof entry.until === "number" && entry.until > now
+    ? { reason: typeof entry.reason === "string" ? entry.reason : "refused" }
+    : null;
+}
+
+// --- resolution ----------------------------------------------------------------
+
+export type FallbackReason = "not_in_catalog" | "refused";
+
+export interface SubagentFallback {
+  requested: string;
+  requestedName: string;
+  used: string;
+  usedName: string;
+  reason: FallbackReason | string;
+}
+
+export interface SubagentResolution {
+  /** The model the child runs on; null = leave the child to pi's own default (no omnirush model known). */
+  model: string | null;
+  /** The effort (gateway spelling); null = the model's default (no --thinking). */
+  effort: string | null;
+  /** The picked model could not be used: the main one runs instead. */
+  fallback?: SubagentFallback;
+  /** The main model (and effort) the child's gateway guard moves to when the gateway refuses `model`. */
+  gatewayFallback?: { model: string; effort: string | null };
+}
+
+export interface AgentModel {
+  /** pi provider id ("omnirush" for the gateway's models). */
+  provider: string | null;
+  model: string | null;
+  /** pi thinking level or gateway effort. */
+  effort: string | null;
+}
+
+/**
+ * What one sub-agent runs on.
+ *
+ * `delegating` is the agent calling spawn_agents (its model is what "same as
+ * main" keeps); `main` is the main session's model and effort (handed down
+ * to nested layers through the environment), the one a picked model falls
+ * back to. `explicit` is the task's own `model`, which wins over the picked
+ * one and is not checked against the catalog (the gateway decides).
+ */
+export function resolveSubagentModel(input: {
+  setting: SubagentSetting;
+  catalog: readonly CatalogModel[] | null;
+  delegating: AgentModel;
+  main?: AgentModel | null;
+  explicit?: string | null;
+  refused?: (model: string) => boolean;
+}): SubagentResolution {
+  const { setting, catalog, delegating } = input;
+  const main: AgentModel = input.main && input.main.model ? input.main : delegating;
+  const mainIsGateway = main.provider === PROVIDER_ID && Boolean(main.model);
+  const wantedEffort = setting.effort ?? parseEffort(main.effort) ?? null;
+  const effortOn = (model: string): string | null => nearestEffort(wantedEffort, levelsFor(catalog, model));
+
+  const withGatewayFallback = (resolution: SubagentResolution): SubagentResolution => {
+    if (
+      resolution.model &&
+      mainIsGateway &&
+      main.model !== resolution.model &&
+      (!catalog || catalog.some((entry) => entry.id === main.model))
+    ) {
+      resolution.gatewayFallback = { model: main.model!, effort: effortOn(main.model!) };
+    }
+    return resolution;
+  };
+
+  // The task's own model[:effort]: an effort it names wins over the picked
+  // and the parent's (mapped to the nearest level the model offers).
+  const explicit = input.explicit && isModelId(input.explicit) ? splitModelEffort(input.explicit) : null;
+  if (explicit && isModelId(explicit.model)) {
+    const effort = explicit.effort ? nearestEffort(explicit.effort, levelsFor(catalog, explicit.model)) ?? explicit.effort : effortOn(explicit.model);
+    return withGatewayFallback({ model: explicit.model, effort });
+  }
+
+  if (setting.model) {
+    const inCatalog = !catalog || catalog.some((entry) => entry.id === setting.model);
+    const reason: FallbackReason | null = !inCatalog ? "not_in_catalog" : input.refused?.(setting.model) ? "refused" : null;
+    if (reason && mainIsGateway && main.model !== setting.model) {
+      return {
+        model: main.model!,
+        effort: effortOn(main.model!),
+        fallback: {
+          requested: setting.model,
+          requestedName: displayName(catalog, setting.model),
+          used: main.model!,
+          usedName: displayName(catalog, main.model!),
+          reason,
+        },
+      };
+    }
+    return withGatewayFallback({ model: setting.model, effort: effortOn(setting.model) });
+  }
+
+  // "Same as main": the delegating agent's own model.
+  if (delegating.provider !== PROVIDER_ID || !delegating.model) {
+    return { model: null, effort: null };
+  }
+  return withGatewayFallback({ model: delegating.model, effort: effortOn(delegating.model) });
+}
+
+/** A readable note for a sub-agent that ran on the main model instead of the picked one. */
+export function fallbackNote(fallback: { requestedName?: string; requested: string; usedName?: string; used: string; reason: string }): string {
+  const why = fallback.reason === "not_in_catalog"
+    ? "is not available to this account"
+    : fallback.reason === "refused"
+      ? "was refused by omnirush.ai recently"
+      : `was refused by omnirush.ai (${fallback.reason})`;
+  return `ran on ${fallback.usedName ?? fallback.used}: ${fallback.requestedName ?? fallback.requested} ${why}`;
+}
+
+// --- the gateway side (a child's guard) -----------------------------------------
+
+/** Refusals of the picked model that move the request to the main model at once. */
+const MODEL_REFUSED = new Set([
+  "model_unavailable",
+  "model_not_allowed",
+  "model_not_found",
+  "model_input_not_supported",
+  "reasoning_effort_not_allowed",
+  "unsupported_model_endpoint",
+  "muse_relay_not_configured",
+  "model_upstream_auth_failed",
+  "model_upstream_misconfigured",
+]);
+/** Busy or down: the picked model is tried once more, then the request moves. */
+const MODEL_BUSY = new Set([
+  "model_concurrency_limited",
+  "model_upstream_unavailable",
+  "internal_proxy_unavailable",
+  "provider_unavailable",
+  "provider_rate_limited",
+  "capacity_unavailable",
+  "circuit_open",
+  "maintenance",
+  "draining",
+  "auth_unavailable",
+  "token_capacity",
+  "gateway_overload",
+  "queue_timeout",
+]);
+/** Account-wide refusals: another model would be refused the same way. */
+const ACCOUNT_REFUSED = new Set([
+  "daily_grant_exhausted",
+  "grant_check_unavailable",
+  "account_inactive",
+  "consent_required",
+  "consent_version_outdated",
+  "omnirush_account_required",
+  "model_request_too_large",
+]);
+const BUSY_STATUSES = new Set([429, 502, 503, 504]);
+
+export type RefusalMove = "now" | "after_retry" | "never";
+
+/** The gateway's error code in a refused response body (detail, error, error.code or code). */
+export function refusalCode(bodyText: string): string | null {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(bodyText);
+  } catch {
+    return null;
+  }
+  if (!isRecord(payload)) return null;
+  const nested = isRecord(payload.error) ? payload.error : null;
+  const text = (value: unknown) => (typeof value === "string" && value.trim() ? value.trim() : null);
+  const code = text(payload.detail) ?? text(payload.error) ?? text(nested?.code) ?? text(payload.code) ?? (isRecord(payload.detail) ? text(payload.detail.code) : null);
+  return code ? code.replace(/^upstream_/, "") : null;
+}
+
+/** Whether a refused sub-agent request moves to the main model, at once or after one more try. */
+export function classifyRefusal(status: number, bodyText: string): { move: RefusalMove; reason: string } {
+  const code = refusalCode(bodyText);
+  const reason = code ?? `http_${status}`;
+  if (status === 401) return { move: "never", reason };
+  if (code && ACCOUNT_REFUSED.has(code)) return { move: "never", reason };
+  if (code && MODEL_REFUSED.has(code)) return { move: "now", reason };
+  if ((code && MODEL_BUSY.has(code)) || BUSY_STATUSES.has(status)) return { move: "after_retry", reason };
+  return { move: "never", reason };
+}
+
+/** The model a Responses request body names. */
+export function requestModel(body: unknown): string | null {
+  if (typeof body !== "string") return null;
+  try {
+    const parsed = JSON.parse(body);
+    return isRecord(parsed) && typeof parsed.model === "string" ? parsed.model : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The same request on another model: its effort replaced (or dropped for the model's default). */
+export function withModel(body: string, model: string, effort: string | null): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  const { reasoning_effort: _legacy, ...rest } = parsed;
+  const reasoning = isRecord(rest.reasoning) ? { ...rest.reasoning } : null;
+  if (reasoning) delete reasoning.effort;
+  const nextReasoning = effort ? { ...(reasoning ?? {}), effort: effort === "none" ? "none" : effort } : reasoning;
+  return JSON.stringify({ ...rest, model, ...(nextReasoning ? { reasoning: nextReasoning } : {}) });
+}
+
+// --- a child's gateway fallback (wired into sota.ts's fetch) ---------------------
+
+/** The request's route after a fallback: the model the SOTA guard now expects, and where it moved. */
+export interface FallbackRoute {
+  expected: string;
+  movedTo: { model: string; effort: string | null; reason: string } | null;
+}
+
+/** Models this process moved away from: requested model -> until (epoch ms). */
+const movedAway = new Map<string, number>();
+
+function pause(ms: number, signal?: AbortSignal | null): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+function abortError(signal: AbortSignal): unknown {
+  return signal.reason ?? Object.assign(new Error("This operation was aborted"), { name: "AbortError" });
+}
+
+/**
+ * Wrap a sub-agent's fetch: when the gateway refuses the picked model before
+ * answering (model_unavailable and friends at once; 429/502/503/504 or a busy
+ * code after one more try), the same request goes to the main model instead,
+ * so the task continues rather than failing. The model is then skipped for
+ * REFUSAL_COOLDOWN_MS — by this process (its later steps go straight to the
+ * main model) and, through the refusals file, by new sub-agents. Account-wide
+ * refusals and every other error pass through untouched.
+ */
+export function subagentFallbackFetch(
+  baseFetch: (input: any, init?: any) => Promise<Response>,
+  options: {
+    model: string;
+    effort: string | null;
+    dir: string;
+    route: FallbackRoute;
+    retryDelayMs?: number;
+    now?: () => number;
+    /** Told once per requested model and process (the parent reads it from stderr). */
+    report?: (event: { requested: string; used: string; effort: string | null; reason: string }) => void;
+  },
+): (input: any, init?: any) => Promise<Response> {
+  const now = options.now ?? Date.now;
+  const reported = new Set<string>();
+  return async (input: any, init?: any) => {
+    const body = init?.body;
+    const requested = requestModel(body);
+    if (typeof body !== "string" || !requested || requested === options.model) return baseFetch(input, init);
+    const signal: AbortSignal | undefined = init?.signal ?? undefined;
+
+    const move = async (reason: string): Promise<Response | null> => {
+      const moved = withModel(body, options.model, options.effort);
+      if (moved === null) return null;
+      options.route.expected = options.model;
+      options.route.movedTo = { model: options.model, effort: options.effort, reason };
+      if ((movedAway.get(requested) ?? 0) <= now()) {
+        movedAway.set(requested, now() + REFUSAL_COOLDOWN_MS);
+        markRefused(options.dir, requested, reason, now());
+      }
+      if (!reported.has(requested)) {
+        reported.add(requested);
+        try {
+          options.report?.({ requested, used: options.model, effort: options.effort, reason });
+        } catch {
+          /* reporting never breaks the request */
+        }
+      }
+      return baseFetch(input, { ...init, body: moved });
+    };
+
+    // Refused a moment ago in this process: straight to the main model.
+    if ((movedAway.get(requested) ?? 0) > now()) {
+      return (await move("refused")) ?? baseFetch(input, init);
+    }
+
+    let response = await baseFetch(input, init);
+    if (response.ok || response.status === 401) return response;
+    let refusal = classifyRefusal(response.status, await response.clone().text().catch(() => ""));
+    if (refusal.move === "never") return response;
+    if (refusal.move === "after_retry") {
+      await response.body?.cancel().catch(() => undefined);
+      await pause(options.retryDelayMs ?? 1_500, signal);
+      if (signal?.aborted) throw abortError(signal);
+      const again = await baseFetch(input, init);
+      if (again.ok || again.status === 401) return again;
+      refusal = classifyRefusal(again.status, await again.clone().text().catch(() => ""));
+      if (refusal.move === "never") return again;
+      response = again;
+    }
+    const moved = await move(refusal.reason);
+    if (!moved) return response;
+    await response.body?.cancel().catch(() => undefined);
+    return moved;
+  };
+}
+
+/** For tests: forget this process's cooldowns. */
+export function resetFallbackMemory(): void {
+  movedAway.clear();
+}