UNPKG

@bitkyc08/opencodex

Version:

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

1,666 lines • 69.3 kB
/**
 * Data-driven reasoning ladders for routed providers.
 *
 * Routed providers rarely publish per-model effort ladders: OpenCode Zen Go answers /models
 * with ids only (id/object/created/owned_by), so opencodex had to hardcode ladders in
 * registry.ts and synthesise max/ultra for codex-rs catalog membership. The public models.dev
 * catalogue DOES publish them per model:
 *   reasoning: true
 *   reasoning_options: [{type:"effort",values:["low","high","max"]}, {type:"toggle"},
 *                       {type:"budget_tokens"}]
 * This module snapshots that catalogue to disk and hands configuredReasoningEfforts() a
 * fallback ladder, so the Codex catalog AND the wire clamp agree with the model instead of a
 * hand-written guess.
 *
 * Failure policy: a missing or corrupt snapshot yields undefined, and an expired snapshot still
 * serves its last ladder while a best-effort refresh runs in the background. The second
 * cache records rungs the upstream actually rejected (400/403 naming reasoning_effort), so an
 * entitlement gap (muse-spark max needs an active Muse Code subscription) costs one rejected
 * request instead of failing every turn that selects that rung.
 */
import { createHash } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
// Leaf modules on purpose: this file is imported from reasoning-effort.ts, which combos/types.ts
// already imports. Going through the ../config barrel closes a cycle back into account-namespaces.ts
// and leaves COMBO_NAMESPACE in its temporal dead zone for entry points that start at combos/types.ts.
import { atomicWriteFile } from "../config/atomic-write";
import { getConfigDir, withConfigDirHardeningSettled } from "../config/paths";
import {
  extractJsonEnvelope,
  extractJsonEnvelopeWithContext,
  isHardPolicyOrOriginRefusal,
} from "../lib/hard-refusal";
export { extractJsonEnvelope, extractJsonEnvelopeWithContext, isHardPolicyOrOriginRefusal };
import type { OcxProviderConfig } from "../types";
import { resolveProviderApiKey } from "./api-key-resolve";

const FILENAME = "reasoning-metadata-cache.json";
const SUPPORT_FILENAME = "reasoning-support-cache.json";
const SOURCE_URL = "https://models.dev/api.json";
const USER_AGENT = "opencodex-reasoning-metadata/1.0 (+https://github.com/lidge-jun/opencodex)";
/** Snapshot age that triggers a background refresh. Older snapshots still serve reads. */
const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
/** A learned "this rung is refused" fact expires: entitlements change. */
const SUPPORT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
const PERSIST_DEBOUNCE_MS = 250;

/** Canonical Codex ladder order; mirrors reasoning-effort.ts CODEX_REASONING_LEVELS. */
const LADDER_ORDER = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
/** Ranked rungs used for downgrade planning; ultra is client-only and folds to max. */
const RANKED = ["low", "medium", "high", "xhigh", "max"];
/** Mirror of registry.ts THINKING_TOGGLE_EFFORTS / THINKING_BUDGET_EFFORTS. */
const CLASSIFIED_STYLE_EFFORTS = ["low", "medium", "high", "xhigh", "max"];

/**
 * models.dev provider key for a provider config. OcxProviderConfig carries no id, so the
 * destination URL is the stable handle. Only destinations this patch has evidence for are
 * listed; an unlisted provider simply keeps its current behaviour.
 */
const BASE_URL_TO_METADATA_PROVIDER: Record<string, string> = {
  "https://opencode.ai/zen/go/v1": "opencode-go",
  "https://opencode.ai/zen/v1": "opencode",
};

/**
 * Both sides of the mapping are compared after this normalisation, so a trailing slash or a
 * `/v1` suffix never decides whether a destination resolves. models.dev publishes each
 * provider's own `api` URL; the snapshot keeps it (v2) so the mapping can be checked against
 * published data instead of trusted blindly.
 */
export function normalizeDestinationUrl(url: string | undefined): string | undefined {
  if (typeof url !== "string" || url.trim() === "") return undefined;
  try {
    const parsed = new URL(url.trim());
    const path = parsed.pathname.replace(/\/+$/, "").replace(/\/v1$/i, "");
    return (parsed.protocol + "//" + parsed.host + path).toLowerCase();
  } catch {
    return undefined;
  }
}

export type ReasoningMetadataOption = { type: string; values?: string[] };
export type ReasoningMetadataModel = { reasoning: boolean; options: ReasoningMetadataOption[] };

interface MetadataSnapshot {
  version: 1 | 2;
  fetchedAt: number;
  source: string;
  providers: Record<string, Record<string, ReasoningMetadataModel>>;
  /**
   * v2: models.dev provider key -> that provider's published api URL (normalised). v1 snapshots
   * predate the field and keep working through BASE_URL_TO_METADATA_PROVIDER.
   */
  apis?: Record<string, string>;
}

interface SupportSnapshot {
  version: 2;
  rows: Record<string, { effort: string; at: number; evidence?: string }>;
}

let snapshotMemo: MetadataSnapshot | null | undefined;
let supportMemo: Map<string, number> | undefined;
let persistTimer: ReturnType<typeof setTimeout> | null = null;
let refreshInFlight: Promise<RefreshOutcome> | null = null;
/** Bumped by reset so a fired support write still waiting for ACL admission writes nothing. */
let persistGeneration = 0;

/** Test seam: drop the memoised snapshot/support caches so a suite can drive the load paths. */
export function resetReasoningMetadataCachesForTests(): void {
  snapshotMemo = undefined;
  supportMemo = undefined;
  if (persistTimer) {
    clearTimeout(persistTimer);
    persistTimer = null;
  }
  refreshInFlight = null;
  persistGeneration += 1;
}

function readJsonFile<T>(filename: string): T | null {
  try {
    const path = join(getConfigDir(), filename);
    if (!existsSync(path)) return null;
    return JSON.parse(readFileSync(path, "utf8")) as T;
  } catch {
    // A corrupt cache must never break routing, the catalog, or the dashboard.
    return null;
  }
}

/** Canonical order + dedupe. Local mirror of sanitizeCodexReasoningEfforts (import cycle). */
function sanitizeLadder(values: readonly string[] | undefined): string[] | undefined {
  if (!Array.isArray(values)) return undefined;
  const seen = new Set(values.filter((value): value is string => typeof value === "string"));
  const ordered = LADDER_ORDER.filter(effort => seen.has(effort));
  return ordered.length > 0 ? ordered : undefined;
}

function metadataProviderKey(provider: OcxProviderConfig): string | undefined {
  const normalized = normalizeDestinationUrl(typeof provider.baseUrl === "string" ? provider.baseUrl : undefined);
  if (!normalized) return undefined;
  for (const [destination, key] of Object.entries(BASE_URL_TO_METADATA_PROVIDER)) {
    if (normalizeDestinationUrl(destination) === normalized) return key;
  }
  return undefined;
}

/** Whether catalog sync should bootstrap metadata for this destination. */
export function providerUsesReasoningMetadata(provider: OcxProviderConfig): boolean {
  return metadataProviderKey(provider) !== undefined;
}

/**
 * Local mirror of `modelRecordValue()` from `src/reasoning-effort.ts`, which imports this
 * module and so cannot be imported back. Exact id, then the `family:` prefix, then a
 * case-folded match — a configured ladder must resolve here exactly as it does there, or the
 * downgrade rung is chosen off a different ladder than the catalog advertises.
 */
function modelLadderValue(
  record: Record<string, string[]> | undefined,
  modelId: string,
): readonly string[] | undefined {
  if (!record) return undefined;
  if (Object.prototype.hasOwnProperty.call(record, modelId)) return record[modelId];
  const colon = modelId.indexOf(":");
  if (colon > 0) {
    const family = modelId.slice(0, colon);
    if (Object.prototype.hasOwnProperty.call(record, family)) return record[family];
  }
  const folded = modelId.toLowerCase();
  for (const [key, value] of Object.entries(record)) {
    if (key.toLowerCase() === folded) return value;
  }
  return undefined;
}

/**
 * Bind learned capability to the credential that supplied the evidence. A digest keeps the
 * credential itself out of the persisted cache while remaining stable across restarts and key
 * selection. Providers without key-auth identity may use metadata, but cannot teach the cache.
 *
 * The hash input is the resolved wire credential, not the configured expression: the catalog
 * path carries the raw config string in apiKey (a keychain:/env reference stays unresolved
 * there), while the request path carries the resolved secret in apiKey and the configured
 * expression in _apiKeyAttempt.reference. The request path hashes apiKey exactly as routed --
 * the reference is only provenance, and re-resolving it at record time could read a credential
 * rotated since the request was served. The catalog path resolves the configured expression,
 * so both sides still bind learned refusals to the same wire credential, and a rotation behind
 * a stable reference starts clean instead of inheriting the previous credential's refusals.
 */
