UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,958 lines • 103 kB
import { parseResetCooldownMs } from "../codex/routing";
import { CYBER_POLICY_FALLBACK_MESSAGE, TERMINAL_REFUSAL_FALLBACK_MESSAGE, classifyError, isCyberPolicyCode, isCyberPolicyMessage, isRateLimitOrQuotaFailureMessage, isSubscriptionGateMessage, isTerminalRefusalCode, safetyRefusalCodeFromMessage } from "../lib/errors";
import { isHardPolicyOrOriginRefusal } from "../lib/hard-refusal";
import { parseHttpDate } from "../lib/http-date";
import { isNonReplayableUpstreamCode } from "../lib/upstream-retry";
import { isAnthropicBillingFailure, isAnthropicExtraUsageFailure } from "../providers/anthropic-billing-refusal";
import { hasConflictingReasoningEffortCode } from "../providers/reasoning-metadata";
import { isKiroAccountProfileRefusal } from "../adapters/kiro-refusal";
import { OLLAMA_LATE_ATTRIBUTION_LIMIT_MESSAGE } from "../adapters/ollama-late-attribution";
import { M365_RESPONSE_LIMIT_MESSAGES } from "../adapters/m365-copilot/response-limits";
import type { OcxComboTarget } from "../types";
import { targetKey } from "./types";
import { PersistedCooldownMap } from "./cooldown-store";
import { registerOptionalShutdownHook } from "../lib/optional-shutdown-hooks";
import { isDefiniteContextOverflow } from "../lib/context-overflow-verdict";

// The verdict lives in a dependency-free leaf so the presentation classifier can share it.
export { isDefiniteContextOverflow };
import {
  captureConfigGeneration,
  sweepExpiredOnWrite,
  type GenerationContext,
} from "../lib/state-store-sweeper";

interface TargetCooldown {
  cooldownUntil: number;
  revision: number;
  status?: number;
}

const DEFAULT_COOLDOWN_MS = 60_000;
const MAX_COOLDOWN_MS = 10 * 60_000;
const MAX_SERVER_DELAY_MS = 24 * 60 * 60_000;
/** Short cooldown for request-rate 429s (for example provider code 1302) that omit Retry-After. */
export const COMBO_REQUEST_RATE_COOLDOWN_MS = 5_000;

const QUOTA_LIMIT_CODES = new Set([
  "1308",
  "1310",
  "1316",
  "1317",
  "1318",
  "1319",
  "1320",
  "1321",
  "insufficient_quota",
]);
const TRANSIENT_REQUEST_RATE_CODES = new Set(["1302", "1305"]);
/** Map<`${comboId}\0${provider/model}`, TargetCooldown> */
// Never reset: an in-flight reservation may still refer to an entry cleared from the map.
let nextCooldownRevision = 0;
// Disk-backed (combo-cooldowns.json): a restart keeps every live, reset-aware cooldown.
const targetCooldowns = new PersistedCooldownMap<TargetCooldown>(() => ++nextCooldownRevision);
registerOptionalShutdownHook("combo-target-cooldowns", () => targetCooldowns.flushForShutdown());
let lastReconciledGeneration = 0;
let liveComboTargets = new Set<string>();

function cooldownMapKey(
  comboId: string,
  target: Pick<OcxComboTarget, "provider" | "model">,
): string {
  return `${comboId}\0${targetKey(target)}`;
}

/** Parse a Retry-After delay, optionally retaining an upstream delay up to one day. */
export function parseRetryAfterMs(
  value: string | null | undefined,
  now = Date.now(),
  options?: { preserveImmediate?: boolean; preserveServerDelay?: boolean },
): number | undefined {
  const text = value?.trim();
  if (!text) return undefined;
  // Keep legacy bounded parsing for other callers. Combo cooldowns preserve
  // multi-hour upstream delays, but never quarantine a target beyond one day.
  const maximum = options?.preserveServerDelay === true
    ? MAX_SERVER_DELAY_MS
    : MAX_COOLDOWN_MS;
  if (/^\d+(?:\.\d+)?$/.test(text)) {
    const seconds = Number(text);
    if (
      Number.isFinite(seconds)
      && (seconds > 0 || (options?.preserveImmediate && seconds === 0))
    ) {
      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), maximum);
    }
  }
  const timestamp = parseHttpDate(text, now, { legacy: true });
  if (timestamp === undefined) return undefined;
  const delay = timestamp - now;
  if (delay > 0) return Math.min(delay, maximum);
  return options?.preserveImmediate ? 1 : undefined;
}

export function isComboTargetInCooldown(
  comboId: string,
  target: Pick<OcxComboTarget, "provider" | "model">,
  now = Date.now(),
): boolean {
  const key = cooldownMapKey(comboId, target);
  const entry = targetCooldowns.get(key);
  if (!entry) return false;
  if (entry.cooldownUntil <= now) {
    targetCooldowns.dropLocal(key);
    return false;
  }
  return true;
}

/** The live cooldown expiry for one target, or undefined once it is absent or elapsed. */
export function comboTargetCooldownExpiry(
  comboId: string,
  target: Pick<OcxComboTarget, "provider" | "model">,
  now = Date.now(),
): number | undefined {
  const key = cooldownMapKey(comboId, target);
  const entry = targetCooldowns.get(key);
  if (!entry) return undefined;
  if (entry.cooldownUntil <= now) {
    targetCooldowns.dropLocal(key);
    return undefined;
  }
  return entry.cooldownUntil;
}

/** HTTP status recorded with the target's live cooldown, when the cooling failure had one. */
export function comboTargetCooldownStatus(
  comboId: string,
  target: Pick<OcxComboTarget, "provider" | "model">,
  now = Date.now(),
): number | undefined {
  return isComboTargetInCooldown(comboId, target, now)
    ? targetCooldowns.get(cooldownMapKey(comboId, target))?.status : undefined;
}

/** Identity of the current live write, independent of its possibly repeated expiry. */
export function comboTargetCooldownRevision(
  comboId: string,
  target: Pick<OcxComboTarget, "provider" | "model">,
  now = Date.now(),
): number | undefined {
  return isComboTargetInCooldown(comboId, target, now)
    ? targetCooldowns.get(cooldownMapKey(comboId, target))?.revision : undefined;
}

/** Lift only the reserved write; a replacement with even the same expiry survives. */
export function clearComboTargetCooldownIfUnchanged(
  comboId: string,
  target: Pick<OcxComboTarget, "provider" | "model">,
  expectedRevision: number,
): void {
  const key = cooldownMapKey(comboId, target);
  if (targetCooldowns.get(key)?.revision === expectedRevision) targetCooldowns.dropLocal(key);
}

export function isTransientRequestRateLimit(input: {
  status?: number;
  code?: string | null;
  message?: string;
}): boolean {
  if (isProviderScopedQuotaCap(input.status, input.message ?? "", input.code)) return false;
  const code = (input.code ?? "").trim().toLowerCase().replaceAll("-", "_");
  if (QUOTA_LIMIT_CODES.has(code)) return false;
  if (TRANSIENT_REQUEST_RATE_CODES.has(code)) return true;
  const text = (input.message ?? "").toLowerCase();
  if (
    text.includes("usage limit reached")
    || text.includes("insufficient_quota")
    || text.includes("quota exhausted")
  ) {
    return false;
  }
  return text.includes("rate limit reached for requests");
}

export function remainingComboCooldownMs(comboId: string, now = Date.now()): number | undefined {
  const prefix = `${comboId}\0`;
  let soonest: number | undefined;
  for (const [key, cooldown] of targetCooldowns) {
    if (!key.startsWith(prefix)) continue;
    const remaining = cooldown.cooldownUntil - now;
    if (remaining <= 0) {
      targetCooldowns.dropLocal(key);
      continue;
    }
    if (soonest === undefined || remaining < soonest) soonest = remaining;
  }
  return soonest;
}

/** Snapshot active quota cooldowns without inspecting request eligibility or changing state. */
export function snapshotComboQuotaCooldowns<T extends Pick<OcxComboTarget, "provider" | "model">>(
  comboId: string,
  targets: Iterable<T>,
  now = Date.now(),
): Array<{ target: T; cooldownUntil: number }> {
  const snapshot: Array<{ target: T; cooldownUntil: number }> = [];
  for (const target of targets) {
    const key = cooldownMapKey(comboId, target);
    const cooldown = targetCooldowns.get(key);
    if (!cooldown || cooldown.cooldownUntil <= now) continue;
    if (cooldown.status !== 429 && cooldown.status !== 402) continue;
    snapshot.push({ target, cooldownUntil: cooldown.cooldownUntil });
  }
  return snapshot;
}

export function comboCooldownRetryAfterSeconds(comboId: string, now = Date.now()): string | undefined {
  const remainingMs = remainingComboCooldownMs(comboId, now);
  if (remainingMs === undefined) return undefined;
  return String(Math.max(1, Math.ceil(remainingMs / 1000)));
}

/** Record a combo target cooldown, preferring bounded upstream retry evidence. */
export function coolComboTarget(
  comboId: string,
  target: Pick<OcxComboTarget, "provider" | "model">,
  options?: {
    retryAfter?: string | null;
    resetAt?: unknown | unknown[];
    now?: number;
    cooldownMs?: number;
    writerGeneration?: number;
    status?: number;
    code?: string | null;
    message?: string;
  },
): boolean {
  const now = options?.now ?? Date.now();
  const writerGeneration = options?.writerGeneration ?? captureConfigGeneration();
  const ownerKey = `${comboId}::${targetKey(target)}`;
  if (writerGeneration < lastReconciledGeneration && !liveComboTargets.has(ownerKey)) return false;
  // A server-provided Retry-After is authoritative, including an immediate `0` directive.
  // A quota reset is the next-most-specific signal (#3256); configured and default cooldowns
  // are only fallbacks when upstream supplied neither usable value.
  const serverDelayMs = parseRetryAfterMs(options?.retryAfter, now, {
    preserveImmediate: true,
    preserveServerDelay: true,
  });
  const cooldownMs = serverDelayMs
    ?? parseResetCooldownMs(options?.resetAt, now)
    ?? options?.cooldownMs
    // A spent account window or an unpaid/rejected credential does not turn over in a minute,
    // so the 60s default would re-offer a target that cannot succeed. Only the duration
    // changes; the scope and hop decisions are untouched.
    ?? (isAccountWindowExhausted(options?.message ?? "", options?.code, options?.status)
      || PROVIDER_SCOPED_FAILURE_CODES.has(normalizedFailureCode(options?.code))
      ? MAX_COOLDOWN_MS
      : isTransientRequestRateLimit({
        status: options?.status,
        code: options?.code,
        message: options?.message,
      }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS);
  targetCooldowns.set(cooldownMapKey(comboId, target), {
    revision: ++nextCooldownRevision,
    // Local fallbacks are capped at ten minutes; explicit server delays at one day.
    cooldownUntil: now + (serverDelayMs ?? Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS)),
    status: options?.status,
  });
  sweepExpiredOnWrite(now);
  return true;
}

/**
 * failureDetail codes that cool a combo target after a COMMITTED terminal.
 * Pre-commit failures already cool through the hop path; these are the
 * post-commit `incomplete` terminals that path never sees, so without this
 * the next request picks the same target and burns the same budget again.
 */
export type CommittedIncompleteReason = "max_output_tokens" | "upstream_stall_timeout";

const COMMITTED_TERMINAL_COOLDOWN_MS: Readonly<Record<CommittedIncompleteReason, number>> = {
  // The target cannot emit more than its output ceiling; a request that
  // exhausted it will exhaust it again, so this uses the local cooldown cap.
  max_output_tokens: MAX_COOLDOWN_MS,
  // Upstream went silent mid-stream after committing output — a health
  // signal, but transient, so the standard short cooldown applies.
  upstream_stall_timeout: DEFAULT_COOLDOWN_MS,
};

export interface CommittedTerminalServingAttempt {
  provider: string;
  model: string;
  status: number;
  locallyAnswered?: boolean;
}

export interface CommittedTerminalCooldownFacts {
  comboId?: string;
  terminalStatus?: string;
  terminalReason?: CommittedIncompleteReason;
  servingAttempt?: CommittedTerminalServingAttempt;
  httpStatus?: number;
  target?: Pick<OcxComboTarget, "provider" | "model">;
  writerGeneration?: number;
  outputTokens?: number;
  outputCeiling?: number | null;
  isPaused?: boolean;
}