function credentialIdentity(provider: OcxProviderConfig): string | undefined {
  const resolved = provider._apiKeyAttempt?.reference !== undefined
    ? provider.apiKey
    : resolveProviderApiKey(provider.apiKey);
  if (typeof resolved !== "string" || resolved.length === 0) return undefined;
  return createHash("sha256").update(resolved).digest("hex");
}

/** JSON encoding avoids delimiter ambiguity in provider, model, and effort identifiers. */
function supportKey(providerKey: string, credential: string, modelId: string, effort: string): string {
  return JSON.stringify([providerKey, credential, modelId, effort]);
}

function loadSnapshot(): MetadataSnapshot | null {
  if (snapshotMemo !== undefined) return snapshotMemo;
  const parsed = readJsonFile<MetadataSnapshot>(FILENAME);
  snapshotMemo = parsed && (parsed.version === 1 || parsed.version === 2) && parsed.providers && typeof parsed.providers === "object"
    ? parsed
    : null;
  return snapshotMemo;
}

/**
 * Mapping report for diagnostics and tests: every gated destination, the models.dev provider it
 * resolves to, and whether the snapshot (v2) publishes an `api` URL that confirms it. The gate is
 * deliberate -- 36 of the registry's 83 destinations match a models.dev provider, so resolving by
 * URL alone would silently move ladders for providers this change has no evidence for.
 */
export function reasoningMetadataMapping(): Array<{
  destination: string;
  provider: string;
  publishedApi?: string;
  confirmed?: boolean;
  models: number;
}> {
  const snapshot = loadSnapshot();
  return Object.entries(BASE_URL_TO_METADATA_PROVIDER).map(([destination, provider]) => {
    const normalized = normalizeDestinationUrl(destination);
    const publishedApi = snapshot?.apis?.[provider];
    const row = {
      destination,
      provider,
      ...(publishedApi ? { publishedApi } : {}),
      ...(publishedApi ? { confirmed: publishedApi === normalized } : {}),
      models: Object.keys(snapshot?.providers?.[provider] ?? {}).length,
    };
    return row;
  });
}

function loadSupport(): Map<string, number> {
  const nowMs = Date.now();
  if (supportMemo) {
    // The memo lives for the process lifetime, so the TTL has to be re-applied on every read.
    // Checking it only on the disk load meant a long-running proxy kept clamping on a refusal
    // it recorded a month earlier, and `dropLearnedUnsupportedReasoningEfforts` inherited that
    // through the same map.
    for (const [key, at] of supportMemo) {
      if (nowMs - at > SUPPORT_TTL_MS) {
        supportMemo.delete(key);
        supportEvidence.delete(key);
      }
    }
    return supportMemo;
  }
  const rows = new Map<string, number>();
  const parsed = readJsonFile<SupportSnapshot>(SUPPORT_FILENAME);
  // Version 1 rows had no credential identity and are deliberately invalidated: accepting them
  // would preserve destination-wide refusals written by a lower-entitlement account.
  if (parsed && parsed.version === 2 && parsed.rows && typeof parsed.rows === "object") {
    for (const [key, row] of Object.entries(parsed.rows)) {
      if (!row || typeof row.at !== "number") continue;
      if (nowMs - row.at > SUPPORT_TTL_MS) continue;
      rows.set(key, row.at);
    }
  }
  supportMemo = rows;
  return rows;
}

/** Snapshot health for ocx status / diagnostics. */
export function reasoningMetadataStatus(): { fetchedAt?: number; ageMs?: number; stale: boolean; models: number } {
  const snapshot = loadSnapshot();
  if (!snapshot) return { stale: false, models: 0 };
  const ageMs = Date.now() - snapshot.fetchedAt;
  let models = 0;
  for (const provider of Object.values(snapshot.providers)) models += Object.keys(provider).length;
  return { fetchedAt: snapshot.fetchedAt, ageMs, stale: ageMs > CACHE_TTL_MS, models };
}

export function reasoningMetadataModel(provider: OcxProviderConfig, modelId: string): ReasoningMetadataModel | undefined {
  const key = metadataProviderKey(provider);
  if (!key) return undefined;
  const models = loadSnapshot()?.providers?.[key];
  if (!models) return undefined;
  const model = models[modelId];
  return model && typeof model === "object" ? model : undefined;
}

/** Raw models.dev effort values for a model, canonicalised; undefined when not published. */
export function metadataEffortValues(provider: OcxProviderConfig, modelId: string): string[] | undefined {
  const model = reasoningMetadataModel(provider, modelId);
  if (!model) return undefined;
  const options = Array.isArray(model.options) ? model.options : [];
  const effort = options.find(option => option && option.type === "effort");
  const ladder = sanitizeLadder(effort?.values);
  // none/minimal are sentinels, not picker rungs (mapReasoningEffort folds minimal to low), and
  // advertising them would trip the Codex runtime clamp for no user-visible gain.
  const rungs = ladder?.filter(value => value !== "none" && value !== "minimal");
  return rungs && rungs.length > 0 ? rungs : undefined;
}

/** True when models.dev publishes the named option type (toggle / budget_tokens) for a model. */
export function metadataDeclaresType(provider: OcxProviderConfig, modelId: string, type: string): boolean {
  const model = reasoningMetadataModel(provider, modelId);
  if (!model) return false;
  const options = Array.isArray(model.options) ? model.options : [];
  return options.some(option => option?.type === type);
}

export function isReasoningEffortLearnedUnsupported(provider: OcxProviderConfig, modelId: string, effort: string): boolean {
  const key = metadataProviderKey(provider);
  const credential = credentialIdentity(provider);
  if (!key || !credential) return false;
  return loadSupport().has(supportKey(key, credential, modelId, effort));
}

/**
 * After the ladder is chosen (registry config or models.dev metadata), remove the rungs this
 * account actually had refused. Applied at the configuredReasoningEfforts() exit so a
 * registry-pinned ladder learns exactly like a metadata-derived one; without it a pinned rung
 * the upstream rejects would replay-and-fail on every request. An all-refused ladder keeps the
 * original list: turning "some rungs" into "no effort control" would silently drop the picker.
 */
export function dropLearnedUnsupportedReasoningEfforts(
  provider: OcxProviderConfig,
  modelId: string,
  efforts: readonly string[],
): string[] {
  if (efforts.length === 0) return [...efforts];
  const key = metadataProviderKey(provider);
  if (!key) return [...efforts];
  const credential = credentialIdentity(provider);
  if (!credential) return [...efforts];
  const support = loadSupport();
  if (support.size === 0) return [...efforts];
  const kept = efforts.filter(effort => !support.has(supportKey(key, credential, modelId, effort)));
  return kept.length === 0 ? [...efforts] : kept;
}

/**
 * Metadata fallback ladder for a provider/model.
 *
 * - Published effort values win.
 * - A model the provider already classifies as thinking-toggle / thinking-budget keeps the
 *   provider's own effort list; a toggle-only entry never invents wire semantics here.
 * - Rungs the upstream actually refused are removed; a ladder emptied by that learning
 *   returns undefined (status quo) rather than advertising "no effort control".
 */
export function reasoningEffortsFromMetadata(provider: OcxProviderConfig, modelId: string): string[] | undefined {
  const published = metadataEffortValues(provider, modelId);
  let ladder = published;
  if (!ladder) {
    const classified = (provider.thinkingToggleModels ?? []).includes(modelId)
      || (provider.thinkingBudgetModels ?? []).includes(modelId);
    ladder = classified ? CLASSIFIED_STYLE_EFFORTS : undefined;
  }
  if (!ladder || ladder.length === 0) return undefined;
  const kept = ladder.filter(effort => !isReasoningEffortLearnedUnsupported(provider, modelId, effort));
  if (kept.length === 0) return undefined;
  return kept;
}

const supportEvidence = new Map<string, string>();

/**
 * Record that the upstream refused a rung. Persisted (debounced) so the next catalog sync and
 * every later request clamp before dispatch. Returns true when this is new information.
 */
export function recordUnsupportedReasoningEffort(
  provider: OcxProviderConfig,
  modelId: string,
  effort: string,
  evidence?: string,
): boolean {
  const key = metadataProviderKey(provider);
  const credential = credentialIdentity(provider);
  if (!key || !credential || !effort) return false;
  const rowKey = supportKey(key, credential, modelId, effort);
  const rows = loadSupport();
  if (rows.has(rowKey)) return false;
  rows.set(rowKey, Date.now());
  if (evidence) supportEvidence.set(rowKey, evidence.slice(0, 240));
  if (persistTimer) clearTimeout(persistTimer);
  persistTimer = setTimeout(() => {
    persistTimer = null;
    // Admitted after an overlapping optional config-root ACL flight (#7815); rows are read
    // inside the callback, and a timed-out admission skips this best-effort write.
    const dir = getConfigDir();
    const generation = persistGeneration;
    void withConfigDirHardeningSettled(dir, () => {
      if (generation !== persistGeneration) return;
      const out: SupportSnapshot["rows"] = {};
      for (const [rowKey, at] of rows) {
        const evidenceText = supportEvidence.get(rowKey);
        out[rowKey] = {
          effort: JSON.parse(rowKey)[3] ?? "",
          at,
          ...(evidenceText ? { evidence: evidenceText } : {}),
        };
      }
      atomicWriteFile(join(dir, SUPPORT_FILENAME), JSON.stringify({ version: 2, rows: out }) + "\n");
    }).catch(() => {
      // Best-effort persistence only.
    });
  }, PERSIST_DEBOUNCE_MS);
  return true;
}