/**
 * Record a bounded cooldown when a combo child commits output and then ends
 * `incomplete` for a target-capacity or upstream-silence reason. The response
 * is already delivered — this only shapes the NEXT pick, so the caller's
 * effort and context configuration stay untouched.
 */
export function coolComboTargetForCommittedTerminal(facts: CommittedTerminalCooldownFacts): void {
  if (!facts.comboId || facts.terminalStatus !== "incomplete") return;
  const cooldownMs = facts.terminalReason === undefined
    ? undefined
    : COMMITTED_TERMINAL_COOLDOWN_MS[facts.terminalReason];
  if (cooldownMs === undefined) return;
  if (facts.terminalReason === "max_output_tokens") {
    // Reaching the caller's own allowance (routine for Claude Code) or an Anthropic pause_turn
    // must not cool a healthy target. Cool only when the turn was unpaused, the target's own
    // ceiling is known, and the output actually reached that ceiling.
    if (facts.isPaused === true) return;
    if (facts.outputCeiling == null || (facts.outputTokens ?? 0) < facts.outputCeiling) return;
  }
  const attempt = facts.servingAttempt;
  // The incomplete terminal is itself proof the target ran: a late stall surfaces to
  // the client as a 5xx attempt status, so gating on status < 400 would silence exactly
  // the case this cooldown exists for.
  if (!attempt || attempt.locallyAnswered === true) return;
  // Combo selection evaluates cooldowns against pick.target (which preserves any alias selector
  // the combo named); fall back to the routed physical attempt only when facts omits the target.
  const target = facts.target ?? { provider: attempt.provider, model: attempt.model };
  // A shorter committed-terminal cooldown must not shorten a longer live one — a
  // server Retry-After or reset already recorded for this target stays authoritative.
  const existing = targetCooldowns.get(cooldownMapKey(facts.comboId, target));
  if (existing && existing.cooldownUntil > Date.now() + cooldownMs) return;
  coolComboTarget(facts.comboId, target, {
    cooldownMs,
    status: facts.httpStatus,
    writerGeneration: facts.writerGeneration,
  });
}

export function earliestComboCooldown(
  comboId: string,
  targets: Iterable<Pick<OcxComboTarget, "provider" | "model">>,
  now = Date.now(),
): { expiry: number; target: Pick<OcxComboTarget, "provider" | "model"> } | undefined {
  let earliest: { expiry: number; target: Pick<OcxComboTarget, "provider" | "model"> } | undefined;
  for (const target of targets) {
    const key = cooldownMapKey(comboId, target);
    const entry = targetCooldowns.get(key);
    if (!entry || entry.cooldownUntil <= now) continue;
    if (earliest === undefined || entry.cooldownUntil < earliest.expiry) {
      earliest = { expiry: entry.cooldownUntil, target };
    }
  }
  return earliest;
}

/** Public convenience wrapper returning only the earliest cooldown expiry. */
export function earliestComboCooldownExpiry(
  comboId: string,
  targets: Iterable<Pick<OcxComboTarget, "provider" | "model">>,
  now = Date.now(),
): number | undefined {
  return earliestComboCooldown(comboId, targets, now)?.expiry;
}

export function reconcileComboTargetCooldowns(context: GenerationContext): number {
  if (context.generation <= lastReconciledGeneration) return 0;
  liveComboTargets = new Set(context.comboTargets);
  lastReconciledGeneration = context.generation;
  return 0;
}

export function sweepExpiredComboTargetCooldowns(now = Date.now()): number {
  let removed = 0;
  for (const [key, cooldown] of targetCooldowns) {
    if (cooldown.cooldownUntil > now) continue;
    targetCooldowns.dropLocal(key);
    removed += 1;
  }
  return removed;
}

/** Clear all cooldowns, one combo, or only the supplied target keys within that combo. */
export function clearComboTargetCooldowns(comboId?: string, targetKeys?: Iterable<string>): void {
  if (comboId === undefined) {
    targetCooldowns.clearAllPersisted();
    liveComboTargets.clear();
    lastReconciledGeneration = 0;
    return;
  }
  const prefix = `${comboId}\0`;
  if (targetKeys !== undefined) {
    targetCooldowns.clearPersisted([...targetKeys].map(key => `${prefix}${key}`));
    return;
  }
  targetCooldowns.clearPrefixPersisted(prefix);
}

export type ComboFailureDecision = "hop" | "stop";
export type ComboFailureCooldownScope = "none" | "target" | "provider";

function normalizedFailureCode(code?: string | number | null): string {
  if (typeof code === "number") return Number.isFinite(code) ? String(code) : "";
  return code?.trim().toLowerCase().replaceAll("-", "_") ?? "";
}

/** Parse one bounded error body or single SSE data frame into its root record. */
function parseErrorEnvelope(message: string): Record<string, unknown> | undefined {
  if (message.length > 16_384) return undefined;
  let text = message.trim();
  const proxyPrefix = /^Provider error \d{3}: /.exec(text);
  if (proxyPrefix) text = text.slice(proxyPrefix[0].length).trim();
  if (text.startsWith("data:") && !text.includes("\n")) text = text.slice("data:".length).trim();
  try {
    const payload: unknown = JSON.parse(text);
    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
    return payload as Record<string, unknown>;
  } catch {
    return undefined;
  }
}

/**
 * The one error record an envelope carries: its own `error`, else the root when that root states
 * the failure itself. HTTP consumption and the SSE preflight both select through here so the two
 * transports cannot disagree about which record speaks.
 *
 * A `response.error` alone is deliberately not a carrier here. Under a bare frame it is not an
 * error event at all, so reading it on HTTP only made the same envelope hop on one transport and
 * stop on the other; leaving it unread is the behavior both transports had.
 */
export function envelopeErrorRecord(root: Record<string, unknown>): Record<string, unknown> | undefined {
  const error = root.error;
  if (error !== null && typeof error === "object" && !Array.isArray(error)) {
    const record = { ...(error as Record<string, unknown>) };
    if (typeof record.detail !== "string" && typeof root.detail === "string") {
      record.detail = root.detail;
    }
    return record;
  }
  if (typeof root.message === "string" || typeof root.detail === "string") {
    return root;
  }
  return undefined;
}

/** Parse one bounded error record from an HTTP 400 body or a single SSE data frame. */
export function http400ErrorRecord(message: string): Record<string, unknown> | undefined {
  const root = parseErrorEnvelope(message);
  return root ? envelopeErrorRecord(root) : undefined;
}

/** A record's own structured code as a string; blank, absent and non-finite values state none. */
export function envelopeRecordCode(record: Record<string, unknown> | undefined): string | undefined {
  if (!record) return undefined;
  const code = record.code;
  if (typeof code === "number") {
    return Number.isFinite(code) ? String(code) : undefined;
  }
  return typeof code === "string" && code.trim() !== "" ? code : undefined;
}

/**
 * The envelope root's own structured code, when it states one beside a nested record.
 *
 * The nested record is what normalization selects for display and classification, so this is
 * the only place a root verdict survives. Numeric codes are stringified the way the decision
 * normalizes them. An absent, empty or whitespace-only code is no verdict at all.
 */
export function upstreamEnvelopeRootCode(message: string): string | undefined {
  return envelopeRecordCode(parseErrorEnvelope(message));
}

/** Check whether a parsed error record or raw diagnostic text represents a malformed response_format. */
export function isMalformedResponseFormatRecord(record?: Record<string, unknown>, rawText?: string): boolean {
  const fields = record
    ? [record.message, record.detail].filter((value): value is string => typeof value === "string")
    : [];
  if (rawText) fields.push(rawText);
  return fields.some(detail =>
    /\binvalid schema(?: for)? response_format\b/i.test(detail)
    || /\bresponse_format(?:\.[a-z_]+)*\s+must be (?:one of|valid|a valid)\b/i.test(detail));
}

/** Identify known malformed structured-output diagnostics that must remain terminal. */
export function isMalformedResponseFormatRequest(status: number, message: string): boolean {
  if (status !== 400) return false;
  return isMalformedResponseFormatRecord(http400ErrorRecord(message), message);
}

/** Check whether a parsed error record matches OpenRouter's uncoded numeric-400 opaque wrapper. */
export function isOpenRouterOpaque400Record(record?: Record<string, unknown>): boolean {
  if (!record) return false;
  const metadata = record.metadata;
  const errorType = record.type === "error" ? undefined : record.type;
  return record.message === "Provider returned error"
    && (record.code === 400 || record.code === "400")
    && errorType === undefined
    && metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)
    && (metadata as Record<string, unknown>).raw === "ERROR";
}

/** Recognize OpenRouter's uncoded numeric-400 wrapper for an opaque provider failure. */
export function isOpenRouterOpaque400Envelope(message: string): boolean {
  const root = parseErrorEnvelope(message);
  return !!root && isOpenRouterOpaque400EnvelopeRoot(root);
}

/**
 * The same verdict for an already parsed envelope root, which is what the SSE preflight holds.
 * Both transports entering here is what keeps their answers equal.
 */
export function isOpenRouterOpaque400EnvelopeRoot(root: Record<string, unknown>): boolean {
  return isOpenRouterOpaque400Record(envelopeErrorRecord(root)) && !envelopeRootStatesVerdict(root);
}

/**
 * Root codes that state a request verdict of their own, so the record beside them does not
 * speak for the envelope.
 *
 * Membership is a correctness question, not a formatting one: an equality test against `"400"`
 * made every other root code -- including a blank one and the codes that are ordinary combo hop
 * signals -- suppress the opaque verdict, so HTTP stopped on failures SSE advanced past. Each
 * entry here is a code `comboFailureDecision` reaches its terminal arms with when read alone.
 * Content refusals are the shared {@link isTerminalRefusalCode} set; the post-send codes are the
 * ones {@link isNonReplayableUpstreamCode} owns; the rest are the generic request verdicts and the
 * origin's own refusal.
 */
const ROOT_VERDICT_CODES = new Set([
  "origin_rejected",
  "content_policy_violation",
  "context_length_exceeded",
  "invalid_request_error",
  "client_closed_request",
  "client_cancelled",
]);

/** A root code that is itself a hard stop or terminal request verdict; blank means "no verdict". */
function rootCodeStatesVerdict(code: string): boolean {
  const normalized = normalizedFailureCode(code);
  return ROOT_VERDICT_CODES.has(normalized)
    || isTerminalRefusalCode(normalized)
    || isNonReplayableUpstreamCode(normalized);
}

/**
 * Does the envelope root name its own verdict? A non-`"error"` type and any terminal root code do;
 * a blank, absent, numeric-`400` or hop-signal code does not, so the nested record keeps speaking.
 */
function envelopeRootStatesVerdict(root: Record<string, unknown>): boolean {
  const { type } = root;
  if (type !== undefined && type !== null && type !== "error") return true;
  const code = envelopeRecordCode(root);
  return code !== undefined && rootCodeStatesVerdict(code);
}

/** Check whether an uncoded numeric 400 is an opaque OpenRouter failure that may safely advance without cooling. */
function isUncodedUpstream400(
  status: number,
  message: string,
  code?: string | number | null,
  options?: {
    malformedResponseFormat?: boolean;
    openRouterOpaque400?: boolean;
  },
): boolean {
  const normalized = normalizedFailureCode(code);
  if (status !== 400 || (normalized !== "" && normalized !== "400")) return false;
  const malformed = options?.malformedResponseFormat !== undefined
    ? options.malformedResponseFormat
    : isMalformedResponseFormatRequest(status, message);
  if (malformed) return false;
  return options?.openRouterOpaque400 !== undefined
    ? options.openRouterOpaque400
    : isOpenRouterOpaque400Envelope(message);
}

/**
 * xAI can reject a model/account effort rung with this exact vendor envelope. It is target-local
 * evidence for a combo: the same model may accept a lower rung, or a later target may accept the
 * request. Keep the match exact so unrelated invalid arguments stay terminal.
 */
const EXACT_EFFORT_COMPATIBLE_CODES = new Set(["", "invalid_request_error", "invalid_argument"]);
const EXACT_EFFORT_COMPATIBLE_TYPES = new Set(["", "invalid_request_error", "upstream_error"]);

function hasIncompatibleDiagnosticCarrier(val: unknown, depth = 0): boolean {
  if (val === undefined || val === null) return false;
  if (depth > 8) return true;
  if (Array.isArray(val)) {
    if (val.length > 32) return true;
    for (const item of val) {
      if (hasIncompatibleDiagnosticCarrier(item, depth + 1)) return true;
    }
    return false;
  }
  if (typeof val === "string") {
    try {
      const parsed = JSON.parse(val);
      if (parsed && typeof parsed === "object") {
        return hasIncompatibleDiagnosticCarrier(parsed, depth + 1);
      }
      return true;
    } catch {
      return true;
    }
  }
  if (typeof val === "object") {
    const rec = val as Record<string, unknown>;
    if (rec.param !== undefined && rec.param !== null) {
      if (typeof rec.param !== "string") return true;
      const param = rec.param.trim().toLowerCase();
      if (param.length > 0 && param !== "reasoning_effort" && param !== "reasoning.effort") return true;
    }
    if (rec.code !== undefined && rec.code !== null) {
      if (typeof rec.code !== "string") return true;
      if (!EXACT_EFFORT_COMPATIBLE_CODES.has(normalizedFailureCode(rec.code))) return true;
    }
    if (rec.type !== undefined && rec.type !== null) {
      if (typeof rec.type !== "string") return true;
      if (!EXACT_EFFORT_COMPATIBLE_TYPES.has(normalizedFailureCode(rec.type))) return true;
    }
    if (rec.error !== undefined && rec.error !== null) {
      if (hasIncompatibleDiagnosticCarrier(rec.error, depth + 1)) return true;
    }
    if (rec.response !== undefined && rec.response !== null) {
      if (hasIncompatibleDiagnosticCarrier(rec.response, depth + 1)) return true;
    }
    if (rec.last_error !== undefined && rec.last_error !== null) {
      if (hasIncompatibleDiagnosticCarrier(rec.last_error, depth + 1)) return true;
    }
    if (rec.details !== undefined && rec.details !== null) {
      if (hasIncompatibleDiagnosticCarrier(rec.details, depth + 1)) return true;
    }
    if (rec.detail !== undefined && rec.detail !== null) {
      if (hasIncompatibleDiagnosticCarrier(rec.detail, depth + 1)) return true;
    }
    if (rec.errors !== undefined && rec.errors !== null) {
      if (hasIncompatibleDiagnosticCarrier(rec.errors, depth + 1)) return true;
    }
    if (rec.message !== undefined && rec.message !== null) {
      if (typeof rec.message !== "string" || rec.message !== "Invalid reasoning effort.") return true;
    }
    return false;
  }
  return false;
}

function isExactInvalidReasoningEffortRefusal(status: number, message: string, code?: string | null): boolean {
  if (status !== 400 || message.length > 16_384) return false;
  if (code !== undefined && code !== null && typeof code !== "string") return false;
  const outerCode = normalizedFailureCode(code);
  if (!EXACT_EFFORT_COMPATIBLE_CODES.has(outerCode)) return false;
  if (isHardPolicyOrOriginRefusal(message) || hasConflictingReasoningEffortCode(message, 16_384)) return false;
  let text = message.trim();
  for (let depth = 0; depth < 3; depth += 1) {
    if (text.startsWith("Provider error 400: ")) text = text.slice("Provider error 400: ".length).trim();
    if (text.startsWith("data:") && !text.includes("\n")) text = text.slice("data:".length).trim();
    let payload: unknown;
    try { payload = JSON.parse(text); } catch { return false; };
    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
    const root = payload as Record<string, unknown>;
    if (root.code !== undefined && root.code !== null && typeof root.code !== "string") return false;
    if (root.type !== undefined && root.type !== null && typeof root.type !== "string") return false;
    if (root.message !== undefined && root.message !== null && typeof root.message !== "string") return false;
    if (root.param !== undefined && root.param !== null) {
      if (typeof root.param !== "string") return false;
      const param = root.param.trim().toLowerCase();
      if (param !== "reasoning_effort" && param !== "reasoning.effort") return false;
    }
    const rootCode = normalizedFailureCode(root.code as string | undefined);
    const rootType = normalizedFailureCode(root.type as string | undefined);
    if (!EXACT_EFFORT_COMPATIBLE_CODES.has(rootCode)) return false;
    if (!EXACT_EFFORT_COMPATIBLE_TYPES.has(rootType)) return false;
    if (root.response !== undefined && root.response !== null) return false;
    if (root.last_error !== undefined && root.last_error !== null) return false;
    if (hasIncompatibleDiagnosticCarrier(root.details)) return false;
    if (hasIncompatibleDiagnosticCarrier(root.detail)) return false;
    if (hasIncompatibleDiagnosticCarrier(root.errors)) return false;
    if (rootCode === "invalid_argument"
      && root.error === "Invalid reasoning effort."
      && (root.type === undefined || root.type === "invalid_request_error")
      && (root.param === undefined || root.param === "reasoning_effort" || root.param === "reasoning.effort")) {
      if (root.message !== undefined && root.message !== null && root.message !== "Invalid reasoning effort.") return false;
      return true;
    }
    const error = root.error;
    if (!error || typeof error !== "object" || Array.isArray(error)) return false;
    const record = error as Record<string, unknown>;
    if (record.code !== undefined && record.code !== null && typeof record.code !== "string") return false;
    if (record.type !== undefined && record.type !== null && typeof record.type !== "string") return false;
    if (record.message !== undefined && record.message !== null && typeof record.message !== "string") return false;
    if (record.error !== undefined && record.error !== null && typeof record.error !== "string") return false;
    if (record.param !== undefined && record.param !== null) {
      if (typeof record.param !== "string") return false;
      const param = record.param.trim().toLowerCase();
      if (param !== "reasoning_effort" && param !== "reasoning.effort") return false;
    }
    if (root.param !== undefined && root.param !== null && record.param !== undefined && record.param !== null) {
      if (root.param.trim().toLowerCase() !== record.param.trim().toLowerCase()) return false;
    }
    const errorCode = normalizedFailureCode(record.code as string | undefined);
    const errorType = normalizedFailureCode(record.type as string | undefined);
    if (!EXACT_EFFORT_COMPATIBLE_CODES.has(errorCode)) return false;
    if (!EXACT_EFFORT_COMPATIBLE_TYPES.has(errorType)) return false;
    if (record.response !== undefined && record.response !== null) return false;
    if (record.last_error !== undefined && record.last_error !== null) return false;
    if (hasIncompatibleDiagnosticCarrier(record.details)) return false;
    if (hasIncompatibleDiagnosticCarrier(record.detail)) return false;
    if (hasIncompatibleDiagnosticCarrier(record.errors)) return false;
    if (record.type === "upstream_error" && typeof record.message === "string"
      && record.message.startsWith("Provider error 400: ")
      && EXACT_EFFORT_COMPATIBLE_CODES.has(errorCode)) {
      text = record.message;
      continue;
    }
    if (root.type === "upstream_error" && typeof root.message === "string"
      && root.message.startsWith("Provider error 400: ")
      && EXACT_EFFORT_COMPATIBLE_CODES.has(rootCode)) {
      text = root.message;
      continue;
    }
    if (root.message !== undefined && root.message !== null && root.message !== "Invalid reasoning effort.") return false;
    if (record.error !== undefined && record.error !== null && record.error !== "Invalid reasoning effort.") return false;
    return record.type === "invalid_request_error"
      && record.message === "Invalid reasoning effort."
      && EXACT_EFFORT_COMPATIBLE_CODES.has(errorCode)
      && (record.param === undefined || record.param === "reasoning_effort" || record.param === "reasoning.effort");
  }
  return false;
}

/**
 * A spent account window, by structured code or upstream prose. Status is deliberately not
 * consulted: the ChatGPT Codex backend reports a depleted plan window as HTTP 502
 * `upstream_server_error` carrying `The usage limit has been reached`, never the documented 429,
 * so any status gate misses it. Read in exactly ONE place -- the cooldown DURATION fallback. A
 * status-blind prose match is safe for choosing how long to wait; it is not safe for choosing
 * what to black out, so `isProviderScopedQuotaCap` and the scope/decision paths stay untouched
 * and a Codex 502 still resolves `target` scope and `hop` through `status >= 500`.
 */
// `1308` is the vendor code for a spent five-hour window and carries no prose of its own when the
// upstream reports it bare, so it belongs here too. The rest of QUOTA_LIMIT_CODES stays out: those
// are quota-limit codes whose window length this gateway has no evidence for, and guessing long on
// them would hold a target that may clear sooner.
const ACCOUNT_EXHAUSTION_CODES = new Set(["usage_limit_exceeded", "usage_limit_reached", "1308"]);
// Token-plan windows (Alibaba's DeepSeek/Qwen plans) report "Your token-plan 1-week quota has been
// exhausted" (#5494). The match is anchored to that phrasing: a looser "quota ... exhausted" would
// also catch per-minute limits, and this arm outranks the transient rate-limit duration.
const ACCOUNT_EXHAUSTION_TEXT = /usage limit (?:has been )?reached|token-plan\s+\S+\s+quota has been exhausted|(?:account|weekly|monthly|daily)\s*(?:usage\s+)?quota (?:(?:has been |is )?exhausted|exceeded)/i;

/**
 * Determines whether an error signals that an account's quota or usage window has been exhausted.
 *
 * Explicit error codes (`usage_limit_exceeded`, `insufficient_quota`, etc.) are always authoritative.
 * For HTTP 400 (Bad Request), prose alone is not authoritative because client validation errors
 * may echo prompt contents or parameter values containing quota-related words.
 *
 * @param message The error message text.
 * @param code The normalized or raw error code.
 * @param status The HTTP status code, if known.
 * @returns True if the failure represents an account window exhaustion.
 */
function isAccountWindowExhausted(
  message: string,
  code?: string | null,
  status?: number,
): boolean {
  const normalized = normalizedFailureCode(code);
  if (ACCOUNT_EXHAUSTION_CODES.has(normalized) || normalized === "insufficient_quota") {
    return true;
  }
  // On HTTP 400 (Bad Request / parameter validation), prose alone is not authoritative evidence
  // of account quota exhaustion because validation errors may echo user prompts or parameter values
  // quoting "quota exhausted". An authoritative account exhaustion verdict on 400 requires a
  // structured exhaustion code.
  if (status === 400 || status === 422) {
    return false;
  }
  return ACCOUNT_EXHAUSTION_TEXT.test(message.toLowerCase());
}

function isProviderScopedQuotaCap(
  status: number | undefined,
  message: string,
  code?: string | null,
): boolean {
  if (status === 400 || status === 422) return false; // Validation prose may reflect the caller's input.
  const normalizedCode = normalizedFailureCode(code);
  const text = message.toLowerCase();
  if (
    status === 429
    && (normalizedCode === "gousagelimiterror" || text.includes("monthly usage limit reached"))
  ) {
    return true;
  }
  return text.includes("err_free_prompt_cap")
    || (text.includes("free tier") && text.includes("single request"));
}

/** A structured account-window exhaustion code; prose never qualifies (a request can echo it). */
function hasAccountExhaustionCode(code?: string | null): boolean {
  const normalized = normalizedFailureCode(code);
  return ACCOUNT_EXHAUSTION_CODES.has(normalized) || normalized === "insufficient_quota";
}

/**
 * A free-tier cap the upstream evaluates PER REQUEST rather than per account window. These
 * needles used to reach only `isProviderScopedQuotaCap`, so a single oversized free-tier prompt
 * cooled the whole provider for every other combo — including the shorter requests that same
 * provider would still have served. `free_rate_limited` also left the provider-scoped predicate
 * for the same reason; it stays a hop signal, but stops recording provider-wide evidence.
 */
function isRequestLocalFreePromptCap(
  status: number | undefined,
  message: string,
  code?: string | null,
): boolean {
  if (status !== 400 && status !== 422) return false;
  const text = message.toLowerCase();
  if (normalizedFailureCode(code) === "free_rate_limited") return true;
  if (text.includes("err_free_prompt_cap")) return true;
  return text.includes("free tier") && (text.includes("single request") || text.includes("prompt"));
}

/**
 * Failures that describe the SHAPE of this request rather than the health of the target.
 * Cooling anything for these is wrong twice over: the target is fine, and the next request
 * (shorter prompt, smaller tool catalog) would have succeeded against it.
 */