/** Test seam: flush a pending support write, admitted like the timer write (#7815). */
export async function flushReasoningSupportCache(): Promise<void> {
  if (!persistTimer) return;
  clearTimeout(persistTimer);
  persistTimer = null;
  const dir = getConfigDir();
  const generation = persistGeneration;
  await withConfigDirHardeningSettled(dir, () => {
    if (generation !== persistGeneration) return;
    const rows = loadSupport();
    const out: SupportSnapshot["rows"] = {};
    for (const [rowKey, at] of rows) {
      const evidenceText = supportEvidence.get(rowKey);
      out[rowKey] = { effort: JSON.parse(rowKey)[3] ?? "", at, ...(evidenceText ? { evidence: evidenceText } : {}) };
    }
    atomicWriteFile(join(dir, SUPPORT_FILENAME), JSON.stringify({ version: 2, rows: out }) + "\n");
  }).catch(() => {
    // Best-effort persistence only.
  });
}

/**
 * Words an upstream uses when it is refusing the parameter it just named. Requiring one of
 * these beside the effort term is what separates "the gateway rejected reasoning effort" from
 * "the gateway rejected something else and echoed the request back".
 */
const REJECTION_LANGUAGE = /unsupported|not supported|does not support|invalid|not valid|unrecognized|unknown|not allowed|not permitted|must be|requires|required|cannot|can't|out of range/i;

/**
 * How far from the effort term the rejection language may sit and still be about it. Kept
 * deliberately short: an error body that echoes the request back puts unrelated field names and
 * their complaints within a hundred characters of each other, so a generous window classifies
 * every 400 that mentions effort as a refusal of it.
 */
const REJECTION_WINDOW = 48;
/**
 * Optional effort repair only analyzes a complete, short diagnostic (UTF-16 code units).
 * Longer input is conflicting evidence, never a prefix to retry or learn from. This bounds
 * the remaining heuristic scans; it does not truncate the upstream response body.
 */
const MAX_REASONING_DIAGNOSTIC_CHARS = 1_024;

/**
 * The `invalid_request_error` type tag rides along on essentially every 400 an OpenAI-shaped
 * gateway emits, so it is evidence of nothing. Blanked before the language scan rather than
 * dropped from the pattern, because `invalid` is real evidence when it is the message.
 */
const GENERIC_ERROR_TYPE = /invalid_request_error/gi;

const EFFORT_COMPATIBLE_CODES = new Set([
  "",
  "invalid_request_error",
  "invalid_argument",
  "invalid_parameter",
  "unsupported_parameter",
  "unsupported_value",
  "invalid_parameter_error",
]);
const EFFORT_COMPATIBLE_TYPES = new Set([
  "",
  "invalid_request_error",
  "upstream_error",
  "bad_request",
]);

/**
 * Error codes and types arrive as snake_case, kebab-case or PascalCase depending on the gateway
 * (Volcengine Ark sends `InvalidParameter` / `BadRequest`). Fold all three to snake_case before the
 * compatibility lookup so a generic vendor code is not read as naming some other field.
 */
function normalizeErrorTag(value: string): string {
  return value.trim().replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().replaceAll("-", "_");
}