const REQUEST_SHAPE_FAILURE_CODES = new Set([
  "input_admission_refused",
  "context_length_exceeded",
  "tool_catalog_too_large",
  "cursor_root_envelope_limit",
  "target_incompatible",
  // A route that cannot read the request's media (image input to a text-only CLI route) is
  // healthy for every other request, so cooling it would only block unrelated turns.
  "unsupported_input_modality",
  // A request whose token cap was reached before output was produced is request-specific;
  // the candidate remains healthy for subsequent requests with larger limits.
  "zero_output_token_limit",
]);

/** Credential/billing failures that every target sharing the provider inherits. */
const PROVIDER_SCOPED_FAILURE_CODES = new Set([
  "invalid_api_key",
  "insufficient_quota",
  "subscription_required",
  "payment_required",
  "billing_error",
  "insufficient_balance",
]);

/**
 * Precise target-local request incompatibilities are request-local, not terminal for a combo.
 * Require a bounded, intact provider envelope; never infer compatibility from echoed prompt text.
 * Only OpenCodex's exact error wrapper may be unwrapped, with a fixed depth budget. Unknown or
 * conflicting codes fail closed. No fields are removed here and no same-target replay is added.
 * Image rejection requires `param: input` and an exact model-scoped prefix.
 */
function isRequestLocalTargetIncompatibility(status: number, message: string, code?: string | null): boolean {
  if (isExactInvalidReasoningEffortRefusal(status, message, code)) return true;
  if (status !== 400 || message.length > 16_384) return false;
  const genericCodes = new Set(["", "invalid_request_error", "unsupported_parameter", "unsupported_value"]);
  if (!genericCodes.has(normalizedFailureCode(code))) return false;
  let text = message.trim();
  for (let depth = 0; depth < 3; depth += 1) {
    if (text.startsWith("Provider error 400: ")) text = text.slice("Provider error 400: ".length);
    let payload: unknown;
    try { payload = JSON.parse(text); } catch { return false; }
    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
    const root = payload as Record<string, unknown>;
    if (root.code !== undefined && root.code !== null && typeof root.code !== "string") return false;
    if (root.type !== undefined && root.type !== null && typeof root.type !== "string") return false;
    if (root.param !== undefined && root.param !== null && typeof root.param !== "string") return false;
    const rootCode = normalizedFailureCode(root.code as string | undefined);
    if (!genericCodes.has(rootCode)) return false;
    if (root.type !== undefined && root.type !== null && root.type !== "invalid_request_error" && root.type !== "upstream_error") return false;
    const error = root.error;
    if (!error || typeof error !== "object" || Array.isArray(error)) return false;
    const e = error as Record<string, unknown>;
    if (e.code !== undefined && e.code !== null && typeof e.code !== "string") return false;
    if (root.param !== undefined && root.param !== null && typeof e.param === "string") {
      if (root.param.trim().toLowerCase() !== e.param.trim().toLowerCase()) return false;
    }
    const errorCode = normalizedFailureCode(typeof e.code === "string" ? e.code : undefined);
    if (!genericCodes.has(errorCode) || typeof e.message !== "string") return false;
    if (e.type !== "invalid_request_error" && e.type !== "upstream_error") return false;
    if (e.message.startsWith("Provider error 400: ") && e.param === undefined
      && (errorCode === "" || errorCode === "invalid_request_error")) {
      text = e.message;
      continue;
    }
    if (e.type !== "invalid_request_error") return false;
    if (e.message === "Unsupported parameter: user") {
      return (e.param === undefined || e.param === "user") && errorCode !== "unsupported_value";
    }
    if (errorCode === "unsupported_value"
      && (e.param === "reasoning.effort" || e.param === "reasoning_effort")
      && e.message.startsWith("Unsupported value:") && e.message.includes("not supported")) return true;
    if (e.code === null
      && e.param === "reasoning_effort"
      && /^Function tools with reasoning_effort are not supported for gpt-6-astra(?:-\d{4}-\d{2}-\d{2})? in \/v1\/chat\/completions\. To use function tools, use \/v1\/responses or set reasoning_effort to 'none'\.$/.test(e.message)) return true;
    return e.param === "input"
      && (errorCode === "" || errorCode === "invalid_request_error")
      && /^Model '[^']{1,256}' does not support image inputs\./.test(e.message);
  }
  return false;
}

/**
 * Codes a gateway uses when it declines a request field it cannot serve.
 *
 * Wider than the set {@link isRequestLocalTargetIncompatibility} accepts, by exactly one member:
 * Alibaba's gateway reports `invalid_parameter_error`. It is kept in its own set rather than
 * added to the shared one, because that set also governs the `user` parameter and image-input
 * branches and widening it there would admit shapes those branches were reasoned about without.
 */
const RESPONSE_FORMAT_REFUSAL_CODES = new Set([
  "",
  "invalid_request_error",
  "invalid_parameter_error",
  "unsupported_parameter",
  "unsupported_value",
]);

/**
 * Does this message say the target cannot PROVIDE `response_format`, rather than that the
 * request's `response_format` was malformed?
 *
 * That distinction is the whole point of #4903 and it is why neither obvious option was taken.
 * Hopping on every 400 would replay a genuinely malformed request against every remaining
 * target. Dropping `response_format` would silently change the output contract the caller
 * asked for, on a path whose entire purpose is a structured result.
 *
 * So both halves are required: the message must name the field, AND it must say the field is
 * unavailable or unsupported. "Invalid schema for response_format" names the field and claims
 * nothing about capability, so it stays terminal.
 *
 * `param` may be absent or explicitly null -- the reported gateway sends `param: null` -- but a
 * param naming a DIFFERENT field contradicts the message and fails closed.
 */