function isIncompleteStructuredWrapper(text: string): boolean {
  let s = text.trim();
  for (let d = 0; d < 3; d += 1) {
    if (s.startsWith("Provider error 400: ")) {
      s = s.slice("Provider error 400: ".length).trim();
    } else if (s.startsWith("Provider error: ")) {
      s = s.slice("Provider error: ".length).trim();
    } else if (s.startsWith("Gateway error 400: ")) {
      s = s.slice("Gateway error 400: ".length).trim();
    } else if (s.startsWith("Gateway error: ")) {
      s = s.slice("Gateway error: ".length).trim();
    }
    if (s.startsWith("data:") && !s.includes("\n")) {
      s = s.slice("data:".length).trim();
    }
  }
  if (s.startsWith("{") || s.startsWith("[")) {
    try {
      JSON.parse(s);
      return false;
    } catch {
      return true;
    }
  }
  if (/^(?:(?:Provider|Gateway) error (?:400:\s*)?|data:\s*)[{\[]/i.test(text.trim())) {
    return true;
  }
  const firstBrace = s.indexOf("{");
  const lastBrace = s.lastIndexOf("}");
  if (firstBrace !== -1) {
    let openBraces = 0;
    let inString = false;
    let escape = false;
    for (let i = 0; i < s.length; i += 1) {
      const ch = s[i];
      if (escape) {
        escape = false;
        continue;
      }
      if (ch === "\\") {
        escape = true;
        continue;
      }
      if (ch === '"') {
        inString = !inString;
        continue;
      }
      if (!inString) {
        if (ch === "{") openBraces += 1;
        else if (ch === "}") openBraces -= 1;
      }
    }
    if (openBraces !== 0) return true;
    if (lastBrace > firstBrace && s.slice(firstBrace, lastBrace + 1).includes(":")) {
      try {
        JSON.parse(s.slice(firstBrace, lastBrace + 1));
      } catch {
        return true;
      }
    }
  }
  const firstBracket = s.indexOf("[");
  const lastBracket = s.lastIndexOf("]");
  if (firstBracket !== -1) {
    let openBrackets = 0;
    let inString = false;
    let escape = false;
    for (let i = 0; i < s.length; i += 1) {
      const ch = s[i];
      if (escape) {
        escape = false;
        continue;
      }
      if (ch === "\\") {
        escape = true;
        continue;
      }
      if (ch === '"') {
        inString = !inString;
        continue;
      }
      if (!inString) {
        if (ch === "[") openBrackets += 1;
        else if (ch === "]") openBrackets -= 1;
      }
    }
    if (openBrackets !== 0) return true;
    const bracketSlice = s.slice(firstBracket, lastBracket + 1);
    if (
      lastBracket > firstBracket &&
      (bracketSlice.includes('"') || bracketSlice.includes("'") || bracketSlice.includes(":") || bracketSlice.includes(","))
    ) {
      try {
        JSON.parse(bracketSlice);
      } catch {
        // "reasoning_effort must be one of ['low','medium','high']" is a value list in prose, not
        // a truncated or reflected envelope (#8173).
        if (!isEffortValueEnumeration(bracketSlice)) return true;
      }
    }
  }
  return false;
}

const EFFORT_PARAM_NAMES = new Set([
  "reasoning_effort",
  "reasoning.effort",
  "reasoning",
  "reasoning_parameters",
  "effort",
  // A thinking-budget field is the same subject on the Anthropic-shaped wires: a refusal that
  // names it is about the reasoning control, not about some other parameter.
  "thinking_budget",
  "thinking.budget",
  "thinking.budget_tokens",
]);

function cleanParam(str: string): string {
  return str.trim().toLowerCase().replaceAll("-", "_").replace(/[^a-z0-9_]+$/gi, "").replace(/^[^a-z0-9_]+/gi, "");
}

const KNOWN_NON_EFFORT_PARAMS = new Set([
  "temperature",
  "top_p",
  "top_k",
  "max_tokens",
  "max_completion_tokens",
  "max_output_tokens",
  "min_tokens",
  "stop",
  "stop_sequences",
  "presence_penalty",
  "frequency_penalty",
  "repetition_penalty",
  "logit_bias",
  "logprobs",
  "top_logprobs",
  "seed",
  "tools",
  "tool_choice",
  "functions",
  "function_call",
  "response_format",
  "stream",
  "stream_options",
  "user",
  "service_tier",
  "modalities",
  "prediction",
  "parallel_tool_calls",
  "messages",
  "prompt",
  "n",
  "best_of",
]);

const GENERIC_PARAM_WORDS = new Set([
  "request",
  "requests",
  "argument",
  "arguments",
  "parameter",
  "parameters",
  "param",
  "params",
  "payload",
  "body",
  "input",
  "inputs",
  "json",
  "format",
  "data",
  "content",
  "value",
  "values",
  "field",
  "fields",
  "call",
  "type",
  "error",
  "message",
  "model",
  "url",
  "header",
  "headers",
  "auth",
  "api",
  "key",
  "token",
  "status",
  "code",
  "response",
  "gateway",
  "provider",
  "invalid",
  "unsupported",
  "unknown",
  "unrecognized",
  "unexpected",
  "unallowed",
  "it",
  "this",
  "that",
  "these",
  "those",
  "which",
  "what",
  "all",
  "each",
  "every",
  "both",
  "either",
  "neither",
  "one",
  "they",
  "there",
  "here",
  "string",
  "number",
  "boolean",
  "integer",
  "array",
  "object",
  "null",
  "none",
]);

const EFFORT_RUNGS = new Set([
  "none",
  "low",
  "medium",
  "high",
  "max",
  "xhigh",
  "ultra",
  "minimal",
  "standard",
  "default",
]);

/**
 * Words that describe a diagnostic, never name a request field.
 *
 * "Unsupported parameter: 'reasoning_effort'" puts an adjective exactly where a field name sits
 * in "`field` parameter", and "Unsupported value: 'max'" puts the refused value under a noun.
 * Reading either as the competing subject made genuine effort refusals terminal (#8173).
 */
const DIAGNOSTIC_NOISE_WORDS = new Set([
  "unsupported",
  "invalid",
  "unrecognized",
  "unknown",
  "unexpected",
  "bad",
  "malformed",
  "value",
  "values",
  "parameter",
  "parameters",
  "param",
  "params",
  "field",
  "fields",
  "argument",
  "arguments",
  "arg",
  "property",
  "request",
  "response",
  "payload",
  "body",
  "error",
  // Determiners and participles that introduce the subject: "The following parameter is not
  // supported: reasoning_effort" puts one where a field name would sit.
  "following",
  "specified",
  "given",
  "provided",
  "requested",
  "supplied",
  "above",
  "a",
  "an",
  "the",
  "same",
]);

/**
 * A bare number (or numeric literal) is a value in every diagnostic that names a limit, never a
 * field name, so "thinking budget 32000 is not supported" is not a competing-parameter refusal.
 */
const NUMERIC_VALUE_TOKEN = /^[0-9]+(?:\.[0-9]+)?$/;

/** Connectives and glue words allowed inside a published-value enumeration. */
const EFFORT_ENUMERATION_FILLER = new Set([
  "and",
  "or",
  "values",
  "value",
  "supported",
  "allowed",
  "available",
  "one",
  "of",
  "are",
  "is",
]);

/**
 * Whether a bracket slice is just a list of effort rungs, e.g. `['low','medium','high']`.
 *
 * "reasoning_effort must be one of ['low','medium','high']" is prose that lists the ladder. The
 * structured-wrapper checks treat any bracket payload with commas and quotes as a malformed or
 * reflected envelope, which made this genuine refusal terminal (#8173). A payload composed only
 * of rung names is a value list, not an envelope.
 */
function isEffortValueEnumeration(slice: string): boolean {
  const tokens = slice.match(/[A-Za-z_][A-Za-z0-9_.\-]*|[0-9]+(?:\.[0-9]+)?/g);
  if (!tokens || tokens.length === 0) return false;
  return tokens.every(token => {
    const normalized = token.toLowerCase();
    return EFFORT_RUNGS.has(normalized) || EFFORT_ENUMERATION_FILLER.has(normalized);
  });
}

/** True when every bracketed group in the text is an effort-value enumeration. */
function carriesOnlyEffortEnumerations(text: string): boolean {
  const groups = text.match(/\[[^\]]*\]/g);
  return !!groups && groups.length > 0 && groups.every(isEffortValueEnumeration);
}

const STRUCTURAL_EFFORT_WORDS = new Set([
  "level",
  "mode",
  "rung",
  "rungs",
]);

const SUBJECT_FOLLOWING_VERBS = new Set([
  "is",
  "are",
  "was",
  "were",
  "be",
  "been",
  "being",
  "has",
  "have",
  "had",
  "does",
  "do",
  "did",
  "cannot",
  "cant",
  "can",
  "could",
  "will",
  "would",
  "shall",
  "should",
  "may",
  "might",
  "must",
]);

const REASONING_EFFORT_CONTEXT_REGEX = /\b(?:reasoning[._\s]+effort|reasoning[._\s]+parameters|reasoning|effort)\b/i;

/** How far from a rung value its own clause may name effort and still describe it. */
const EFFORT_DESCRIPTOR_WINDOW = 64;

function isExplicitFieldOrParameter(text: string, matchIndex: number, param: string): boolean {
  if (SUBJECT_FOLLOWING_VERBS.has(param)) return false;
  // "Unsupported parameter", "Invalid value", "Missing field" put a diagnostic word exactly
  // where a field name sits. It is never the subject the sentence is about (#8173).
  if (DIAGNOSTIC_NOISE_WORDS.has(param)) return false;
  // A rung value is never a field name: "Invalid reasoning effort. The max field is invalid."
  // names its subject explicitly in the sentence before, and no diagnostic says "the max field"
  // about an unrelated field named max. Judging the value on its own words first keeps the
  // quoted-field windows below from being applied to a ladder rung.
  if (EFFORT_RUNGS.has(param) && !namesRungAsDeclaredField(text, matchIndex, param)) return false;
  const pre = text.slice(Math.max(0, matchIndex - 48), matchIndex);
  if (
    /\b(?:reasoning[._\s]+effort|reasoning[._\s]+parameters|reasoning|effort)\s+(?:parameter|param|argument|arg|field|property)\s*(?:[:=]\s*['"`]?|['"`]|\s+)\s*$/i.test(
      pre
    )
  ) {
    return false;
  }
  if (/\b(?:parameter|param|argument|arg|field|property)\s*(?:[:=]\s*['"`]?|['"`]|\s+)\s*$/i.test(pre)) return true;
  const post = text.slice(matchIndex + param.length, Math.min(text.length, matchIndex + param.length + 32));
  if (/^\s*['"`]?\s+(?:parameter|param|argument|arg|field|property)\b/i.test(post)) return true;
  return false;
}

/**
 * Whether the rung at `matchIndex` is introduced as a field in its own right — the shapes
 * "the max field", "Invalid field: max", "parameter max" — rather than as a value under a
 * diagnostic noun such as "Unsupported value: 'max'".
 */
function namesRungAsDeclaredField(text: string, matchIndex: number, param: string): boolean {
  const pre = text.slice(Math.max(0, matchIndex - 48), matchIndex);
  if (/\b(?:parameter|param|argument|arg|field|property)\s*(?:[:=]\s*['"`]?|['"`]|\s+)\s*$/i.test(pre)) return true;
  const post = text.slice(matchIndex + param.length, Math.min(text.length, matchIndex + param.length + 32));
  return /^\s*['"`]?\s+(?:parameter|param|argument|arg|field|property)\b/i.test(post);
}

function isEffortDescriptorInContext(text: string, matchIndex: number, param: string): boolean {
  if (EFFORT_RUNGS.has(param)) {
    if (namesRungAsDeclaredField(text, matchIndex, param)) return false;
    // A rung is an effort descriptor when the surrounding words tie it to effort. The context
    // window is the whole diagnostic minus OTHER parameters: a message that ends
    // "Supported values are: 'low','medium','high'" must not turn the refused 'max' into a
    // competing field merely because the same sentence lists a ladder.
    const pre = text.slice(Math.max(0, matchIndex - EFFORT_DESCRIPTOR_WINDOW), matchIndex);
    if (REASONING_EFFORT_CONTEXT_REGEX.test(pre)) return true;
    const post = text.slice(matchIndex + param.length, Math.min(text.length, matchIndex + param.length + EFFORT_DESCRIPTOR_WINDOW));
    return REASONING_EFFORT_CONTEXT_REGEX.test(post);
  }
  if (STRUCTURAL_EFFORT_WORDS.has(param)) {
    const preText = text.slice(Math.max(0, matchIndex - 32), matchIndex);
    return /(?:reasoning[._\s]+effort|reasoning|effort)\s*[:=]?\s*['"`]?$/i.test(preText);
  }
  return false;
}

function tokenStartIndex(m: RegExpExecArray, rawToken: string, isPrefixToken: boolean): number {
  const offset = isPrefixToken ? m[0].indexOf(rawToken) : m[0].lastIndexOf(rawToken);
  return offset >= 0 ? m.index + offset : m.index;
}

function isCompetingParameterToken(text: string, tokenIndex: number, rawToken: string): boolean {
  const p = cleanParam(rawToken);
  if (!p || EFFORT_PARAM_NAMES.has(p) || SUBJECT_FOLLOWING_VERBS.has(p)) return false;
  // A diagnostic adjective or noun ("Unsupported", "invalid", "value", "field") occupies the
  // syntactic slot of a field name without naming one. GENERIC_PARAM_WORDS covers most of them;
  // "bad" and "malformed" were missing there, so the two sets stay separate.
  if (DIAGNOSTIC_NOISE_WORDS.has(p)) return false;
  // A bare number names a limit, not a request field ("thinking budget 32000 is not supported").
  if (NUMERIC_VALUE_TOKEN.test(p)) return false;
  if (isExplicitFieldOrParameter(text, tokenIndex, p)) return true;
  if (GENERIC_PARAM_WORDS.has(p)) return false;
  if (isEffortDescriptorInContext(text, tokenIndex, p)) return false;
  return true;
}

/**
 * Concrete request fields a diagnostic can name instead of effort. Unlike the heuristic subject
 * patterns below, a member of this list is a real wire field, so naming one beside an
 * authoritative effort param really is a different subject.
 */
const CONCRETE_FIELD_TERM =
  /\b(?:temperature|top_p|top_k|max_tokens|max_completion_tokens|max_output_tokens|min_tokens|stop|stop_sequences|presence_penalty|frequency_penalty|repetition_penalty|logit_bias|logprobs|top_logprobs|seed|tools|tool_choice|functions|function_call|response_format|stream|stream_options|user|safety_identifier|service_tier|modalities|prediction|parallel_tool_calls|messages|prompt|input|image_url)\b/gi;

/**
 * Whether the text names a concrete non-effort request field while rejecting something.
 *
 * This is the only inference allowed to override a structured `param` that already names
 * reasoning effort. Everything heuristic in `diagnosticTextNamesOtherParameter` — adjective
 * subjects, quoted rungs, "value:" prefixes — must not, or it would re-break every canonical
 * effort refusal whose prose happens to quote the refused value (#8173).
 */
function diagnosticTextNamesConcreteOtherField(text: string): boolean {
  for (let m = CONCRETE_FIELD_TERM.exec(text); m; m = CONCRETE_FIELD_TERM.exec(text)) {
    const from = Math.max(0, m.index - REJECTION_WINDOW);
    const to = Math.min(text.length, m.index + m[0].length + REJECTION_WINDOW);
    if (REJECTION_LANGUAGE.test(text.slice(from, to))) return true;
  }
  return false;
}

function diagnosticTextNamesOtherParameter(text: string, authoritativeEffortSubject = false): boolean {
  if (!text) return false;
  const s = text.replace(GENERIC_ERROR_TYPE, " ");
  if (authoritativeEffortSubject) return diagnosticTextNamesConcreteOtherField(s);

  const paramPattern = /\b(?:parameter|param|argument|arg|field|property)(?:\s*[:=]\s*['"`]?|\s*['"`]|\s+)['"`]?([a-zA-Z0-9_\-\.]+)['"`]?/gi;
  for (let m = paramPattern.exec(s); m; m = paramPattern.exec(s)) {
    const tokenIndex = tokenStartIndex(m, m[1], false);
    if (isCompetingParameterToken(s, tokenIndex, m[1])) return true;
  }

  const prefixParamPattern = /\b['"`]?([a-zA-Z0-9_\-\.]+)['"`]?\s+(?:parameter|param|argument|arg|field|property)\b/gi;
  for (let m = prefixParamPattern.exec(s); m; m = prefixParamPattern.exec(s)) {
    const tokenIndex = tokenStartIndex(m, m[1], true);
    const beforeToken = s.slice(0, tokenIndex);
    // In "cannot use parameter 'x'", use introduces the label, not a field named use.
    // Quoted field names and verbs outside that diagnostic phrase remain competing subjects.
    if (!/['"`]$/.test(beforeToken) && (m[1].toLowerCase() === "missing"
      || (/^(?:specify|use|set|pass|provide)$/i.test(m[1]) && /\bcannot\s+$/i.test(beforeToken)))) continue;
    if (isCompetingParameterToken(s, tokenIndex, m[1])) return true;
  }

  const subjectMustBe = /\b['"`]?([a-zA-Z0-9_\-\.]+)['"`]?\s+must\s+be\b/gi;
  for (let m = subjectMustBe.exec(s); m; m = subjectMustBe.exec(s)) {
    const tokenIndex = tokenStartIndex(m, m[1], true);
    if (isCompetingParameterToken(s, tokenIndex, m[1])) return true;
  }

  const subjectIsRejection =
    /\b['"`]?([a-zA-Z0-9_\-\.]+)['"`]?\s+(?:is|are)\s+(?:invalid|not\s+valid|unsupported|unrecognized|unknown|not\s+allowed|not\s+permitted|not\s+supported|required|missing)\b/gi;
  for (let m = subjectIsRejection.exec(s); m; m = subjectIsRejection.exec(s)) {
    const tokenIndex = tokenStartIndex(m, m[1], true);
    if (isCompetingParameterToken(s, tokenIndex, m[1])) return true;
  }

  const subjectColon =
    /\b['"`]?([a-zA-Z0-9_\-\.]+)['"`]?\s*:\s*(?:must\s+be|invalid|unsupported|unrecognized|unknown|expected|required|missing|not\s+allowed)\b/gi;
  for (let m = subjectColon.exec(s); m; m = subjectColon.exec(s)) {
    const tokenIndex = tokenStartIndex(m, m[1], true);
    if (isCompetingParameterToken(s, tokenIndex, m[1])) return true;
  }

  const rejectionExtra =
    /\b(?:unexpected|missing|cannot\s+(?:specify|use|set|pass|provide))\s+(?:(?:field|param|parameter|argument|property)\b\s*)?['"`]?([a-zA-Z0-9_\-\.]+)['"`]?/gi;
  for (let m = rejectionExtra.exec(s); m; m = rejectionExtra.exec(s)) {
    const tokenIndex = tokenStartIndex(m, m[1], false);
    if (isCompetingParameterToken(s, tokenIndex, m[1])) return true;
  }

  const nonEffortTerm = /\b(?:temperature|top_p|top_k|max_tokens|max_completion_tokens|max_output_tokens|min_tokens|stop|stop_sequences|presence_penalty|frequency_penalty|repetition_penalty|logit_bias|logprobs|top_logprobs|seed|tools|tool_choice|functions|function_call|response_format|stream|stream_options|user|service_tier|modalities|prediction|parallel_tool_calls|messages|prompt)\b/gi;
  for (let m = nonEffortTerm.exec(s); m; m = nonEffortTerm.exec(s)) {
    const from = Math.max(0, m.index - REJECTION_WINDOW);
    const to = Math.min(s.length, m.index + m[0].length + REJECTION_WINDOW);
    if (REJECTION_LANGUAGE.test(s.slice(from, to))) return true;
  }

  const rejectionDirect = /\b(?:invalid|unsupported|unrecognized|unknown)\s+['"`]?([a-zA-Z0-9_\-\.]+)['"`]?/gi;
  for (let m = rejectionDirect.exec(s); m; m = rejectionDirect.exec(s)) {
    const tokenIndex = tokenStartIndex(m, m[1], false);
    if (isCompetingParameterToken(s, tokenIndex, m[1])) return true;
  }
  return false;
}

function isConflictingDiagnosticProse(str: string | undefined, authoritativeEffortSubject = false): boolean {
  if (!str) return false;
  if (str.length > MAX_REASONING_DIAGNOSTIC_CHARS) return true;
  const s = str.trim();
  if (!s) return false;
  if (
    /\b(?:permission[-_]denied|insufficient[-_]quota|rate[-_]limit[-_]exceeded|model[-_]not[-_]found|context[-_]length[-_]exceeded|access[-_]denied|unauthorized|invalid[-_]api[-_]key|account[-_]deactivated|billing[-_]hard[-_]limit)\b/i.test(s)
  ) {
    return true;
  }
  const codeMatch = /\bcode\s*[:=]\s*["']?([a-zA-Z0-9_\-]+)["']?/i.exec(s);
  if (codeMatch && codeMatch[1]) {
    const code = normalizeErrorTag(codeMatch[1]);
    if (!EFFORT_COMPATIBLE_CODES.has(code) && !isHttpStatusText(code)) return true;
  }
  const typeMatch = /\btype\s*[:=]\s*["']?([a-zA-Z0-9_\-]+)["']?/i.exec(s);
  if (typeMatch && typeMatch[1]) {
    const type = normalizeErrorTag(typeMatch[1]);
    if (!EFFORT_COMPATIBLE_TYPES.has(type)) return true;
  }
  if (diagnosticTextNamesOtherParameter(s, authoritativeEffortSubject)) {
    return true;
  }
  return false;
}

/**
 * Whether a numeric code is the HTTP status echoed back rather than a vendor error code.
 *
 * Google answers a bad reasoning effort with `{"code":400,"error":{"message":"…"}}`, where the
 * numeric field is the response status. Treating it as an unrecognized semantic code made that
 * genuine refusal terminal (#8173). Only 4xx is accepted: a numeric 5xx is a server failure and
 * must keep its terminal verdict.
 */
function isHttpStatusText(token: string): boolean {
  if (!NUMERIC_VALUE_TOKEN.test(token)) return false;
  const value = Number(token);
  return Number.isInteger(value) && value >= 400 && value <= 499;
}

function isHttpStatusNumber(value: unknown): boolean {
  return typeof value === "number" && Number.isInteger(value) && value >= 400 && value <= 499;
}

/**
 * Rejects error envelopes that carry a conflicting code (e.g. permission_denied, insufficient_quota,
 * rate_limit_exceeded, model_not_found, malformed non-string code) or competing diagnostic parameters
 * (e.g. reasoning_effort at root with an inner error identifying temperature) so they stay terminal
 * or proceed to combo failover without false reasoning-effort learning or same-target ladder retries (#8173).
 */
export function hasConflictingReasoningEffortCode(
  text: string | undefined,
  maxEnvelopeChars: 1_024 | 16_384 = MAX_REASONING_DIAGNOSTIC_CHARS,
): boolean {
  if (!text) return false;
  // Exact-refusal failover may inspect a larger complete envelope; prose heuristics
  // retain the short limit even when unrelated metadata makes that envelope larger.
  if (text.length > maxEnvelopeChars) return true;
  if (isIncompleteStructuredWrapper(text)) return true;
  let unescaped = text.trim();
  for (let d = 0; d < 3; d += 1) {
    if (unescaped.startsWith("Provider error 400: ")) {
      unescaped = unescaped.slice("Provider error 400: ".length).trim();
    }
    if (unescaped.startsWith("data:") && !unescaped.includes("\n")) {
      unescaped = unescaped.slice("data:".length).trim();
    }
  }
  let parsed: unknown;
  let outerPrefix = "";
  let outerSuffix = "";
  try {
    parsed = JSON.parse(unescaped);
  } catch {
    const extracted = extractJsonEnvelopeWithContext(unescaped);
    if (extracted) {
      parsed = extracted.value;
      outerPrefix = extracted.prefix;
      outerSuffix = extracted.suffix;
    }
  }
  if (isConflictingDiagnosticProse(outerPrefix) || isConflictingDiagnosticProse(outerSuffix)) {
    return true;
  }
  if (!parsed || typeof parsed !== "object") {
    if (isIncompleteStructuredWrapper(unescaped)) return true;
    const hasBraces = unescaped.includes("{") && unescaped.includes("}");
    const hasBrackets =
      unescaped.includes('["') ||
      (unescaped.includes("[") &&
        unescaped.includes("]") &&
        (unescaped.includes('"') || unescaped.includes("'") || unescaped.includes(",")));
    if (hasBraces || (hasBrackets && !carriesOnlyEffortEnumerations(unescaped))) return true;
    return isConflictingDiagnosticProse(unescaped);
  }
  try {
    const queue: unknown[] = [parsed];
    let examined = 0;
    while (queue.length > 0 && examined < 32) {
      const candidate = queue.shift();
      examined += 1;
      if (!candidate || typeof candidate !== "object") continue;
      if (Array.isArray(candidate)) {
        if (candidate.length > 32) return true;
        for (const item of candidate) {
          if (item && typeof item === "object") {
            queue.push(item);
          } else if (typeof item === "string") {
            if (item.length > 16_384) return true;
            let innerItem: unknown;
            let innerPrefix = "";
            let innerSuffix = "";
            try {
              innerItem = JSON.parse(item);
            } catch {
              const extractedItem = extractJsonEnvelopeWithContext(item);
              if (extractedItem) {
                innerItem = extractedItem.value;
                innerPrefix = extractedItem.prefix;
                innerSuffix = extractedItem.suffix;
              }
            }
            if (innerItem && typeof innerItem === "object") {
              if (isConflictingDiagnosticProse(innerPrefix) || isConflictingDiagnosticProse(innerSuffix)) {
                return true;
              }
              queue.push(innerItem);
            } else if (isIncompleteStructuredWrapper(item)) {
              return true;
            } else {
              const trimmed = item.trim();
              if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
                try {
                  const parsedItem = JSON.parse(item);
                  if (parsedItem && typeof parsedItem === "object") {
                    queue.push(parsedItem);
                  } else {
                    return true;
                  }
                } catch {
                  return true;
                }
              } else {
                const codeLike = normalizeErrorTag(trimmed);
                if (
                  !codeLike.includes(" ") &&
                  (codeLike.includes("_") || codeLike.length < 32) &&
                  !EFFORT_COMPATIBLE_CODES.has(codeLike) &&
                  !EFFORT_COMPATIBLE_TYPES.has(codeLike)
                ) {
                  return true;
                }
                if (isConflictingDiagnosticProse(trimmed)) {
                  return true;
                }
              }
            }
          } else {
            return true;
          }
        }
        continue;
      }
      const rec = candidate as Record<string, unknown>;
      // A structured param/field naming effort is authoritative about the subject. Text
      // inference may only override it by naming a concrete other request field, never by
      // reading a diagnostic adjective or the refused value as a field name (#8173).
      const authoritativeEffortSubject = typeof rec.param === "string" && EFFORT_PARAM_NAMES.has(rec.param.trim().toLowerCase());
      if (rec.param !== undefined && rec.param !== null) {
        if (typeof rec.param !== "string") return true;
        const param = rec.param.trim().toLowerCase();
        if (param.length > 0 && !EFFORT_PARAM_NAMES.has(param)) return true;
      }
      if (rec.code !== undefined && rec.code !== null) {
        if (isHttpStatusNumber(rec.code)) {
          // An HTTP status echoed into `code` says nothing about which field was refused.
        } else if (typeof rec.code !== "string") return true;
        else {
          const code = normalizeErrorTag(rec.code);
          if (!EFFORT_COMPATIBLE_CODES.has(code)) return true;
        }
      }
      if (rec.type !== undefined && rec.type !== null) {
        if (typeof rec.type !== "string") return true;
        const type = normalizeErrorTag(rec.type);
        if (!EFFORT_COMPATIBLE_TYPES.has(type)) return true;
      }
      for (const field of ["message", "error", "details", "detail", "response", "last_error", "errors"] as const) {
        const val = rec[field];
        if (val && typeof val === "object") {
          queue.push(val);
        } else if (typeof val === "string") {
          let inner: unknown;
          let innerPrefix = "";
          let innerSuffix = "";
          try {
            inner = JSON.parse(val);
          } catch {
            const extracted = extractJsonEnvelopeWithContext(val);
            if (extracted) {
              inner = extracted.value;
              innerPrefix = extracted.prefix;
              innerSuffix = extracted.suffix;
            }
          }
          if (inner && typeof inner === "object") {
            if (isConflictingDiagnosticProse(innerPrefix, authoritativeEffortSubject) || isConflictingDiagnosticProse(innerSuffix, authoritativeEffortSubject)) {
              return true;
            }
            queue.push(inner);
          } else if (isIncompleteStructuredWrapper(val)) {
            return true;
          } else if (isConflictingDiagnosticProse(val, authoritativeEffortSubject)) {
            return true;
          }
        }
      }
    }
    if (queue.length > 0) {
      return true;
    }
  } catch {
    return false;
  }
  return false;
}

function diagnosticTextBlamesReasoningEffort(text: string): boolean {
  if (diagnosticTextNamesOtherParameter(text)) return false;
  if (/unsupported.{0,24}effort/i.test(text)) return true;
  const scanned = text.replace(GENERIC_ERROR_TYPE, " ");
  const term = /reasoning\.effort|reasoning_effort|reasoning effort|thinking budget|reasoning_parameters/gi;
  for (let match = term.exec(scanned); match; match = term.exec(scanned)) {
    const preText = scanned.slice(0, match.index);
    const postText = scanned.slice(match.index + match[0].length);
    const lastBoundary = Math.max(
      preText.lastIndexOf(";"),
      preText.lastIndexOf("\n"),
      preText.lastIndexOf("|"),
      preText.search(/\.(?:\s+|$)(?=[^.]*$)/)
    );
    const clauseStart = lastBoundary !== -1 ? lastBoundary + 1 : 0;
    const nextBoundary = postText.search(/[;\n|]|\.(?:\s+|$)/);
    const clauseEnd = nextBoundary !== -1 ? match.index + match[0].length + nextBoundary : scanned.length;

    const from = Math.max(clauseStart, match.index - REJECTION_WINDOW);
    const to = Math.min(clauseEnd, match.index + match[0].length + REJECTION_WINDOW);
    const windowText = scanned.slice(from, to);
    if (REJECTION_LANGUAGE.test(windowText)) {
      if (!diagnosticTextNamesOtherParameter(windowText)) {
        return true;
      }
    }
  }
  return false;
}

function diagnosticRecordBlamesReasoningEffort(rec: Record<string, unknown>, depth = 0): boolean {
  if (depth > 4) return false;
  if (typeof rec.param === "string") {
    const param = rec.param.trim().toLowerCase();
    if (EFFORT_PARAM_NAMES.has(param)) return true;
    return false;
  }
  if (typeof rec.message === "string") {
    if (rec.message.includes("{") || rec.message.startsWith("Provider error 400: ")) {
      return isReasoningEffortRejection(rec.message, depth + 1);
    }
    if (diagnosticTextBlamesReasoningEffort(rec.message)) return true;
  }
  if (typeof rec.error === "string") {
    if (rec.error.includes("{") || rec.error.startsWith("Provider error 400: ")) {
      return isReasoningEffortRejection(rec.error, depth + 1);
    }
    if (diagnosticTextBlamesReasoningEffort(rec.error)) return true;
  }
  if (typeof rec.detail === "string") {
    if (rec.detail.includes("{") || rec.detail.startsWith("Provider error 400: ")) {
      return isReasoningEffortRejection(rec.detail, depth + 1);
    }
    if (diagnosticTextBlamesReasoningEffort(rec.detail)) return true;
  } else if (Array.isArray(rec.detail)) {
    for (const item of rec.detail) {
      if (item && typeof item === "object") {
        if (diagnosticRecordBlamesReasoningEffort(item as Record<string, unknown>, depth + 1)) return true;
      } else if (typeof item === "string") {
        if (item.includes("{") || item.startsWith("Provider error 400: ")) {
          if (isReasoningEffortRejection(item, depth + 1)) return true;
        } else if (diagnosticTextBlamesReasoningEffort(item)) {
          return true;
        }
      }
    }
  } else if (rec.detail && typeof rec.detail === "object") {
    if (diagnosticRecordBlamesReasoningEffort(rec.detail as Record<string, unknown>, depth + 1)) return true;
  }
  if (typeof rec.details === "string") {
    if (rec.details.includes("{") || rec.details.startsWith("Provider error 400: ")) {
      return isReasoningEffortRejection(rec.details, depth + 1);
    }
    if (diagnosticTextBlamesReasoningEffort(rec.details)) return true;
  } else if (Array.isArray(rec.details)) {
    for (const item of rec.details) {
      if (item && typeof item === "object") {
        if (diagnosticRecordBlamesReasoningEffort(item as Record<string, unknown>, depth + 1)) return true;
      } else if (typeof item === "string") {
        if (item.includes("{") || item.startsWith("Provider error 400: ")) {
          if (isReasoningEffortRejection(item, depth + 1)) return true;
        } else if (diagnosticTextBlamesReasoningEffort(item)) {
          return true;
        }
      }
    }
  } else if (rec.details && typeof rec.details === "object") {
    if (diagnosticRecordBlamesReasoningEffort(rec.details as Record<string, unknown>, depth + 1)) return true;
  }
  if (typeof rec.last_error === "string") {
    if (rec.last_error.includes("{") || rec.last_error.startsWith("Provider error 400: ")) {
      return isReasoningEffortRejection(rec.last_error, depth + 1);
    }
    if (diagnosticTextBlamesReasoningEffort(rec.last_error)) return true;
  } else if (rec.last_error && typeof rec.last_error === "object") {
    if (diagnosticRecordBlamesReasoningEffort(rec.last_error as Record<string, unknown>, depth + 1)) return true;
  }
  return false;
}

/**
 * Evidence test for a rejection body: does it blame reasoning effort?
 *
 * Restricts inspections to authoritative diagnostic carriers (error, errors, details, detail, last_error, response)
 * so echoed request context (e.g. request.param: "reasoning_effort") does not falsely classify unrelated 400s
 * (such as temperature or max_tokens errors) as effort refusals (#8173).
 */
export function isReasoningEffortRejection(text: string | undefined, depth = 0): boolean {
  if (!text || text.length > MAX_REASONING_DIAGNOSTIC_CHARS || depth > 4) return false;
  if (isHardPolicyOrOriginRefusal(text)) return false;
  if (hasConflictingReasoningEffortCode(text)) return false;

  let unescaped = text.trim();
  for (let d = 0; d < 3; d += 1) {
    if (unescaped.startsWith("Provider error 400: ")) {
      unescaped = unescaped.slice("Provider error 400: ".length).trim();
    }
    if (unescaped.startsWith("data:") && !unescaped.includes("\n")) {
      unescaped = unescaped.slice("data:".length).trim();
    }
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(unescaped);
  } catch {
    parsed = extractJsonEnvelope(unescaped);
  }

  if (parsed && typeof parsed === "object") {
    if (Array.isArray(parsed)) {
      if (hasConflictingReasoningEffortCode(unescaped)) return false;
      for (const item of parsed) {
        if (item && typeof item === "object") {
          if (diagnosticRecordBlamesReasoningEffort(item as Record<string, unknown>, depth + 1)) return true;
        } else if (typeof item === "string") {
          if (item.includes("{") || item.startsWith("Provider error 400: ")) {
            if (isReasoningEffortRejection(item, depth + 1)) return true;
          } else if (diagnosticTextBlamesReasoningEffort(item)) {
            return true;
          }
        }
      }
      return false;
    }

    const root = parsed as Record<string, unknown>;

    if (root.error !== undefined && root.error !== null) {
      if (typeof root.error === "object" && !Array.isArray(root.error)) {
        if (diagnosticRecordBlamesReasoningEffort(root.error as Record<string, unknown>, depth + 1)) return true;
      } else if (typeof root.error === "string") {
        if (root.error.includes("{") || root.error.startsWith("Provider error 400: ")) {
          if (isReasoningEffortRejection(root.error, depth + 1)) return true;
        } else if (diagnosticTextBlamesReasoningEffort(root.error)) {
          return true;
        }
      }
    }

    if (Array.isArray(root.errors)) {
      for (const item of root.errors) {
        if (item && typeof item === "object") {
          if (diagnosticRecordBlamesReasoningEffort(item as Record<string, unknown>, depth + 1)) return true;
        } else if (typeof item === "string") {
          if (item.includes("{") || item.startsWith("Provider error 400: ")) {
            if (isReasoningEffortRejection(item, depth + 1)) return true;
          } else if (diagnosticTextBlamesReasoningEffort(item)) {
            return true;
          }
        }
      }
    }

    if (Array.isArray(root.details)) {
      for (const item of root.details) {
        if (item && typeof item === "object") {
          if (diagnosticRecordBlamesReasoningEffort(item as Record<string, unknown>, depth + 1)) return true;
        } else if (typeof item === "string") {
          if (item.includes("{") || item.startsWith("Provider error 400: ")) {
            if (isReasoningEffortRejection(item, depth + 1)) return true;
          } else if (diagnosticTextBlamesReasoningEffort(item)) {
            return true;
          }
        }
      }
    } else if (typeof root.details === "string") {
      if (root.details.includes("{") || root.details.startsWith("Provider error 400: ")) {
        if (isReasoningEffortRejection(root.details, depth + 1)) return true;
      } else if (diagnosticTextBlamesReasoningEffort(root.details)) {
        return true;
      }
    } else if (root.details && typeof root.details === "object") {
      if (diagnosticRecordBlamesReasoningEffort(root.details as Record<string, unknown>, depth + 1)) return true;
    }

    if (typeof root.detail === "string") {
      if (root.detail.includes("{") || root.detail.startsWith("Provider error 400: ")) {
        if (isReasoningEffortRejection(root.detail, depth + 1)) return true;
      } else if (diagnosticTextBlamesReasoningEffort(root.detail)) {
        return true;
      }
    } else if (Array.isArray(root.detail)) {
      for (const item of root.detail) {
        if (item && typeof item === "object") {
          if (diagnosticRecordBlamesReasoningEffort(item as Record<string, unknown>, depth + 1)) return true;
        } else if (typeof item === "string") {
          if (item.includes("{") || item.startsWith("Provider error 400: ")) {
            if (isReasoningEffortRejection(item, depth + 1)) return true;
          } else if (diagnosticTextBlamesReasoningEffort(item)) {
            return true;
          }
        }
      }
    } else if (root.detail && typeof root.detail === "object") {
      if (diagnosticRecordBlamesReasoningEffort(root.detail as Record<string, unknown>, depth + 1)) return true;
    }

    if (typeof root.last_error === "string") {
      if (root.last_error.includes("{") || root.last_error.startsWith("Provider error 400: ")) {
        if (isReasoningEffortRejection(root.last_error, depth + 1)) return true;
      } else if (diagnosticTextBlamesReasoningEffort(root.last_error)) {
        return true;
      }
    } else if (root.last_error && typeof root.last_error === "object") {
      if (diagnosticRecordBlamesReasoningEffort(root.last_error as Record<string, unknown>, depth + 1)) return true;
    }

    if (root.response && typeof root.response === "object") {
      const resp = root.response as Record<string, unknown>;
      if (resp.error && typeof resp.error === "object") {
        if (diagnosticRecordBlamesReasoningEffort(resp.error as Record<string, unknown>, depth + 1)) return true;
      }
      if (typeof resp.last_error === "string") {
        if (resp.last_error.includes("{") || resp.last_error.startsWith("Provider error 400: ")) {
          if (isReasoningEffortRejection(resp.last_error, depth + 1)) return true;
        } else if (diagnosticTextBlamesReasoningEffort(resp.last_error)) {
          return true;
        }
      } else if (resp.last_error && typeof resp.last_error === "object") {
        if (diagnosticRecordBlamesReasoningEffort(resp.last_error as Record<string, unknown>, depth + 1)) return true;
      }
      if (typeof resp.details === "string") {
        if (resp.details.includes("{") || resp.details.startsWith("Provider error 400: ")) {
          if (isReasoningEffortRejection(resp.details, depth + 1)) return true;
        } else if (diagnosticTextBlamesReasoningEffort(resp.details)) {
          return true;
        }
      } else if (resp.details && typeof resp.details === "object") {
        if (diagnosticRecordBlamesReasoningEffort(resp.details as Record<string, unknown>, depth + 1)) return true;
      }
      if (typeof resp.detail === "string") {
        if (resp.detail.includes("{") || resp.detail.startsWith("Provider error 400: ")) {
          if (isReasoningEffortRejection(resp.detail, depth + 1)) return true;
        } else if (diagnosticTextBlamesReasoningEffort(resp.detail)) {
          return true;
        }
      } else if (resp.detail && typeof resp.detail === "object") {
        if (diagnosticRecordBlamesReasoningEffort(resp.detail as Record<string, unknown>, depth + 1)) return true;
      }
    }

    if (root.error === undefined || typeof root.error !== "object") {
      if (diagnosticRecordBlamesReasoningEffort(root, depth + 1)) return true;
    }

    return false;
  }

  const hasBraces = unescaped.includes("{") && unescaped.includes("}");
  const hasBrackets =
    unescaped.includes('["') ||
    (unescaped.includes("[") &&
      unescaped.includes("]") &&
      (unescaped.includes('"') || unescaped.includes("'") || unescaped.includes(",")));
  if (hasBraces || (hasBrackets && !carriesOnlyEffortEnumerations(unescaped))) return false;
  if (isIncompleteStructuredWrapper(unescaped)) return false;

  return diagnosticTextBlamesReasoningEffort(unescaped);
}

/**
 * Plan a single-rung downgrade for a rejected request: records the refusal (so later turns
 * clamp before dispatch) and returns the next lower rung the model does publish.
 */
export function planReasoningEffortDowngrade(args: {
  provider: OcxProviderConfig;
  modelId: string;
  requested?: string;
  rejectionText?: string;
}): { effort: string; recorded: boolean } | undefined {
  if (args.rejectionText && (isHardPolicyOrOriginRefusal(args.rejectionText) || hasConflictingReasoningEffortCode(args.rejectionText))) return undefined;
  const requested = args.requested === "ultra" ? "max" : args.requested;
  if (!requested || !RANKED.includes(requested)) return undefined;
  const recorded = recordUnsupportedReasoningEffort(args.provider, args.modelId, requested, args.rejectionText);
  // Same precedence as configuredReasoningEfforts(): a hand-written ladder is a contract and
  // models.dev is only consulted when nothing was configured for this model. Reading metadata
  // first would have picked the downgrade rung off the published ladder even where a pinned
  // one disagreed, so the replay could land on a rung the registry deliberately excludes.
  const effective = sanitizeLadder(modelLadderValue(args.provider.modelReasoningEfforts, args.modelId))
    ?? sanitizeLadder(args.provider.reasoningEfforts)
    ?? metadataEffortValues(args.provider, args.modelId);
  const ladder = (effective ?? []).filter(effort => RANKED.includes(effort));
  if (ladder.length === 0) return undefined;
  const candidates = ladder
    .filter(effort => RANKED.indexOf(effort) < RANKED.indexOf(requested))
    .filter(effort => !isReasoningEffortLearnedUnsupported(args.provider, args.modelId, effort));
  if (candidates.length === 0) return undefined;
  return { effort: candidates[candidates.length - 1], recorded };
}

/**
 * Refresh the models.dev snapshot. Best-effort and idempotent: never throws, never blocks a
 * request, keeps the previous snapshot on failure. Ladders are stored for the gated destinations
 * only (OpenCode Zen + Zen Go: about 130 models), while every published provider `api` URL is
 * kept so the gate can be checked against real data and widened without another format change.
 * Non-reasoning models carry no ladder and are dropped.
 */
type RefreshOutcome = {
  ok: boolean;
  reason: string;
  providers?: number;
  models?: number;
};

/** Bound a caller's wait without cancelling the shared refresh job. */
function waitForRefresh(work: Promise<RefreshOutcome>, waitMs: number | undefined): Promise<RefreshOutcome> {
  if (waitMs === undefined) return work;
  if (!Number.isSafeInteger(waitMs) || waitMs < 0) {
    return Promise.resolve({ ok: false, reason: "invalid wait budget" });
  }
  let timer: ReturnType<typeof setTimeout> | undefined;
  const deadline = new Promise<RefreshOutcome>(resolve => {
    timer = setTimeout(() => resolve({ ok: false, reason: "wait budget exceeded" }), waitMs);
    timer.unref?.();
  });
  return Promise.race([work, deadline]).finally(() => {
    if (timer) clearTimeout(timer);
  });
}

export async function refreshReasoningMetadata(options: { force?: boolean; waitMs?: number } = {}): Promise<RefreshOutcome> {
  const snapshot = loadSnapshot();
  if (!options.force && snapshot && Date.now() - snapshot.fetchedAt <= CACHE_TTL_MS) {
    return { ok: true, reason: "fresh" };
  }
  if (refreshInFlight) {
    // A joined caller learns the shared outcome: a refused or failed refresh is not a success.
    return waitForRefresh(refreshInFlight.then(outcome => outcome.ok ? { ok: true, reason: "coalesced" } : outcome), options.waitMs);
  }
  const job = (async () => {
    const response = await fetch(SOURCE_URL, {
      headers: { "user-agent": USER_AGENT, accept: "application/json" },
      // A hanging connection must not pin refreshInFlight for the life of the process.
      signal: AbortSignal.timeout(15_000),
    });
    if (!response.ok) throw new Error("models.dev HTTP " + response.status);
    const raw = await response.json() as Record<string, { api?: unknown; models?: Record<string, unknown> }>;
    const providers: MetadataSnapshot["providers"] = {};
    const apis: Record<string, string> = {};
    const gated = new Set(Object.values(BASE_URL_TO_METADATA_PROVIDER));
    let models = 0;
    for (const [providerKey, entry] of Object.entries(raw ?? {})) {
      const api = normalizeDestinationUrl(typeof entry?.api === "string" ? entry.api : undefined);
      if (api) apis[providerKey] = api;
      if (!gated.has(providerKey)) continue;
      const out: Record<string, ReasoningMetadataModel> = {};
      for (const [modelId, value] of Object.entries(entry?.models ?? {})) {
        const model = value as { reasoning?: unknown; reasoning_options?: unknown };
        if (model?.reasoning !== true) continue;
        const options: ReasoningMetadataOption[] = [];
        if (Array.isArray(model?.reasoning_options)) {
          for (const option of model.reasoning_options) {
            if (!option || typeof option !== "object") continue;
            const type = (option as { type?: unknown }).type;
            if (typeof type !== "string") continue;
            const values = (option as { values?: unknown }).values;
            options.push({
              type,
              ...(Array.isArray(values)
                ? { values: values.filter((v): v is string => typeof v === "string").slice(0, 12) }
                : {}),
            });
          }
        }
        out[modelId] = { reasoning: model?.reasoning === true, options };
        models += 1;
      }
      if (Object.keys(out).length === 0) continue;
      providers[providerKey] = out;
    }
    const next: MetadataSnapshot = { version: 2, fetchedAt: Date.now(), source: SOURCE_URL, providers, apis };
    // The last await is the network read; publication waits out an overlapping optional
    // config-root ACL flight (#7815) and a timed-out admission fails this refresh unpublished.
    const dir = getConfigDir();
    await withConfigDirHardeningSettled(dir, () => atomicWriteFile(join(dir, FILENAME), JSON.stringify(next) + "\n"));
    snapshotMemo = next;
    return { ok: true, reason: "refreshed", providers: Object.keys(providers).length, models };
  })();
  const settled = job.catch((error): RefreshOutcome => ({
    ok: false,
    reason: error instanceof Error ? error.message : String(error),
  }));
  const shared = settled.finally(() => { if (refreshInFlight === shared) refreshInFlight = null; });
  refreshInFlight = shared;
  return waitForRefresh(settled, options.waitMs);
}

/**
 * Optional background refresh for callers that do not wait for a snapshot. Catalog sync uses
 * refreshReasoningMetadata with a bounded wait; an expired ladder read can request this refresh.
 * A classified toggle/budget model can have a fallback ladder without any snapshot, so this
 * path must never bootstrap a missing snapshot. One refresh per process; failures are ignored.
 */
export function ensureReasoningMetadataSnapshot(): void {
  const snapshot = loadSnapshot();
  if (!snapshot || Date.now() - snapshot.fetchedAt <= CACHE_TTL_MS) return;
  if (refreshInFlight) return;
  void refreshReasoningMetadata().catch(() => undefined);
}