function namesResponseFormatIncapability(message: string, param: unknown): boolean {
  if (param !== undefined && param !== null && param !== "response_format") return false;
  const text = message.toLowerCase();
  if (!text.includes("response_format")) return false;
  return /(unavailable|not available|unsupported|not supported|does not support|doesn't support|cannot be used|is not enabled)/u
    .test(text);
}

/**
 * A `response_format` capability gap is target-local: this model cannot produce the requested
 * output shape, which says nothing about the next target in the combo.
 *
 * Reported against a shadow title-generation call, where a combo's first target rejects
 * `response_format` and the chain stops instead of trying the target behind it (#4903).
 *
 * The next target receives the SAME request, `response_format` included, so a target that can
 * honour the contract honours it and one that cannot is skipped in turn. Traversal stays finite
 * because combo excludes each attempted target and policy tries each candidate once.
 *
 * The envelope is bounded exactly like {@link isRequestLocalTargetIncompatibility}: an intact
 * provider JSON object, a depth budget, `type: "invalid_request_error"`, and a code from a
 * closed set. Nothing is inferred from echoed prompt text and no field is removed.
 */
function isResponseFormatCapabilityRefusal(
  status: number,
  message: string,
  code?: string | null,
): boolean {
  if (status !== 400 || message.length > 16_384) return false;
  if (!RESPONSE_FORMAT_REFUSAL_CODES.has(normalizedFailureCode(code))) return false;
  let text = message.trim();
  for (let depth = 0; depth < 3; depth += 1) {
    if (text.startsWith("Provider error 400: ")) {
      text = text.slice("Provider error 400: ".length).trim();
    }
    // A chat gateway can report the refusal inside a single SSE frame, and the combo consumer
    // keeps the raw text when that frame stops the error object from being extracted -- which is
    // why the reported classification text reads `data: {"error":...}` and why the structured
    // code arrives undefined. Exactly one `data:` prefix is removed, and only when the body is
    // one line: this unwraps a single frame rather than parsing a stream, so a multi-event body
    // is left alone and still fails closed.
    if (text.startsWith("data:") && !text.includes("\n")) {
      text = text.slice("data:".length).trim();
    }
    let payload: unknown;
    try { payload = JSON.parse(text); } catch { return false; }
    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
    const error = (payload as Record<string, unknown>).error;
    if (!error || typeof error !== "object" || Array.isArray(error)) return false;
    const e = error as Record<string, unknown>;
    if (e.code !== undefined && e.code !== null && typeof e.code !== "string") return false;
    if (typeof e.message !== "string") return false;
    // Our own wrapper, re-wrapped by a downstream hop. Peel it and look again, within budget.
    if (e.message.startsWith("Provider error 400: ") && e.param === undefined) {
      text = e.message;
      continue;
    }
    if (e.type !== "invalid_request_error") return false;
    const errorCode = normalizedFailureCode(typeof e.code === "string" ? e.code : undefined);
    if (!RESPONSE_FORMAT_REFUSAL_CODES.has(errorCode)) return false;
    return namesResponseFormatIncapability(e.message, e.param);
  }
  return false;
}

/**
 * Codes, types and params an unoffered-tool-call refusal may carry. The reported carrier uses
 * `type: "upstream_error"` with `code: null` -- an aggregator re-wrapping the model backend's
 * 400 -- while request-validation spellings stay accepted because gateways disagree on which
 * they emit. Anything outside these closed sets fails closed.
 */
const UNOFFERED_TOOL_CALL_CODES = new Set(["", "invalid_request_error", "invalid_argument", "upstream_error"]);
const UNOFFERED_TOOL_CALL_TYPES = new Set(["", "invalid_request_error", "upstream_error", "ai_apicallerror"]);
const UNOFFERED_TOOL_CALL_PARAMS = new Set(["tools", "tool_choice"]);
/**
 * The provider's own verdict sentences for target-local model failures, each anchored so a
 * validation message that merely quotes or reflects one cannot impersonate the verdict -- the
 * same failure mode moderation-refusal matching guards against. Both observed carriers arrive
 * as `type: "upstream_error"` with `code: null` behind aggregator re-wraps.
 */
const UNOFFERED_TOOL_CALL_MESSAGES = [
  /^the model called a function that was not offered in tools\.?$/i,
  /^the model returned an unexpected parser control marker; no output was published\.?$/i,
] as const;
/** Sibling records that could smuggle a competing verdict this classifier does not inspect. */
const UNOFFERED_TOOL_CALL_CARRIERS = ["response", "last_error", "details", "detail", "errors"] as const;

function isUnofferedToolCallVerdict(text: string): boolean {
  const value = text.trim().replace(/^Provider error \d{3}: /, "").trim();
  return UNOFFERED_TOOL_CALL_MESSAGES.some(pattern => pattern.test(value));
}

/**
 * A root message that carries its own envelope prefix is peeled and its contents must still
 * support the verdict: `Provider error 400: Invalid value for tools` contradicts a nested
 * refusal even though the prefix itself is recognized.
 */
function isUnofferedToolCallCarrierVerdict(text: string): boolean {
  let value = text.trim();
  for (let depth = 0; depth < 3; depth += 1) {
    const proxyPrefix = /^Provider error \d{3}: /.exec(value);
    if (proxyPrefix) {
      value = value.slice(proxyPrefix[0].length).trim();
      continue;
    }
    if (value.startsWith("data:") && !value.includes("\n")) {
      value = value.slice("data:".length).trim();
      continue;
    }
    break;
  }
  return isUnofferedToolCallVerdict(value);
}

function hasUnofferedToolCallCarrierPrefix(text: string): boolean {
  return /^Provider error \d{3}: /.test(text) || (text.startsWith("data:") && !text.includes("\n"));
}

function unofferedToolCallRecordShape(record: Record<string, unknown>): boolean {
  if (record.code !== undefined && record.code !== null && typeof record.code !== "string" && typeof record.code !== "number") return false;
  if (record.type !== undefined && record.type !== null && typeof record.type !== "string") return false;
  if (record.param !== undefined && record.param !== null) {
    if (typeof record.param === "string") {
      if (!UNOFFERED_TOOL_CALL_PARAMS.has(record.param.trim().toLowerCase())) return false;
    } else if (typeof record.param === "object" && !Array.isArray(record.param)) {
      // An AI-SDK gateway wraps the verdict in an error object under `param`; accept it only
      // when a nested string field independently carries the same anchored verdict, so the
      // object cannot smuggle a different claim.
      const nested = record.param as Record<string, unknown>;
      const diagnostics = [nested.error, nested.message].filter((v) => v !== undefined && v !== null);
      if (diagnostics.length === 0) return false;
      for (const diagnostic of diagnostics) {
        if (typeof diagnostic !== "string" || !isUnofferedToolCallVerdict(diagnostic)) return false;
      }
      // The nested record is held to the same closed code/type sets and carrier ban as the
      // envelope, so a policy code tucked inside `param` cannot ride the verdict into a hop.
      if (nested.param !== undefined && nested.param !== null) return false;
      if (nested.code !== undefined && nested.code !== null
        && (typeof nested.code !== "string" && typeof nested.code !== "number"
          || !UNOFFERED_TOOL_CALL_CODES.has(normalizedFailureCode(nested.code)))) return false;
      if (nested.type !== undefined && nested.type !== null
        && (typeof nested.type !== "string" || !UNOFFERED_TOOL_CALL_TYPES.has(normalizedFailureCode(nested.type)))) return false;
      if (UNOFFERED_TOOL_CALL_CARRIERS.some(carrier => nested[carrier] !== undefined && nested[carrier] !== null)) return false;
    } else {
      return false;
    }
  }
  if (!UNOFFERED_TOOL_CALL_CODES.has(normalizedFailureCode(record.code as string | number | undefined))) return false;
  if (!UNOFFERED_TOOL_CALL_TYPES.has(normalizedFailureCode(record.type as string | undefined))) return false;
  for (const carrier of UNOFFERED_TOOL_CALL_CARRIERS) {
    if (record[carrier] !== undefined && record[carrier] !== null) return false;
  }
  return true;
}

/**
 * A target-local model verdict -- an unoffered tool call, or output the transport could not
 * publish -- is evidence a later combo target may not repeat: the provider answered, the
 * request fit, and the failure arrives before any output commits, so advancing is replay-safe.
 *
 * The envelope is bounded like its siblings: a depth budget, one `Provider error NNN:` or
 * single-line `data:` unwrap per level, closed code/type/param sets, and fail-closed treatment
 * of any record carrying a competing diagnostic carrier or a contradicting root message.
 * Bare verdict text is also a carrier: a chat gateway can surface the sentence with no JSON
 * envelope at all.
 */
export function isUnofferedToolCallRefusal(
  status: number,
  message: string,
  code?: string | number | null,
): boolean {
  if (status !== 400 || message.length > 16_384) return false;
  if (code !== undefined && code !== null && typeof code !== "string" && typeof code !== "number") return false;
  if (!UNOFFERED_TOOL_CALL_CODES.has(normalizedFailureCode(code))) return false;
  let text = message.trim();
  for (let depth = 0; depth < 4; depth += 1) {
    const proxyPrefix = /^Provider error \d{3}: /.exec(text);
    if (proxyPrefix) text = text.slice(proxyPrefix[0].length).trim();
    if (text.startsWith("data:") && !text.includes("\n")) text = text.slice("data:".length).trim();
    let payload: unknown;
    try {
      payload = JSON.parse(text);
    } catch {
      return isUnofferedToolCallVerdict(text);
    }
    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
    const root = payload as Record<string, unknown>;
    if (!unofferedToolCallRecordShape(root)) return false;
    const error = root.error;
    // A nested verdict must agree with the root's own message. When the root carries no error
    // record its message IS the payload carrier and is validated by the flat path below.
    if (error !== undefined && error !== null
      && typeof root.message === "string" && root.message.trim() !== ""
      && !isUnofferedToolCallCarrierVerdict(root.message)) return false;
    if (error === undefined || error === null) {
      if (typeof root.message !== "string") return false;
      if (hasUnofferedToolCallCarrierPrefix(root.message.trim())) {
        text = root.message.trim();
        continue;
      }
      return isUnofferedToolCallVerdict(root.message);
    }
    if (typeof error === "string") {
      if (hasUnofferedToolCallCarrierPrefix(error.trim())) {
        text = error.trim();
        continue;
      }
      return isUnofferedToolCallVerdict(error);
    }
    if (typeof error !== "object" || Array.isArray(error)) return false;
    const record = error as Record<string, unknown>;
    if (!unofferedToolCallRecordShape(record)) return false;
    if (record.error !== undefined && record.error !== null) {
      if (typeof record.error !== "string") return false;
      if (record.error.trim() !== "" && !isUnofferedToolCallVerdict(record.error)) return false;
    }
    if (root.param !== undefined && root.param !== null && record.param !== undefined && record.param !== null
      && String(root.param).trim().toLowerCase() !== String(record.param).trim().toLowerCase()) return false;
    if (typeof record.message !== "string") return false;
    const inner = record.message.trim();
    if (hasUnofferedToolCallCarrierPrefix(inner)) {
      // Our own wrapper, re-wrapped by a downstream hop. Peel it and look again, within budget.
      text = inner;
      continue;
    }
    return isUnofferedToolCallVerdict(record.message);
  }
  return false;
}

/** The classification text the combo path bounds a body to (src/server/responses/core-errors.ts). */
const MODERATION_EVIDENCE_LIMIT = 500;

/** The structured codes that state a provider or gateway moderation verdict. */
const MODERATION_REFUSAL_CODES = new Set(["moderation_refusal", "content_filter"]);

/**
 * Every other code or type a moderation refusal body may carry. Anything outside this list, at any
 * depth, is evidence of something else and the body keeps dev's decision: the hop is granted only
 * to bodies whose structured fields all agree that this is a moderation refusal.
 */
const MODERATION_COMPATIBLE_VALUES = new Set([
  ...MODERATION_REFUSAL_CODES,
  "invalid_request_error", "error", "ai_apicallerror", "responsibleaipolicyviolation", "400", "422",
]);

/** Keys whose values are structured verdicts; folded (lowercase, underscores and hyphens removed). */
const MODERATION_VERDICT_KEYS = new Set(["code", "type", "errorcode", "errortype", "reason"]);

/** Fold a key for comparison: lowercase, underscores and hyphens removed. */
function foldKey(key: string): string {
  return key.toLowerCase().replace(/[_-]/g, "");
}

/** Keys that state an HTTP status; any stated status other than 400/422 is evidence of its own. */
const MODERATION_STATUS_KEYS = new Set(["status", "statuscode", "httpstatus", "httpstatuscode"]);

/** Identifier fields a refusal envelope may carry: a bare token or number, never prose. */
const MODERATION_ID_KEYS = new Set(["id", "requestid", "object", "model", "name", "sequencenumber", "createdat"]);

/**
 * Keys a gateway's routing metadata (providerMetadata) must not use: a field that names a state,
 * status, code or safety verdict is evidence of its own, so only plain routing tokens pass.
 */
const ROUTING_METADATA_EVIDENCE_KEY = /safety|violation|block|polic|account|suspend|disabl|deactivat|ban|status|state|error|code|reason|quota|billing|limit|credit|payment/i;

/**
 * Azure's per-category filter results: the moderation verdict's own detail. Only its own shape
 * passes: category objects of flags and numbers, a `severity` of safe/low/medium/high, bare
 * `id`/`url`/`license` tokens, and compatible codes. Any other text, or a key that names a
 * state, status, error or message, is evidence of its own.
 */
const MODERATION_RESULT_KEY = /^(?:contentfilterresults?|promptfilterresults)$/;
const FILTER_RESULT_EVIDENCE_KEY = /account|status|state|quota|billing|payment|credit|limit|error|message|reason|note|description|detail(?!s$)/i;

/**
 * Response-object fields of a Responses terminal event (`response.failed`) that echo the caller's
 * request or report usage. They say nothing about the failure and are not read.
 */
const RESPONSE_REQUEST_ECHO_KEYS = new Set([
  "instructions", "tools", "toolchoice", "text", "reasoning", "input", "output", "prompt", "include",
  "user", "safetyidentifier", "promptcachekey", "promptcacheretention", "previousresponseid", "conversation",
  "temperature", "topp", "toplogprobs", "maxoutputtokens", "maxtoolcalls", "paralleltoolcalls", "truncation",
  "store", "servicetier", "background", "usage",
]);

/**
 * The whole prose a moderation refusal may carry, after whitespace is collapsed: one verdict
 * sentence (the gateway's own refusal copy, OpenAI's and Azure's included), optionally followed by
 * the category list, the advice to change the prompt and retry, and Azure's documentation pointer.
 * Any other wording (an account, model, parameter or billing problem, in any phrasing) does not
 * match, so the body keeps dev's decision; only known shapes are admitted.
 */
// The anchored scan commits to the first verdict alternative that matches, so alternatives run
// longest-first: Azure's fixed wording leads ("the response was filtered" is a strict prefix of it)
// and the noun-phrased verdict precedes the bare one (its `by ... system` clause reaches further).
const MODERATION_REFUSAL_VERDICT = new RegExp("^(?:"
  + "the response was filtered due to the prompt triggering azure openai'?s content management policy\\.?"
  + "|(?:(?:the|your) )?(?:input|request|prompt|content|message|response|output)(?: (?:was|has been|is))?"
  + " (?:refused|flagged|blocked|rejected|filtered)(?: by (?:the )?(?:moderation|content filter)(?: system)?)?\\.?"
  + "|(?:content )?(?:refused|flagged|blocked|rejected|filtered)(?: by (?:the )?(?:moderation|content filter))?\\.?"
  + "|(?:your )?(?:input|request|prompt|content) violated (?:the )?content (?:safety|management|filtering) polic(?:y|ies)\\.?"
  + ")", "i");
const MODERATION_REFUSAL_TAIL = new RegExp("(?:"
  + "( categor(?:y|ies): )"
  + "| please (?:modify|revise|rephrase|change|adjust|edit) (?:your|the) (?:prompt|input|request|message)(?: and (?:retry|try again))?\\.?"
  + "| (?:please )?(?:retry|try again)(?: later)?\\.?"
  + "| to learn more about our content filtering policies please read our documentation: https://[^ ]+"
  + ")", "iy");
const MODERATION_CATEGORY_WORD = /[a-z][a-z/_-]*/iy;
const MODERATION_CATEGORY_AND = / and /iy;

/** Whether the whole string is known moderation refusal copy. */
function isModerationRefusalProse(text: string): boolean {
  if (text.length > 2_000) return false;
  const prose = text.replace(/\s+/g, " ").trim();
  const verdict = MODERATION_REFUSAL_VERDICT.exec(prose);
  if (!verdict) return false;

  // A comma can introduce the category "and" or the separator ", and ". Keep both
  // interpretations until the rest of the sentence distinguishes them. Each token
  // boundary is visited once, even when several interpretations reach it.
  const tailStarts = new Set([verdict[0].length]);
  const categoryStarts = new Set<number>();
  for (let index = verdict[0].length; index < prose.length; index++) {
    if (tailStarts.has(index)) {
      MODERATION_REFUSAL_TAIL.lastIndex = index;
      const tail = MODERATION_REFUSAL_TAIL.exec(prose);
      if (tail) {
        const next = tail[1] ? categoryStarts : tailStarts;
        next.add(MODERATION_REFUSAL_TAIL.lastIndex);
      }
    }
    if (!categoryStarts.has(index)) continue;
    MODERATION_CATEGORY_WORD.lastIndex = index;
    if (!MODERATION_CATEGORY_WORD.test(prose)) continue;
    const end = MODERATION_CATEGORY_WORD.lastIndex;
    tailStarts.add(prose[end] === "." ? end + 1 : end);
    if (prose.startsWith(", ", end)) categoryStarts.add(end + 2);
    MODERATION_CATEGORY_AND.lastIndex = prose[end] === "," ? end + 1 : end;
    if (MODERATION_CATEGORY_AND.test(prose)) categoryStarts.add(MODERATION_CATEGORY_AND.lastIndex);
  }
  return tailStarts.has(prose.length);
}

/**
 * Safety-system wording in any of its upstream phrasings ("rejected as a result of our safety
 * system", "for safety reasons", "considered high risk"). A safety refusal is the upstream's own
 * terminal verdict, broader than the exact copies safetyRefusalCodeFromMessage names.
 */
const SAFETY_SYSTEM_WORDING = /\bsafety[\s_-]+(?:systems?|reasons?)\b|\bhigh[\s_-]+risk\b/i;

/** Billing, quota and account-state wording: evidence about the provider, not about the prompt. */
const PROVIDER_STATE_WORDING =
  /\bcredit[\s_-]+balance\b|\bquota\b|\bbilling\b|\bpayment[\s_-]+required\b|\binsufficient[\s_-]+(?:quota|balance|funds|credits?)\b|\b(?:account|organi[sz]ation|api[\s_-]*key)\b[^.]{0,40}?\b(?:suspended|disabled|deactivated|banned|inactive|not[\s_-]+active)\b|\brate[\s_-]+limit/i;

/** A refusal names the prompt or input it refused; any other `param` is a validation error. */
function isAllowedModerationParam(param: string): boolean {
  const p = param.trim().toLowerCase();
  return p === "prompt" || p === "input" || p === "messages"
    || p.startsWith("input[") || p.startsWith("input.") || p.startsWith("messages[") || p.startsWith("messages.");
}

/**
 * Any hard-refusal token in any spelling. A moderation code beside one is not evidence that another
 * target may serve the request: the client must not retry these.
 */
const HARD_STOP_TOKENS = [
  "cyber_policy", "origin_rejected", "bio_policy", "misalignment_policy_violation", "invalid_prompt",
  "content_policy_violation", "context_length_exceeded", "client_closed_request", "client_cancelled",
  "upstream_no_response", "upstream_closed_before_response", "upstream_reset_replay_refused",
];
const hardStopPattern = (tokens: readonly string[]) => new RegExp(`(?<![a-z0-9])(?:${tokens.join("|")})(?![a-z0-9])`, "i");
const HARD_STOP_TOKEN = hardStopPattern(HARD_STOP_TOKENS);
/** A provider 413 naming a context overflow is still this target's limit, so only the others veto its hop. */
const HARD_STOP_TOKEN_413 = hardStopPattern(HARD_STOP_TOKENS.filter(token => token !== "context_length_exceeded"));

/** JSON \uXXXX escapes decoded, so an escaped code cannot slip past {@link HARD_STOP_TOKEN}. */
function withJsonEscapesDecoded(text: string): string {
  return text.replace(/\\u([0-9a-fA-F]{4})/g, (_match, hex: string) => String.fromCharCode(Number.parseInt(hex, 16)));
}

/**
 * Whether any hard-refusal token appears in any spelling: JSON escapes decoded (including \n, \t
 * and \r), camel humps split, and hyphens, dots, slashes and whitespace folded to underscores.
 */
function namesHardStopToken(text: string, pattern: RegExp = HARD_STOP_TOKEN): boolean {
  return pattern.test(withJsonEscapesDecoded(text)
    .replace(/\\[ntr]/g, "_")
    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
    .replace(/[-.\s/]+/g, "_"));
}

/** Whether the caller's status and structured code leave room for a moderation hop at all. */
function moderationCodeAllowsHop(status: number, normalizedCode: string): boolean {
  if (status !== 400 && status !== 422) return false;
  return normalizedCode === "" || MODERATION_COMPATIBLE_VALUES.has(normalizedCode);
}

/**
 * The moderation hop for one decision. A caller that read the complete bounded body (the combo
 * failure reader, the stream preflight, the policy path) passes its whole-body verdict; the
 * structured code of this decision can still veto it. Without one, the message decides.
 */
function providerModerationHop(
  status: number, message: string, rawCode: string | null | undefined, wholeBody?: boolean, malformedResponseFormat?: boolean,
): boolean {
  // A malformed response_format diagnostic the reader saw in the whole body stays terminal.
  if (malformedResponseFormat === true) return false;
  if (wholeBody === undefined) return isProviderModerationRefusal(status, message, rawCode);
  return wholeBody && moderationCodeAllowsHop(status, normalizedFailureCode(rawCode));
}

/** Strip this proxy's wrapper prefixes and a single-line SSE data field; undefined unless JSON. */
function moderationEnvelope(message: string): unknown {
  let text = message.trim();
  for (let depth = 0; depth < 3; depth += 1) {
    const prefix = ["Provider error 400: ", "Provider error 422: ", "Provider error: ", "Gateway error 400: ", "Gateway error 422: ", "Gateway error: "]
      .find(candidate => text.startsWith(candidate));
    if (prefix) text = text.slice(prefix.length).trim();
    if (text.startsWith("data:") && !text.includes("\n")) text = text.slice("data:".length).trim();
  }
  try { return JSON.parse(text); } catch { return undefined; }
}

/**
 * Walk a refusal envelope (bounded) against the closed shape of a moderation refusal. Returns whether
 * a moderation code was seen, or null when the body carries anything else: an unknown field, prose
 * that is not refusal copy, a param outside the prompt or input, a stated status other than 400/422,
 * an incompatible code, or more nesting than a refusal envelope has. Only known shapes hop; anything
 * unrecognized keeps dev's decision.
 */
function moderationVerdictFields(payload: unknown): boolean | null {
  let seen = false;
  let nodes = 0;
  const verdict = (field: unknown, key: string, depth: number): boolean => {
    if (field === null || field === undefined) return true;
    // A Responses terminal event names itself in its root `type` (`response.failed`): that is the
    // transport's label for the carrier, not the upstream's verdict.
    if (depth === 0 && key === "type" && typeof field === "string" && /^response\.[a-z_.]+$/.test(field)) return true;
    if (typeof field !== "string" && typeof field !== "number") return false;
    const normalized = normalizedFailureCode(field);
    if (normalized === "") return typeof field === "string";
    if (!MODERATION_COMPATIBLE_VALUES.has(normalized)) return false;
    // Only a code states the provider's moderation verdict. A `type` or an incomplete `reason` of
    // content_filter may sit beside it, but alone it is a model's own output filter, which stays
    // terminal (structure/transports/responses.md).
    if (MODERATION_REFUSAL_CODES.has(normalized) && (foldKey(key) === "code" || foldKey(key) === "errorcode")) seen = true;
    return true;
  };
  const visitFilterResult = (value: unknown, depth: number): boolean => {
    if (++nodes > 512 || depth > 8) return false;
    if (value === null || typeof value === "boolean" || typeof value === "number") return true;
    if (Array.isArray(value)) return value.every(item => visitFilterResult(item, depth + 1));
    if (typeof value !== "object") return false;
    return Object.entries(value as Record<string, unknown>).every(([key, field]) => {
      const folded = foldKey(key);
      if (MODERATION_VERDICT_KEYS.has(folded)) return verdict(field, key, depth);
      if (!/^[a-z][a-z0-9_]*$/i.test(key) || FILTER_RESULT_EVIDENCE_KEY.test(key)) return false;
      if (typeof field === "string") {
        return folded === "severity" ? /^(?:safe|low|medium|high)$/i.test(field)
          : (folded === "id" || folded === "url" || folded === "license") && !/\s/.test(field);
      }
      return visitFilterResult(field, depth + 1);
    });
  };
  // A gateway's routing metadata: plain tokens, numbers and flags only, under keys that name no state.
  const visitRoutingMetadata = (value: unknown, depth: number): boolean => {
    if (++nodes > 512 || depth > 8) return false;
    if (value === null || typeof value === "number" || typeof value === "boolean") return true;
    if (typeof value === "string") return !/\s/.test(value);
    if (Array.isArray(value)) return value.every(item => visitRoutingMetadata(item, depth + 1));
    if (typeof value !== "object") return false;
    return Object.entries(value as Record<string, unknown>).every(([key, field]) =>
      !ROUTING_METADATA_EVIDENCE_KEY.test(key) && visitRoutingMetadata(field, depth + 1));
  };
  const visit = (value: unknown, depth: number, responseObject: boolean): boolean => {
    if (++nodes > 512 || depth > 8) return false;
    if (!value || typeof value !== "object" || Array.isArray(value)) return false;
    const record = value as Record<string, unknown>;
    const responseCarrier = depth === 0 && typeof record.type === "string" && /^response\.[a-z_.]+$/.test(record.type);
    for (const [key, field] of Object.entries(record)) {
      const folded = foldKey(key);
      if (responseObject && RESPONSE_REQUEST_ECHO_KEYS.has(folded)) continue;
      if (MODERATION_VERDICT_KEYS.has(folded)) {
        if (!verdict(field, key, depth)) return false;
      } else if (MODERATION_STATUS_KEYS.has(folded)) {
        if (field === null) continue;
        const stated = typeof field === "number" ? field
          : typeof field === "string" && /^\d{3}$/.test(field.trim()) ? Number(field) : undefined;
        if (stated !== undefined ? stated !== 400 && stated !== 422
          : !(typeof field === "string" && /^(?:failed|incomplete|error)$/i.test(field.trim()))) return false;
      } else if (folded === "message") {
        if (field !== null && field !== "" && !(typeof field === "string" && isModerationRefusalProse(field))) return false;
      } else if (folded === "param") {
        // A param names what the filter inspected: the prompt or input. Any other param is a
        // validation error.
        if (field !== null && typeof field === "object" && !Array.isArray(field)) {
          // An SDK error object in the param slot (an AI gateway's wrapped error) is read as a record.
          if (!visit(field, depth + 1, false)) return false;
        } else if (field !== null && field !== "" && !(typeof field === "string" && isAllowedModerationParam(field))) return false;
      } else if (MODERATION_ID_KEYS.has(folded)) {
        if (field !== null && typeof field !== "number" && !(typeof field === "string" && !/\s/.test(field))) return false;
      } else if (folded === "isretryable") {
        if (field !== null && typeof field !== "boolean") return false;
      } else if (depth === 0 && folded === "providermetadata") {
        if (!visitRoutingMetadata(field, depth + 1)) return false;
      } else if (MODERATION_RESULT_KEY.test(folded)) {
        if (!visitFilterResult(field, depth + 1)) return false;
      } else if (folded === "error") {
        if (field === null) continue;
        if (typeof field === "string" ? !isModerationRefusalProse(field) : !visit(field, depth + 1, false)) return false;
      } else if (folded === "innererror" || (responseObject && folded === "incompletedetails")) {
        if (field !== null && !visit(field, depth + 1, false)) return false;
      } else if (responseObject && folded === "metadata") {
        // The caller's own request metadata; a refusal never needs it, so only an empty one passes.
        if (field !== null && !(typeof field === "object" && !Array.isArray(field) && Object.keys(field).length === 0)) return false;
      } else if (responseCarrier && key === "response") {
        if (!visit(field, depth + 1, true)) return false;
      } else {
        return false;
      }
    }
    return true;
  };
  return visit(payload, 0, false) ? seen : null;
}

/**
 * A provider or gateway moderation refusal on HTTP 400/422 is target-local in a heterogeneous
 * combo: this provider's filter refused the prompt, and another target may serve it.
 *
 * Granted narrowly, on structured evidence only. The verdict must be a structured
 * `moderation_refusal` or `content_filter` code (the caller's or one in the body), every other
 * code or type anywhere in the body must be compatible with it, and no hard-refusal token, safety or
 * terminal copy, malformed response_format diagnostic, subscription gate, or anything the shared
 * classifier files more specifically than a generic invalid request may appear. Prose alone never
 * hops: wording can be echoed back, and a body that carries both prose and another signal is not
 * evidence that the next target may serve the request.
 */
export function isProviderModerationRefusal(
  status: number,
  message: string,
  code?: string | null,
  /** True when `message` is the complete bounded body rather than a possibly cut classification text. */
  complete = false,
): boolean {
  const normalizedCode = normalizedFailureCode(code);
  if (!moderationCodeAllowsHop(status, normalizedCode)) return false;
  const callerStatesModeration = MODERATION_REFUSAL_CODES.has(normalizedCode);
  if (!message) return callerStatesModeration;
  // Hop only on evidence seen whole: the combo path classifies at most the first
  // MODERATION_EVIDENCE_LIMIT characters of a body, and the body readers pass `complete` instead.
  if (!complete && message.length >= MODERATION_EVIDENCE_LIMIT) return false;
  // The same bound as the bounded body readers (64 KiB), so no carrier silently loses a refusal.
  if (message.length > 65_536) return false;
  const lower = message.toLowerCase();
  if (namesHardStopToken(message) || isHardPolicyOrOriginRefusal(message)
    || safetyRefusalCodeFromMessage(message) !== undefined || SAFETY_SYSTEM_WORDING.test(message)
    || isCyberPolicyMessage(message)
    || lower.includes(CYBER_POLICY_FALLBACK_MESSAGE.toLowerCase())
    || lower.includes(TERMINAL_REFUSAL_FALLBACK_MESSAGE.toLowerCase())
    || isMalformedResponseFormatRequest(status, message)
    || isSubscriptionGateMessage(lower)
    // Quota, billing and account-state wording is provider evidence with its own cooldown, even
    // where the classifier files a 400 carrying it as a generic invalid request.
    || isRateLimitOrQuotaFailureMessage(message) || isAnthropicBillingFailure(400, message, undefined)
    || PROVIDER_STATE_WORDING.test(message)
    // Classified as a 400: classifyError maps an untyped 422 to upstream_error.
    || classifyError(400, "upstream_error", message).code !== "invalid_request_error") {
    return false;
  }
  const envelope = moderationEnvelope(message);
  if (envelope === undefined) {
    // Plain text carries no structured fields; only the caller's code can state the verdict, and a
    // body that looks like JSON but does not parse (cut or malformed) never hops.
    return callerStatesModeration && !/^\s*(?:data:\s*)?[[{]/.test(message) && isModerationRefusalProse(message);
  }
  // An envelope root that states a verdict code of its own (invalid_request_error, origin,
  // context length, cancellation...) keeps it, as everywhere else in this file.
  if (envelope && typeof envelope === "object" && !Array.isArray(envelope)) {
    const rootCode = (envelope as Record<string, unknown>).code;
    if (typeof rootCode === "string" && rootCodeStatesVerdict(rootCode)) return false;
  }
  const seen = moderationVerdictFields(envelope);
  return seen !== null && (seen || callerStatesModeration);
}

/** Return the narrowest cooldown scope supported by this target's failure evidence. */
export function comboFailureCooldownScope(
  status: number,
  message: string,
  options?: {
    code?: string | number | null;
    malformedResponseFormat?: boolean;
    openRouterOpaque400?: boolean;
    unofferedToolCallRefusal?: boolean;
    /** Whole-body moderation verdict from a reader that saw the complete bounded body. */
    providerModerationRefusal?: boolean;
  },
): ComboFailureCooldownScope {
  const rawCode = typeof options?.code === "number" ? String(options.code) : options?.code;
  const code = normalizedFailureCode(rawCode);
  if (isAnthropicBillingFailure(status, message, rawCode)) return "provider";
  // Request-shape refusals first: an oversized request must not cool a healthy target.
  // A native transport can surface a zero-output model overflow as a generic
  // upstream_server_error carrying precise context-window prose, so consult the bounded
  // message classifier too: that target is healthy, the turn was simply too large for it.
  if (
    status === 413
    || REQUEST_SHAPE_FAILURE_CODES.has(code)
    || isRequestLocalFreePromptCap(status, message, rawCode)
    || isProviderTargetContextOverflow(status, message, rawCode)
    || isDefiniteContextOverflow(status, message)
    || isRequestLocalTargetIncompatibility(status, message, rawCode)
    // A capability gap says the target is healthy and the request did not fit it, which is the
    // same reason every other entry here refuses to cool a target.
    || isResponseFormatCapabilityRefusal(status, message, rawCode)
    // The provider answered and its model simply called a function it was never offered: the
    // request fit and the target is healthy, so this must not cool it either. A caller that
    // classified the intact bounded body supplies the verdict directly; the display-truncated
    // text here would fail the envelope parse on a long body.
    || (options?.unofferedToolCallRefusal !== undefined
      ? options.unofferedToolCallRefusal
      : isUnofferedToolCallRefusal(status, message, rawCode))
  ) return "none";
  if (isProviderScopedQuotaCap(status, message, rawCode)) return "provider";
  // A rejected or unpaid credential is provider-wide evidence: every target that routes
  // through the same provider row carries the same key and will fail identically.
  if (status === 401 || status === 402 || status === 403) return "provider";
  if (PROVIDER_SCOPED_FAILURE_CODES.has(code)) return "provider";
  // A moderation verdict is target-local, but only after quota and credential evidence had its
  // say: a refusing key beside moderation prose still cools its provider.
  if (providerModerationHop(status, message, rawCode, options?.providerModerationRefusal, options?.malformedResponseFormat)) return "none";
  // OpenRouter's opaque numeric-code wrapper may be target-specific (for example a gateway
  // rejecting a model's translated payload). It may advance the combo, but says nothing about
  // target health and must not quarantine the target.
  if (isUncodedUpstream400(status, message, rawCode, options)) return "none";
  return "target";
}

/** The proxy's own 413 refusals: its translation buffer and body caps, identical for every target. */
const PROXY_OWNED_413_CODES = ["translation_buffer_limit", "inbound_body_too_large", "outbound_body_too_large"];
/**
 * The wording every translator-budget refusal carries ("request ..." or "upstream translation
 * buffer exceeded the safe limit"). Several producers format that 413 with type and code
 * `request_too_large`, which drops `translation_buffer_limit` from the body, so the wording is
 * the one identity that always survives to the combo decision.
 */
const PROXY_TRANSLATION_BUFFER_WORDING = "translation buffer exceeded the safe limit";
/** Request verdicts a 413 can still state; the status alone never outranks them. */
const VERDICT_413_CODES = ["content_policy_violation", "client_closed_request", "client_cancelled"];

/**
 * Whether a 413 is a provider's own intake refusal rather than one this proxy produced. The proxy
 * carries its codes in the structured code (or the type a body falls back to) and in the bounded
 * classification text, so either one marks the refusal as ours. The Ollama late-attribution limit
 * is proxy-owned too and is recognized only by its exact constant, as `isLateAttributionRefusal`
 * does. A 413 that also states a terminal, safety or origin refusal keeps that verdict.
 */
function isProviderIntakeRefusal(message: string, rawCode: string | null | undefined, classifiedCode?: string | null): boolean {
  const code = normalizedFailureCode(rawCode);
  // The classifier's own reading of the text counts too: an uncoded "Request canceled by client"
  // is client_closed_request, and a whole-body caller has no classified code to pass.
  const inferred = normalizedFailureCode(classifiedCode ?? classifyError(413, "upstream_error", message).code);
  if (PROXY_OWNED_413_CODES.includes(code) || VERDICT_413_CODES.includes(code) || VERDICT_413_CODES.includes(inferred)
    || isTerminalRefusalCode(code) || isTerminalRefusalCode(inferred)) {
    return false;
  }
  if (safetyRefusalCodeFromMessage(message) !== undefined || isHardPolicyOrOriginRefusal(message)
    || SAFETY_SYSTEM_WORDING.test(message)) return false;
  if (namesHardStopToken(message, HARD_STOP_TOKEN_413)) return false;
  const lower = message.toLowerCase();
  if (PROXY_OWNED_413_CODES.some(owned => lower.includes(owned)) || lower.includes(PROXY_TRANSLATION_BUFFER_WORDING)) {
    return false;
  }
  // An adapter buffer that overflowed while collecting the answer: the provider already ran the
  // turn, so this 413 is not a refusal before processing and must not reach another target.
  if (Object.values(M365_RESPONSE_LIMIT_MESSAGES).some(limit => message.includes(limit))) return false;
  if (message.trim() === OLLAMA_LATE_ATTRIBUTION_LIMIT_MESSAGE) return false;
  const root = parseErrorEnvelope(message);
  return (root ? envelopeErrorRecord(root) : undefined)?.message !== OLLAMA_LATE_ATTRIBUTION_LIMIT_MESSAGE;
}

/**
 * The whole-body form of {@link isProviderIntakeRefusal}, for a reader that holds the complete
 * bounded 413 body. The classification text the decision receives is cut at 500 characters, so a
 * hard refusal or proxy marker after the cut would otherwise leave the hop open.
 */
export function isProviderIntakeRefusalBody(body: string): boolean {
  return isProviderIntakeRefusal(body, undefined);
}

function isModelLifecycleGone(
  status: number,
  message: string,
  code?: string | null,
): boolean {
  if (status !== 410) return false;
  const normalizedCode = code?.trim().toLowerCase().replaceAll("-", "_");
  if ([
    "model_deprecated",
    "model_end_of_life",
    "model_eol",
    "model_not_found",
    "model_retired",
  ].includes(normalizedCode ?? "")) return true;
  const text = message.toLowerCase();
  return /\bmodel\b/.test(text) && (
    /\bend[ -]of[ -]life\b/.test(text)
    || /\bno longer available\b/.test(text)
    || /\b(?:deprecated|retired|retirement|sunset|decommissioned)\b/.test(text)
  );
}

function isProviderTargetContextOverflow(
  status: number,
  message: string,
  code?: string | null,
): boolean {
  if (status !== 400) return false;
  const normalizedCode = normalizedFailureCode(code);
  const text = message.toLowerCase();
  if (text.includes("invalid_request_prompt_too_long")) return true;
  return normalizedCode === "5059"
    && /\bprompt\s+\d+\s*>\s*\d+\s+maximum context length\b/i.test(message);
}

const CODEX_ACCOUNT_MODEL_REFUSAL = /^The '[^']{1,256}' model is not supported when using Codex with a ChatGPT account\.$/;

export type CodexAccountModelRefusal = "other" | "refusal" | "ambiguous";

/** Inspect only the original root and its own response record, before carrier selection. */
export function hasConflictingCodexModelRefusalEnvelopes(status: number, payload: unknown): boolean {
  if (status !== 400 || !payload || typeof payload !== "object" || Array.isArray(payload)) return false;
  const response = Object.hasOwn(payload, "response") ? (payload as Record<string, unknown>).response : undefined;
  const nested = response && typeof response === "object" && !Array.isArray(response) ? response : undefined;
  return (Object.hasOwn(payload, "detail") || !!nested && Object.hasOwn(nested, "detail"))
    && (Object.hasOwn(payload, "error") || !!nested && Object.hasOwn(nested, "error"));
}

/** Inspect an already parsed, bounded error frame without copying or walking its body. */
export function codexAccountModelRefusalPayload(status: number, payload: unknown): CodexAccountModelRefusal {
  if (status !== 400 || !payload || typeof payload !== "object" || Array.isArray(payload)) return "other";
  if (Object.hasOwn(payload, "detail") && Object.hasOwn(payload, "error")) return "ambiguous";
  const { detail, error } = payload as { detail?: unknown; error?: unknown };
  const field = typeof detail === "string" ? detail
    : error && typeof error === "object" && !Array.isArray(error)
      && typeof (error as Record<string, unknown>).message === "string"
      ? (error as { message: string }).message : undefined;
  return field !== undefined && CODEX_ACCOUNT_MODEL_REFUSAL.test(field) ? "refusal" : "other";
}

/** One complete, bounded HTTP envelope; accept only a single exact status prefix. */
function parseCodexRefusalEnvelope(status: number, message: string): { text: string; payload: unknown } | undefined {
  if (status !== 400 || message.length > 16_384) return undefined;
  let text = message.trim();
  if (text.startsWith("Provider error 400: ")) text = text.slice("Provider error 400: ".length);
  let payload: unknown;
  try { payload = JSON.parse(text); } catch { /* Bare refusal text is also a supported carrier. */ }
  return { text, payload };
}

/** Only allowlisted hard stops cross the same HTTP boundary as positive refusal evidence. */
export function codexAccountModelRefusalHardStopCode(status: number, message: string): string | undefined {
  const payload = parseCodexRefusalEnvelope(status, message)?.payload;
  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
  const root = payload as Record<string, unknown>;
  const response = Object.hasOwn(root, "response") ? root.response : undefined;
  const records = response && typeof response === "object" && !Array.isArray(response)
    ? [root, response as Record<string, unknown>] : [root];
  for (const record of records) {
    const error = record.error && typeof record.error === "object" && !Array.isArray(record.error)
      ? record.error as Record<string, unknown> : undefined;
    // Diagnostic type is never code evidence, even when a code is absent or malformed.
    for (const code of [error?.code, record.code]) {
      if (typeof code !== "string") continue;
      if (isNonReplayableUpstreamCode(code) || isCyberPolicyCode(code)) return code;
      if (normalizedFailureCode(code) === "origin_rejected") return "origin_rejected";
    }
  }
  return undefined;
}

/** A bounded fallback signal, never credential or account-entitlement evidence. */
export function codexAccountModelRefusal(
  status: number, message: string, options?: { allowNestedResponse?: boolean },
): CodexAccountModelRefusal {
  const envelope = parseCodexRefusalEnvelope(status, message);
  if (!envelope) return "other";
  if (CODEX_ACCOUNT_MODEL_REFUSAL.test(envelope.text)) return "refusal";
  const payload = envelope.payload;
  if (hasConflictingCodexModelRefusalEnvelopes(status, payload)) return "ambiguous";
  // A present root carrier stays authoritative, even when malformed or nonmatching.
  if (options?.allowNestedResponse !== false && payload && typeof payload === "object" && !Array.isArray(payload)
    && !Object.hasOwn(payload, "detail") && !Object.hasOwn(payload, "error")
    && Object.hasOwn(payload, "response")) {
    return codexAccountModelRefusalPayload(status, (payload as Record<string, unknown>).response);
  }
  return codexAccountModelRefusalPayload(status, payload);
}

/**
 * Decide whether a zero-output combo failure can move to another eligible target.
 *
 * `rootCode` is the envelope root's own structured code when the record `code` came from is a
 * nested one. Told about both, this applies the same rule for every transport: each code must
 * authorize the hop on its own, so a root hard stop is never hidden behind a retryable record
 * and a retryable pair is not stopped merely because the envelope states them twice.
 */
export function comboFailureDecision(
  status: number,
  message: string,
  options?: {
    code?: string | number | null;
    /** The envelope root's own code when it differs from `code`; absent or blank states none. */
    rootCode?: string | number | null;
    codexModelRefusal?: CodexAccountModelRefusal;
    failedAdapter?: string;
    /** The caller proved the failure is an adapter-normalized plan refusal (`isModelNotInPlanRefusal`). */
    verifiedPlanRefusal?: boolean;
    malformedResponseFormat?: boolean;
    openRouterOpaque400?: boolean;
    unofferedToolCallRefusal?: boolean;
    /** Whole-body moderation verdict from a reader that saw the complete bounded body. */
    providerModerationRefusal?: boolean;
    /** Whole-body 413 intake verdict ({@link isProviderIntakeRefusalBody}); false vetoes the hop. */
    providerIntakeRefusal?: boolean;
  },
): ComboFailureDecision {
  const rootRawCode = typeof options?.rootCode === "number" ? String(options.rootCode) : options?.rootCode;
  const nestedRawCode = typeof options?.code === "number" ? String(options.code) : options?.code;
  const rootCode = normalizedFailureCode(rootRawCode);
  const nestedCode = normalizedFailureCode(nestedRawCode);
  if (rootCode !== "" && rootCode !== nestedCode) {
    if (nestedCode === "") return decideComboFailure(status, message, { ...options, code: rootRawCode });
    const rootDecision = decideComboFailure(status, message, { ...options, code: rootRawCode });
    if (rootDecision === "stop") return "stop";
    return decideComboFailure(status, message, { ...options, code: nestedRawCode }) === "hop"
      ? "hop" : "stop";
  }
  return decideComboFailure(status, message, options);
}

function decideComboFailure(
  status: number,
  message: string,
  options?: {
    code?: string | number | null;
    codexModelRefusal?: CodexAccountModelRefusal;
    failedAdapter?: string;
    verifiedPlanRefusal?: boolean;
    malformedResponseFormat?: boolean;
    openRouterOpaque400?: boolean;
    unofferedToolCallRefusal?: boolean;
    /** Whole-body moderation verdict from a reader that saw the complete bounded body. */
    providerModerationRefusal?: boolean;
    /** Whole-body 413 intake verdict ({@link isProviderIntakeRefusalBody}); false vetoes the hop. */
    providerIntakeRefusal?: boolean;
  },
): ComboFailureDecision {
  if (status === 499) return "stop";
  if (message.toLowerCase().includes("origin_rejected")) return "stop";
  // Structured form of the same hard refusal. The prose test above misses it when the origin
  // reports the code out of band, and every hop rule below -- including the context-overflow
  // one -- must stay subordinate to it.
  const rawCode = typeof options?.code === "number" ? String(options.code) : options?.code;
  if (normalizedFailureCode(rawCode) === "origin_rejected") return "stop";
  // The origin may already be executing this turn (the Codex WebSocket relay sent the create
  // frame and never saw a response event). Hopping would send the same request to a second
  // target while the first may still be generating; the honest status goes to the client.
  if (isNonReplayableUpstreamCode(rawCode)) return "stop";
  // Cyber policy is a hard non-retryable refusal — honor structured code even when
  // classificationText was truncated before the JSON code field.
  if (isCyberPolicyCode(rawCode)) return "stop";
  // HTTP consumers retain hard codes before truncation; SSE metadata owns its selected carrier.
  if (options?.codexModelRefusal === undefined && codexAccountModelRefusalHardStopCode(status, message)) return "stop";
  const modelRefusal = status === 400
    ? options?.codexModelRefusal ?? codexAccountModelRefusal(status, message) : "other";
  // Competing envelopes cannot grant a hop through an earlier structured-code rule either.
  if (modelRefusal === "ambiguous") return "stop";
  // HTTP 410 is normally terminal. A model-specific lifecycle verdict is target-local,
  // however: another provider/model in the declared combo can still serve the request.
  // Require structured lifecycle code or explicit model+lifecycle prose so unrelated
  // application-level 410 responses remain fail-closed.
  if (isModelLifecycleGone(status, message, rawCode)) return "hop";
  const error = classifyError(status, "upstream_error", message);
  if (isCyberPolicyCode(error.code)) return "stop";
  // A 413 that is the proxy's own, or that states a terminal refusal, says nothing about another
  // target's size limit, so every size hop below stays closed for it: the provider-target and
  // definite overflow hops as well as the provider-413 hop. A whole-body reader's verdict covers a
  // marker past the 500-character cut; streaming callers pass the whole event, which the message
  // check reads directly. Hops for other reasons (a model-scoped refusal, say) still apply.
  const sizeHopVetoed = status === 413
    && (options?.providerIntakeRefusal === false || !isProviderIntakeRefusal(message, rawCode, error.code));
  // A provider can expose its own target hard cap with a non-semantic vendor code
  // (for example 5059 + invalid_request_prompt_too_long). That is evidence that this
  // target is too small, not that every later combo target is incapable of serving it.
  if (!sizeHopVetoed && isProviderTargetContextOverflow(status, message, rawCode)) return "hop";
  // A definite context-window refusal is target-local inside a heterogeneous combo: this model
  // cannot hold the turn, but a later target may have a larger window. Two boundaries keep this
  // safe. It is reached only after cancellation, structured origin/cyber refusals and
  // non-replayable post-send codes have already stopped. And it only ever classifies a failure
  // the combo stream preflight already proved emitted no output: `comboStreamPayloadCommitsOutput`
  // commits the child on any text, tool call or unknown event, and only a zero-output terminal
  // becomes a failure response at all, so a turn whose text the client already saw is never
  // reclassified here.
  if (!sizeHopVetoed && isDefiniteContextOverflow(status, message)) return "hop";
  // A provider's HTTP 413 is that target's intake limit (#9017). Combo targets carry different
  // body and token limits, and the provider refused before processing the turn, so the next
  // untried target may accept the unchanged request: the same reasoning as the context-overflow
  // hop above. The proxy's own 413s are identical for every target and stay terminal, as does a
  // 413 that also states a terminal refusal. Cooldown scope stays "none". This reverses the
  // generic-413 stop recorded in devlog/_fin/260904_bug_stack_train/040_deferrals.md
  // (coordinator decision, 2026-11-21); generic 410 is unchanged.
  if (status === 413 && !sizeHopVetoed) return "hop";
  // A local input-admission refusal (#1524) says "this candidate cannot fit the request",
  // not "the request is impossible": the next candidate may have a larger context window.
  //
  // This MUST be tested before the generic stop list below. Our own refusal message says
  // "context window" -- that is what it refuses on -- and the classifier remaps that phrase,
  // so checking the stop list first swallowed the signal and ended the chain. Confirmed
  // upstream context refusals already took the bounded message-classification hop above.
  //
  // Matched on the STRUCTURED code only, which classifyError now preserves for our own
  // refusal. A raw substring test would additionally let any upstream override a terminal
  // verdict by echoing the token in prose we do not control.
  //
  // Precise about what this is NOT: an upstream can still SET this code deliberately, since
  // both extractors read the upstream error object. That is bounded rather than dangerous --
  // an upstream already controls other hop signals (429, 5xx), and traversal is finite: policy
  // tries each candidate once via `tried`, and combo excludes each attempted target. So this is
  // structured-code-only, not provably local.
  if (rawCode === "input_admission_refused" || error.code === "input_admission_refused") {
    return "hop";
  }
  // A degenerate completion is target-local evidence: the child ended its turn carrying only
  // reasoning/commentary prelude. Another target can still serve the same request.
  if (rawCode === "degenerate_completion" || error.code === "degenerate_completion") {
    return "hop";
  }
  if (isProviderScopedQuotaCap(status, message, rawCode || error.code)) {
    return "hop";
  }
  // A model-scoped rejection is target-local: this provider does not serve THIS model, which
  // says nothing about the next combo target. Structured code only, plus the explicit prose
  // form upstreams emit when they carry no code, so an unrelated 400 stays terminal.
  const failureCode = normalizedFailureCode(rawCode || error.code);
  // The input-modality refusal is the same kind of verdict: this route cannot read the turn's
  // media, and a later target may. Its 400 would otherwise end the chain as invalid_request_error.
  if (["model_not_found", "model_unavailable", "unsupported_model", "unsupported_input_modality"].includes(failureCode)) {
    return "hop";
  }
  // So is a plan refusal (#7684): this account's plan excludes THIS model, and it cools only the
  // refused target because `comboFailureCooldownScope` reads a 400 as target-scoped. Unlike the
  // codes above it is honoured only with caller-supplied provenance, never from the code alone.
  if (failureCode === "model_not_in_plan" && options?.verifiedPlanRefusal === true) return "hop";
  if (modelRefusal === "refusal") return "hop";
  // `free_rate_limited` no longer routes through `isProviderScopedQuotaCap` (it is a
  // per-request cap, not provider-wide evidence), so keep its hop verdict explicit here.
  if (failureCode === "free_rate_limited") return "hop";
  if (isRequestLocalTargetIncompatibility(status, message, rawCode)) return "hop";
  // Must precede the generic `invalid_request_error` stop below, which is where this refusal
  // ended the chain: the gateway reports `type: "invalid_request_error"`, so the classifier
  // reaches that list and returns terminal before anything can ask whether the next target
  // could have served the request (#4903).
  if (isResponseFormatCapabilityRefusal(status, message, rawCode)) return "hop";
  if (providerModerationHop(status, message, rawCode, options?.providerModerationRefusal, options?.malformedResponseFormat)) return "hop";
  // A model that calls a function the request never offered hallucinated the call: target-local
  // behavior on a healthy target, arriving as a pre-output 400. Must precede the generic
  // invalid_request_error stop, which is where this envelope ended the chain. A caller that
  // classified the intact bounded body supplies the verdict directly; the display-truncated
  // text here would fail the envelope parse on a long body.
  if (options?.unofferedToolCallRefusal !== undefined
    ? options.unofferedToolCallRefusal
    : isUnofferedToolCallRefusal(status, message, rawCode)) return "hop";
  if (isAnthropicBillingFailure(status, message, rawCode)) return "hop";
  if (isAnthropicExtraUsageFailure(status, message, rawCode)) return "hop";
  // Kiro's body validator rejects the request for the identity it was routed under. The account
  // layer rotates logins first; this is the no-alternate case, so the next combo target is the
  // only remaining chance to serve the turn. Only a caller that knows the failed target is a Kiro
  // adapter grants it (the words alone prove nothing for another provider); it must precede the
  // generic invalid_request_error stop.
  if (options?.failedAdapter === "kiro" && isKiroAccountProfileRefusal(status, message)) return "hop";
  // A structured account-window exhaustion code is provider-state evidence even inside a
  // 400 / invalid_request_error envelope, so it must precede that stop. Exhaustion prose alone
  // never reaches this arm: a validation error can quote quota wording back (#7625).
  if (hasAccountExhaustionCode(rawCode)) return "hop";
  // OpenRouter can wrap an opaque provider failure as a numeric 400 with `metadata.raw: "ERROR"`
  // and no type. Let a heterogeneous combo try another target in this case, while keeping
  // malformed response_format diagnostics terminal and preserving any structured code.
  if (isUncodedUpstream400(status, message, rawCode, options)) return "hop";
  if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
    return "stop";
  }
  // Quota prose inside a request-validation status (400/422) is not authoritative without a
  // structured code: the body can quote prompt or parameter text back (#7625).
  if (error.code === "insufficient_quota" && (status === 400 || status === 422)) return "stop";
  // 402 (payment required) and 425 (too early) are provider-state signals, not verdicts about
  // the request: another combo target can still serve it.
  if ([401, 402, 403, 404, 408, 425, 429].includes(status) || status >= 500) return "hop";
  if ([
    "permission_denied",
    "subscription_required",
    "invalid_api_key",
    "insufficient_quota",
    "payment_required",
    "billing_error",
    "insufficient_balance",
    "rate_limit_exceeded",
    "server_is_overloaded",
    "upstream_server_error",
  ].includes(error.code ?? "")) {
    return "hop";
  }
  return "stop";
}