UNPKG

@bitkyc08/opencodex

Version:

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

1,237 lines • 68.5 kB
import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
import { shouldInjectApiAuthHeader } from "../../codex/loopback-target";

/**
 * Codex parses a catalog entry's `input_modalities` as a closed enum, and one out-of-enum
 * value makes it reject the ENTIRE catalog file — plugins, apps and MCP servers all stop
 * loading over one model's metadata (#759).
 *
 * The catalog writer normalizes on the way out, but a rejected value stored here would still
 * be handed back to the GUI and CLI as if it were real, and the offline `ocx models add` path
 * already refuses it. Validate at ingress so all three paths agree.
 */
/**
 * The modalities a declaration may carry. `video` is missing on purpose: the wire carries text
 * and image parts, so advertising it would be a promise no request path can keep.
 */
type DeclaredInputModality = NonNullable<ModelCapabilities["inputModalities"]>[number];

// A plain string set on purpose: the lookup runs against unvalidated input, and the enum lives in
// the return type below, where the cast is the validator's stated guarantee.
const ALLOWED_INPUT_MODALITIES: ReadonlySet<string> = new Set(["text", "image", "audio"]);

function readInputModalities(raw: unknown): { values?: DeclaredInputModality[]; error?: string } {
  if (raw === undefined) return {};
  if (!Array.isArray(raw)) return { error: "inputModalities must be an array" };
  // Reject non-strings rather than filtering them out. Dropping them silently accepted a
  // malformed POST and, worse, let a PUT of `[42]` clear the stored modalities while
  // answering 200 — the opposite of the contract this validator exists to state. An empty
  // array stays valid: that is how `ocx models edit --modalities -` clears the field.
  const rejected: string[] = [];
  for (const value of raw) {
    if (typeof value !== "string") return { error: "inputModalities must contain only strings" };
    if (!ALLOWED_INPUT_MODALITIES.has(value)) rejected.push(value);
  }
  if (rejected.length > 0) {
    return { error: `unsupported input modality: ${rejected.join(", ")} (allowed: text, image, audio)` };
  }
  return { values: raw as DeclaredInputModality[] };
}

/**
 * Custom-row reasoning ladder. Labels are validated against the Codex ladder (low..ultra)
 * exactly like provider `modelReasoningEfforts` values; unknown labels would otherwise
 * surface in a catalog the upstream never accepts. An empty array is meaningful (explicit
 * "no reasoning" hides the effort control) and must be preserved, not cleared.
 */
function readReasoningEfforts(raw: unknown): { values?: string[]; error?: string } {
  if (raw === undefined) return {};
  if (!Array.isArray(raw)) return { error: "reasoningEfforts must be an array" };
  const rejected: string[] = [];
  const values: string[] = [];
  for (const value of raw) {
    if (typeof value !== "string") return { error: "reasoningEfforts must contain only strings" };
    if (!isDeclaredReasoningEffort(value)) { rejected.push(value); continue; }
    if (!values.includes(value)) values.push(value);
  }
  if (rejected.length > 0) {
    return { error: `unsupported reasoning effort: ${rejected.join(", ")} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
  }
  // Canonical order: the catalog writes supported_reasoning_levels in input order and the
  // fallback default picks the first entry, so a caller-chosen order must not leak through.
  return { values: canonicalizeReasoningEfforts(values) };
}

/** Default effort must be a ladder member that the declared ladder actually includes. */
function readDefaultReasoningEffort(raw: unknown, efforts: string[] | undefined): { value?: string; error?: string } {
  if (raw === undefined) return {};
  if (raw === null) return { value: undefined };
  if (typeof raw !== "string" || !isDeclaredReasoningEffort(raw)) {
    return { error: "defaultReasoningEffort must be one of: none, minimal, low, medium, high, xhigh, max, ultra" };
  }
  if (efforts === undefined || efforts.length === 0) {
    return { error: "defaultReasoningEffort requires a non-empty reasoningEfforts ladder" };
  }
  if (!efforts.includes(raw)) {
    return { error: `defaultReasoningEffort "${raw}" is not in the declared reasoningEfforts ladder` };
  }
  return { value: raw };
}
import type { CatalogModel } from "../../codex/catalog";
import { accountBoundNativeOpenAiSlugsBySelector, catalogModelSlug, configuredNativeAliasSlugs, disabledNativeSlugs, invalidateCodexModelsCache, nativeModelRows, shouldIncludeAccountBoundNativeOpenAi, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
import { CatalogGatherBusyError } from "../../codex/catalog/provider-fetch";
import { clearModelCache, getProviderLiveModelCount } from "../../codex/model-cache";
import { NATIVE_OPENAI_MODELS } from "../../codex/catalog/native-models";

import {
  DEFAULT_SUBAGENT_MODELS,
  codexAutoStartEnabled,
  hasOwnProvider,
  isValidProviderName,
  modelDisplayNamesConfigError,
  multiAgentGuidanceEnabled,
  providerBaseUrlConfigError,
  providerHeadersConfigError,
  providerModelCostsConfigError,
  sanitizeModelCostsForDisplay,
  saveConfigPreservingClaudeCode,
} from "../../config";
import {
  clearLoginState,
  getLoginStatus,
  isPublicOAuthProvider,
  listOAuthProviders,
  startLoginFlow,
  submitManualLoginCode,
  upsertOAuthProvider,
} from "../../oauth";
import { removeCredential } from "../../oauth/store";
import { providerDestinationResolvedError } from "../../lib/destination-policy";
import { redactSecretString } from "../../lib/redact";
import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
import { deriveProviderPresets } from "../../providers/derive";
import { providerCodexAccountMode } from "../../providers/registry";
import { encodedModelIdCollides, routedSlug, slugEquals } from "../../providers/slug-codec";
import { knownModelIdsForProvider } from "../../router";
import { effectiveModelAliases, MODEL_ALIAS_PATTERN } from "../../providers/default-aliases";
import { isValidModelDiscoveryModelId } from "../../providers/model-discovery-limits";
import { commitProviderPatch } from "./provider-patch-transaction";
import { ConfigWritePublishedError } from "../../config/persist-unlocked";
import type { CatalogDisposition } from "../../codex/convergence-types";
import { comboPublicModelId } from "../../combos/types";
import { COMBO_NAMESPACE, comboDisabledModelSelectors, comboModelId, preservesPhysicalComboProvider } from "../../combos";
import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
import { clearThreadAccountMap } from "../../codex/routing";
import { primeCodexPoolQuotas } from "../../codex/auth-api";
import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
import { resolveCodexHomeDir } from "../../codex/home";
import { readUsageEntries } from "../../usage/log";
import { getUsageDebugLogEntries } from "../../usage/debug";
import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
import { getProviderRegistryEntry } from "../../providers/registry";
import { getDebugLogEntries } from "../../lib/debug-log-buffer";
import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort } from "../../reasoning-effort";
import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
import {
  clearDebugSettings,
  clearDebugSetting,
  getDebugSettings,
  setDebugSettings,
  type DebugFlag,
} from "../../lib/debug-settings";
import type { ModelCapabilities, OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig, ProviderCostOverlay } from "../../types";
import { drainAndShutdown } from "../lifecycle";
import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
import type { PersistedUsageAttempt } from "../../usage/log";
import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO, corsHeaders } from "../auth-cors";
import { applySystemEnvToggle } from "../system-env";
import {
  ClientPathError,
  EXPORT_CLIENTS,
  EXPORT_CLIENT_IDS,
  OPENCODE_PROVIDER_ID,
  buildClientConfigText,
  isExportClientId,
  opencodeProxyBaseUrl,
} from "../../clients/config-export";
import type {
  ExportClientId,
  ExportModel,
  OpencodeGeneratedConfig,
  PiGeneratedConfig,
} from "../../clients/config-export";

import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
import type { ManagementContext } from "./context";
import { effectiveModelReasoningEfforts, inheritedModelReasoningEfforts, listManagementModelRows, loadExportModels } from "./model-rows";
import { initialModelSelectionPending } from "../../providers/initial-model-selection";
import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
import {
  hasModelPreset,
  markModelPresetDiverged,
  materializeModelPreset,
  modelPresetFor,
} from "../../providers/model-presets";

/**
 * Counts read back off the SERIALIZED document rather than recomputed from the input rows.
 * `modelsWithoutLimits` drives a GUI line claiming "these models ship without limits", so it
 * has to describe the bytes the user actually receives — a parallel reimplementation of the
 * core's "authoritative context window" rule would be free to drift from it silently.
 */
function summarizeExportedModels(client: ExportClientId, document: unknown): { modelCount: number; modelsWithoutLimits: number } {
  // Each client counts its own document shape. The previous branch assumed
  // "anything that is not OpenCode must be Pi", which silently misread the
  // moment a third client existed.
  return EXPORT_CLIENTS[client].summarize(document);
}

export async function handleModelRoutes(ctx: ManagementContext): Promise<Response | null> {
  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
  // A handler persists the exact config object passed in. Production defaults to
  // the real store; tests that pass an in-memory fixture inject a no-op/spy. Do not
  // bypass this seam with a dynamic config import — doing so replaced a user's
  // ~/.opencodex/config.json with the `existing-uuid` test fixture.
  const persistConfig = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
  const convergeVisibleCatalogs = async () => {
    const catalogRefresh = await convergeCodexCatalog();
    const refresh = deps.refreshOwnedCatalogIntegrations
      ?? (await import("../../integrations/catalog-refresh")).refreshOwnedCatalogIntegrations;
    const clientIntegrations = await refresh({
      config,
      port: Number(url.port) || config.port,
      models: () => loadExportModels(config),
    });
    return { catalogRefresh, clientIntegrations };
  };

  if (url.pathname === "/api/model-discovery" && req.method === "GET") {
    const providers = Object.fromEntries(Object.entries(config.providers).map(([name, provider]) => [
      name, provider.newModelPolicy ?? "inherit",
    ]));
    const recentArrivals = Object.fromEntries(Object.entries(config.modelDiscovery?.recentArrivals ?? {}).map(([name, rows]) => [
      name,
      rows.map(row => ({
        ...row,
        state: (config.disabledModels ?? []).some(slug => slugEquals(slug, name, row.id))
          ? "auto-disabled" : "enabled",
      })),
    ]));
    const baselineCounts = Object.fromEntries(Object.entries(config.modelDiscovery?.knownModels ?? {}).map(([name, baseline]) => [
      name, baseline.ids.length,
    ]));
    return jsonResponse({
      policy: config.modelDiscovery?.newModelPolicy ?? "on", providers, recentArrivals, baselineCounts,
    });
  }

  if (url.pathname === "/api/model-discovery" && req.method === "PUT") {
    let body: { policy?: unknown; provider?: unknown };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (body.policy !== "on" && body.policy !== "off") return jsonResponse({ error: "policy must be on or off" }, 400);
    const provider = typeof body.provider === "string" && body.provider.trim() ? body.provider.trim() : null;
    let baselineBootstrapped = false;
    if (provider) {
      if (!hasOwnProvider(config.providers, provider)) return jsonResponse({ error: "unknown provider" }, 404);
      config.providers[provider].newModelPolicy = body.policy;
    } else {
      const wasAbsent = config.modelDiscovery?.newModelPolicy === undefined;
      config.modelDiscovery ??= {};
      config.modelDiscovery.newModelPolicy = body.policy;
      if (body.policy === "off" && wasAbsent) {
        const models = await fetchAllModels(config);
        const known = config.modelDiscovery.knownModels ??= {};
        const at = new Date().toISOString();
        for (const name of Object.keys(config.providers)) {
          known[name] ??= { ids: [...new Set(models.filter(m => m.provider === name).map(m => m.id))].sort(), removed: [], updatedAt: at };
        }
        baselineBootstrapped = true;
      }
    }
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ok: true, policy: body.policy, provider, ...(baselineBootstrapped ? { baselineBootstrapped } : {}), catalogRefresh });
  }

  if (url.pathname === "/api/model-discovery/acknowledge" && req.method === "POST") {
    let body: { provider?: unknown; ids?: unknown };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    const provider = typeof body.provider === "string" ? body.provider.trim() : "";
    if (!provider || !Array.isArray(body.ids) || body.ids.some(id => typeof id !== "string")) {
      return jsonResponse({ error: "provider and string ids are required" }, 400);
    }
    const acknowledged = new Set(body.ids as string[]);
    const recent = config.modelDiscovery?.recentArrivals;
    if (recent?.[provider]) recent[provider] = recent[provider].filter(row => !acknowledged.has(row.id));
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ok: true, provider, acknowledged: [...acknowledged], catalogRefresh });
  }

  if (url.pathname === "/api/aliases" && req.method === "GET") {
    const providers: Record<string, string> = {};
    const models: Record<string, Record<string, { alias: string; source: "user" | "builtin"; stale?: boolean }>> = {};
    for (const [name, provider] of Object.entries(config.providers)) {
      if (provider.alias) providers[name] = provider.alias;
      const known = knownModelIdsForProvider(name, provider, config);
      const knownSet = new Set(known);
      const rows: Record<string, { alias: string; source: "user" | "builtin"; stale?: boolean }> = {};
      for (const [id, value] of effectiveModelAliases(config, provider, new Set([...known, ...Object.keys(provider.modelAliases ?? {})]))) {
        rows[id] = { ...value, ...(!knownSet.has(id) ? { stale: true } : {}) };
      }
      if (Object.keys(rows).length) models[name] = rows;
    }
    return jsonResponse({ providers, models, defaults: {
      global: config.defaultModelAliases ?? false,
      providers: Object.fromEntries(Object.entries(config.providers).filter(([, p]) => p.defaultAliases !== undefined).map(([n, p]) => [n, p.defaultAliases])),
    } });
  }

  const providerAliasMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/alias$/);
  if (providerAliasMatch && req.method === "PUT") {
    const name = decodeURIComponent(providerAliasMatch[1]!);
    // `keys` is not a provider name: `/api/providers/keys/alias` is the API-KEY POOL's rename
    // endpoint (oauth-account-routes.ts), and model routes are dispatched BEFORE it. Without
    // this guard the alias route matched `name = "keys"`, found no such provider, and returned
    // 404 for every key-pool rename.
    if (name === "keys") return null;
    const provider = config.providers[name];
    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
    let raw: unknown;
    try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(raw) || (raw.alias !== null && typeof raw.alias !== "string")) return jsonResponse({ error: "alias must be a string or null" }, 400, req, config);
    const alias = typeof raw.alias === "string" ? raw.alias.trim() : null;
    if (alias && !isValidProviderName(alias)) return jsonResponse({ error: "invalid provider alias" }, 400, req, config);
    const lower = alias?.toLowerCase();
    const collision = lower && Object.entries(config.providers).find(([other, p]) =>
      other !== name && (other.toLowerCase() === lower || p.alias?.toLowerCase() === lower));
    const comboCollision = lower && Object.entries(config.combos ?? {}).find(([, combo]) => comboPublicModelId("", combo).toLowerCase() === lower);
    const accountCollision = lower && Object.keys(config.codexAccountNamespaces ?? {}).find(value => value.toLowerCase() === lower);
    if (collision || comboCollision || accountCollision) return jsonResponse({ error: `alias conflicts with '${collision?.[0] ?? comboCollision?.[0] ?? accountCollision}'` }, 409, req, config);
    if (alias) provider.alias = alias; else delete provider.alias;
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ok: true, provider: name, alias, catalogRefresh });
  }

  const modelAliasMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/model-aliases$/);
  if (modelAliasMatch && req.method === "PUT") {
    const name = decodeURIComponent(modelAliasMatch[1]!);
    if (name === "keys") return null;
    const provider = config.providers[name];
    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
    let raw: unknown;
    try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(raw) || (raw.set !== undefined && !isPlainRecord(raw.set)) || (raw.remove !== undefined && !Array.isArray(raw.remove))) return jsonResponse({ error: "invalid model alias update" }, 400, req, config);
    const next = { ...(provider.modelAliases ?? {}) };
    for (const id of (raw.remove ?? []) as unknown[]) if (typeof id === "string") delete next[id];
    const conflicts: Array<{ alias: string; heldBy: string }> = [];
    const known = knownModelIdsForProvider(name, provider, config);
    for (const [id, value] of Object.entries((raw.set ?? {}) as Record<string, unknown>)) {
      if (typeof value !== "string" || !MODEL_ALIAS_PATTERN.test(value)) return jsonResponse({ error: `invalid model alias for '${id}'` }, 400, req, config);
      const lower = value.toLowerCase();
      const heldBy = Object.entries(next).find(([other, alias]) => other !== id && alias.toLowerCase() === lower)?.[0]
        ?? known.find(native => native.toLowerCase() === lower)
        ?? Object.entries(config.combos ?? {}).find(([, combo]) => comboPublicModelId("", combo).toLowerCase() === lower)?.[0];
      if (heldBy || /^(?:gpt-|o1-|o3-|o4-|codex-)/i.test(value)) conflicts.push({ alias: value, heldBy: heldBy ?? "native OpenAI family" });
      else next[id] = value;
    }
    if (conflicts.length) return jsonResponse({ error: "model alias collision", conflicts }, 409, req, config);
    provider.modelAliases = next;
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ok: true, aliases: next, catalogRefresh });
  }

  if (url.pathname === "/api/default-aliases" && req.method === "PUT") {
    let raw: unknown;
    try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(raw) || typeof raw.enabled !== "boolean" || (raw.provider !== undefined && typeof raw.provider !== "string")) return jsonResponse({ error: "enabled must be boolean" }, 400, req, config);
    if (typeof raw.provider === "string") {
      const provider = config.providers[raw.provider];
      if (!provider) return jsonResponse({ error: `provider '${raw.provider}' not found` }, 404, req, config);
      provider.defaultAliases = raw.enabled;
    } else config.defaultModelAliases = raw.enabled;
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ok: true, catalogRefresh });
  }

  if (url.pathname === "/api/catalog" && req.method === "GET") {
    // Shared with GET|HEAD /v1/catalog (#809) so both planes emit identical bytes.
    const { serializePersistedCatalog, persistedCodexVersion } = await import("../catalog-download");
    const serialized = await serializePersistedCatalog();
    // No size ceiling here on purpose: this route's behavior predates the shared serializer
    // and a 2,000-model catalog (~92 MB, within the supported bound) must keep working.
    if (serialized.body === null) return jsonResponse({ error: "catalog not found" }, 404, req, config);
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      ...corsHeaders(req, config),
    };
    if (serialized.etag) headers.ETag = serialized.etag;
    const version = await persistedCodexVersion();
    if (version) headers["x-opencodex-codex-version"] = version;
    return new Response(serialized.body, { status: 200, headers });
  }

  if (url.pathname === "/api/models" && req.method === "GET") {
    return jsonResponse(await listManagementModelRows(config));
  }

  const modelCostsMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/model-costs$/);
  if (modelCostsMatch && (req.method === "GET" || req.method === "PUT")) {
    let name: string;
    try { name = decodeURIComponent(modelCostsMatch[1]!); } catch { return jsonResponse({ error: "invalid provider encoding" }, 400); }
    if (!hasOwnProvider(config.providers, name)) {
      return jsonResponse({ error: "provider not found" }, 404, req, config);
    }
    if (req.method === "GET") {
      const provider = config.providers[name]!;
      return jsonResponse({ provider: name, modelCosts: sanitizeModelCostsForDisplay(provider.modelCosts) ?? {} }, 200, req, config);
    }
    let body: unknown;
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(body) || !isValidModelDiscoveryModelId(body.modelId)
      || !Object.hasOwn(body, "cost")
      || Object.keys(body).some(key => key !== "modelId" && key !== "cost")) {
      return jsonResponse({ error: "only a valid modelId and cost object or null are allowed" }, 400, req, config);
    }
    const modelId = body.modelId;
    if (redactSecretString(modelId) !== modelId) {
      return jsonResponse({ error: "modelId cannot be displayed safely" }, 400, req, config);
    }
    const submitted = { [modelId]: body.cost };
    const validationError = body.cost === null ? null : providerModelCostsConfigError(submitted);
    if (validationError) return jsonResponse({ error: validationError }, 400, req, config);
    // Copy only validated rate fields; never echo a secret-shaped model key that the
    // shared display boundary suppresses. Model IDs remain exact, including slashes.
    const cost = body.cost === null ? null : sanitizeModelCostsForDisplay(submitted)?.[modelId];
    if (cost === undefined) return jsonResponse({ error: "modelId cannot be displayed safely" }, 400, req, config);

    // Body parsing yields: a concurrent provider PATCH can replace the row or remove it.
    // Resolve ownership again and keep the merge/save synchronous on the current row.
    if (!hasOwnProvider(config.providers, name)) {
      return jsonResponse({ error: "provider not found" }, 404, req, config);
    }
    const provider = config.providers[name]!;
    const hadModelCosts = Object.hasOwn(provider, "modelCosts");
    const previousModelCosts = provider.modelCosts;
    const nextModelCosts = Object.assign(
      Object.create(null) as Record<string, ProviderCostOverlay>,
      previousModelCosts ?? {},
    );
    if (cost === null) delete nextModelCosts[modelId];
    else nextModelCosts[modelId] = cost;
    const mergedError = providerModelCostsConfigError(nextModelCosts);
    if (mergedError) return jsonResponse({ error: mergedError }, 400, req, config);
    // Keep even an empty map until persistence reconciles individual model keys.
    // Deleting the property would also delete prices another writer added on disk.
    provider.modelCosts = nextModelCosts;
    try {
      // The persistence owner refreshes usage overlays after its atomic write.
      // Price-only edits do not change routing or require catalog convergence.
      persistConfig(config);
    } catch (error) {
      if (hadModelCosts) provider.modelCosts = previousModelCosts;
      else delete provider.modelCosts;
      throw error;
    }
    return jsonResponse({ ok: true, provider: name, modelId, cost }, 200, req, config);
  }

  const displayNameMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/model-display-names$/);
  if (displayNameMatch && req.method === "PUT") {
    let name: string;
    try { name = decodeURIComponent(displayNameMatch[1]!); } catch { return jsonResponse({ error: "invalid provider encoding" }, 400); }
    if (name === "keys") return null;
    if (!hasOwnProvider(config.providers, name)) {
      return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
    }
    let body: unknown;
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(body) || typeof body.modelId !== "string"
      || (body.displayName !== null && typeof body.displayName !== "string")) {
      return jsonResponse({ error: "modelId and displayName string or null are required" }, 400, req, config);
    }
    const modelId = body.modelId.trim();
    const displayName = typeof body.displayName === "string" ? body.displayName.trim() : null;
    if (!isValidModelDiscoveryModelId(modelId)) {
      return jsonResponse({ error: "modelId must be a valid model id" }, 400, req, config);
    }
    const validationError = displayName === null
      ? null
      : modelDisplayNamesConfigError({ [modelId]: displayName });
    if (validationError) return jsonResponse({ error: validationError }, 400, req, config);

    const provider = config.providers[name]!;
    const hadDisplayNames = Object.hasOwn(provider, "modelDisplayNames");
    const previousDisplayNames = provider.modelDisplayNames;
    const nextDisplayNames = Object.assign(
      Object.create(null) as Record<string, string>,
      previousDisplayNames ?? {},
    );
    if (displayName === null) delete nextDisplayNames[modelId];
    else nextDisplayNames[modelId] = displayName;
    const mergedValidationError = modelDisplayNamesConfigError(nextDisplayNames);
    if (mergedValidationError) return jsonResponse({ error: mergedValidationError }, 400, req, config);
    if (Object.keys(nextDisplayNames).length > 0) provider.modelDisplayNames = nextDisplayNames;
    else delete provider.modelDisplayNames;

    try {
      persistConfig(config);
    } catch (error) {
      if (hadDisplayNames) provider.modelDisplayNames = previousDisplayNames;
      else delete provider.modelDisplayNames;
      throw error;
    }
    clearModelCache(name);
    const catalogRefresh = await convergeCodexCatalog();
    const storedDisplayName = provider.modelDisplayNames?.[modelId] ?? null;
    if (catalogRefresh.status === "failed") {
      return jsonResponse({
        error: "model display name saved but catalog refresh failed",
        saved: true,
        provider: name,
        modelId,
        displayNameOverride: storedDisplayName,
        catalogRefresh,
      }, 503, req, config);
    }
    const row = (await listManagementModelRows(config)).find(candidate => (
      candidate.native !== true
      && candidate.custom !== true
      && candidate.provider === name
      && candidate.id === modelId
    ));
    return jsonResponse({
      ok: true,
      provider: name,
      modelId,
      displayName: row?.displayName ?? storedDisplayName ?? routedSlug(name, modelId),
      displayNameOverride: storedDisplayName,
      displayNameSource: row?.displayNameSource ?? (storedDisplayName ? "operator" : "fallback"),
      catalogRefresh,
    });
  }

  /**
   * Client config document for OpenCode / Pi, built from the SAME function `ocx export`
   * calls, so the bytes a user downloads here and the bytes they pipe from the CLI cannot
   * disagree. Read-only: this route never writes the user's client config.
   */
  if (url.pathname === "/api/client-config" && req.method === "GET") {
    const requested = url.searchParams.get("client")?.trim() ?? "";
    if (!isExportClientId(requested)) {
      return jsonResponse(
        { error: `client must be one of: ${EXPORT_CLIENT_IDS.join(", ")}` },
        400,
        req,
        config,
      );
    }
    const spec = EXPORT_CLIENTS[requested];
    // Resolved before the catalog load on purpose. A refused override is a
    // property of the request, not of the catalog: validating it afterwards
    // let a busy or failing catalog answer 503 first, so a user with a
    // relative override never saw the message that says how to fix it — and
    // the route did the enumeration work anyway for input it was going to
    // reject.
    let destination: string;
    try {
      destination = spec.destination(process.env);
    } catch (error) {
      // A client's own environment override can name a path the resolver
      // refuses — a relative value, which this process and the client would
      // resolve against different working directories. That is a
      // user-correctable configuration error, not a server fault, so it leaves
      // this boundary as a bounded 400 instead of escaping handleManagementAPI
      // as a generic 500 and stripping the message that says how to fix it.
      // `integrations/state.ts` and `integrations/writer.ts` already catch the
      // same error on their paths; this route was the one that did not.
      if (!(error instanceof ClientPathError)) throw error;
      return jsonResponse({ error: error.message }, 400, req, config);
    }
    if ((requested === "raycast" || requested === "droid") && shouldInjectApiAuthHeader(config)) {
      return jsonResponse({
        error: `${requested === "droid" ? "Factory Droid" : "Raycast"} export requires an unauthenticated loopback destination; this listener requires an admission header the client cannot supply.`,
        reason: "non_loopback",
      }, 400, req, config);
    }
    const baseUrl = opencodeProxyBaseUrl(Number(url.port) || config.port, config.hostname, config);
    let models: ExportModel[];
    try {
      // The ONE loader every export surface uses. It carries the visibility
      // filter with it, so this route and the integration routes cannot end up
      // telling a client about different models.
      models = await loadExportModels(config);
    } catch (error) {
      // A partial or empty `models` block reads as a valid config while offering nothing,
      // so a catalog failure is surfaced as unavailable rather than serialized. The
      // catalog-busy error keeps its own 503 from handleManagementAPI.
      if (error instanceof CatalogGatherBusyError) throw error;
      return jsonResponse(
        { error: `model catalog unavailable: ${error instanceof Error ? error.message : String(error)}` },
        503,
        req,
        config,
      );
    }
    const built = buildClientConfigText(requested, {
      baseUrl,
      models,
      config,
    });
    const document = built.document;
    return jsonResponse({
      client: spec.id,
      filename: spec.filename,
      destination,
      apiKeyEnv: spec.apiKeyEnv,
      exportHint: spec.exportHint,
      // The client's own format and the exact bytes for it. The GUI previously
      // re-serialized `config` as JSON, which is wrong for four of the six
      // clients; `mediaType` also drives the download blob.
      format: built.format,
      mediaType: built.mediaType,
      text: built.text,
      ...summarizeExportedModels(requested, document),
      config: document,
    }, 200, req, config);
  }

  // Enable/disable models: which routed models Codex sees. PUT hides them from the catalog +
  // /v1/models and invalidates Codex's 5-min models cache so it applies on the next turn.
  if (url.pathname === "/api/disabled-models" && req.method === "PUT") {
    let body: { models?: unknown };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    const disabled = Array.isArray(body.models) ? body.models.filter((m): m is string => typeof m === "string") : [];
    config.disabledModels = disabled;
    persistConfig(config);
    return jsonResponse({ ok: true, disabled, ...await convergeVisibleCatalogs() });
  }

  // One user-facing visibility switch spans two persisted filters: a provider allowlist and the
  // shared blocklist. Keep the update atomic so an interrupted request cannot expose a half-applied
  // state. Native rows only use the blocklist; routed/custom rows also join a non-empty allowlist.
  if (url.pathname === "/api/model-visibility" && req.method === "PUT") {
    let parsedBody: unknown;
    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid model visibility request" }, 400);
    const body = parsedBody;
    const scope = body.scope === "models" || body.scope === "provider" ? body.scope : null;
    const provider = typeof body.provider === "string" ? body.provider.trim() : "";
    if (!scope || !provider || !isValidProviderName(provider) || typeof body.enabled !== "boolean" || !Array.isArray(body.targets)) {
      return jsonResponse({ error: "invalid model visibility request" }, 400);
    }

    const providerConfig = hasOwnProvider(config.providers, provider) ? config.providers[provider] : undefined;
    if (initialModelSelectionPending(providerConfig)) {
      return jsonResponse({ error: "Initial model discovery is pending. Refresh the model list and retry.", code: "initial_model_selection_pending" }, 409);
    }
    const isVirtualComboNamespace = provider === COMBO_NAMESPACE && !preservesPhysicalComboProvider(config);
    if (!providerConfig && provider !== "openai" && !isVirtualComboNamespace) {
      return jsonResponse({ error: "unknown model visibility provider" }, 400);
    }
    const accountNativeQualified = shouldIncludeAccountBoundNativeOpenAi(config)
      ? [...accountBoundNativeOpenAiSlugsBySelector(config).entries()].flatMap(([selector, slugs]) =>
        slugs.filter(slug => !nativeModelRows(config).some(row => row.slug === slug)).map(slug => `${selector}/${slug}`))
      : [];
    const supportedNative = new Set([
      ...nativeModelRows(config).map(row => row.slug),
      ...accountNativeQualified,
      // A model suppressed by an unconfirmed entitlement roster is absent from
      // nativeModelRows, so validating against those rows alone rejected a model this build
      // knows perfectly well and left the operator with no way to clear its disable key
      // (#2886). Accepting the target says "this build knows this model", not "this account
      // may use it" — visibility only writes disabledModels and routing stays gated.
      ...NATIVE_OPENAI_MODELS,
    ]);
    const targets: Array<{ id: string; native: boolean }> = [];
    const seen = new Set<string>();
    for (const value of body.targets) {
      if (!isPlainRecord(value) || typeof value.id !== "string" || (value.native !== undefined && typeof value.native !== "boolean")) {
        return jsonResponse({ error: "invalid model visibility target" }, 400);
      }
      const id = value.id.trim();
      const native = value.native === true;
      const configuredOpenAiCustom = provider === "openai" && !native && providerConfig
        && (config.customModels ?? []).some(model => model.provider === provider && model.modelId === id);
      if (!id || (native && (provider !== "openai" || !supportedNative.has(id)))
        || (provider === "openai" && !native && !configuredOpenAiCustom)) {
        return jsonResponse({ error: "invalid model visibility target" }, 400);
      }
      const key = `${native ? "native" : "routed"}:${id}`;
      if (!seen.has(key)) {
        seen.add(key);
        targets.push({ id, native });
      }
    }
    if (targets.length === 0) return jsonResponse({ error: "model visibility targets required" }, 400);

    const knownComboSelectors = new Set(
      Object.entries(config.combos ?? {}).flatMap(([id, combo]) => (
        comboDisabledModelSelectors(id, combo)
      )),
    );
    const targetComboSelectors = new Map<string, Set<string>>();
    if (isVirtualComboNamespace) {
      for (const target of targets) {
        const combo = config.combos && Object.hasOwn(config.combos, target.id) ? config.combos[target.id] : undefined;
        if (!combo) return jsonResponse({ error: "invalid model visibility target" }, 400);
        targetComboSelectors.set(target.id, new Set(comboDisabledModelSelectors(target.id, combo)));
      }
    }
    const matchesTarget = (stored: string, target: { id: string; native: boolean }) => target.native
      ? stored === target.id
      : isVirtualComboNamespace
        ? targetComboSelectors.get(target.id)!.has(stored)
        : slugEquals(stored, provider, target.id);

    let disabled = [...new Set(config.disabledModels ?? [])];
    if (body.enabled) {
      if (scope === "provider") {
        if (providerConfig && !isVirtualComboNamespace) delete providerConfig.selectedModels;
        if (isVirtualComboNamespace) {
          disabled = disabled.filter(stored => !knownComboSelectors.has(stored));
        } else {
          const nativeIds = provider === "openai"
            ? disabledNativeSlugs({ disabledModels: disabled })
            : new Set<string>();
          const accountNativeIds = provider === "openai" ? new Set(accountNativeQualified) : new Set<string>();
          const nativeAliasSlugs = provider === "openai"
            ? configuredNativeAliasSlugs(config)
            : new Set<string>();
          disabled = disabled.filter(stored => (
            knownComboSelectors.has(stored)
            || nativeAliasSlugs.has(stored)
            || (!stored.startsWith(`${provider}/`) && !nativeIds.has(stored) && !accountNativeIds.has(stored))
          ));
        }
      } else {
        if (!isVirtualComboNamespace && providerConfig?.selectedModels && providerConfig.selectedModels.length > 0) {
          const additions = targets.filter(target => !target.native).map(target => target.id);
          providerConfig.selectedModels = [...new Set([...providerConfig.selectedModels, ...additions])];
        }
        disabled = disabled.filter(stored => !targets.some(target => matchesTarget(stored, target)));
        const arrivals = config.modelDiscovery?.recentArrivals?.[provider];
        if (arrivals) config.modelDiscovery!.recentArrivals![provider] = arrivals.filter(row => (
          !targets.some(target => !target.native && target.id === row.id)
        ));
      }
    } else {
      for (const target of targets) {
        const canonical = target.native
          ? target.id
          : isVirtualComboNamespace
            ? comboModelId(target.id)
            : routedSlug(provider, target.id);
        const alreadyDisabled = disabled.some(stored => matchesTarget(stored, target));
        if (!alreadyDisabled) disabled.push(canonical);
      }
    }

    config.disabledModels = disabled;
    persistConfig(config);
    return jsonResponse({ ok: true, scope, provider, enabled: body.enabled, disabled, ...await convergeVisibleCatalogs() });
  }

  if (url.pathname === "/api/custom-models" && req.method === "GET") {
    return jsonResponse(config.customModels ?? []);
  }

  /*
   * Per-model overrides for a routed row, addressed by provider + upstream model id.
   *
   * Deliberately not a custom model. A custom model is a row the operator declares; this edits
   * facts about a row that already exists, through the provider-level per-model maps the runtime
   * already reads. Creating a custom model to change one field would replace the row's identity
   * and its discovery provenance, which is the opposite of what an edit means.
   *
   * Every field is optional and `null` CLEARS the declaration rather than writing a default: that
   * is what hands the fact back to the registry, the catalog and the provider, instead of pinning
   * today's answer as an override that silently outlives the data it came from.
   *
   * Display name is not here on purpose. The row already has a dedicated editor for it
   * (PUT /api/providers/{provider}/model-display-names) with its own provenance display; a second
   * control writing the same key is two statements that can drift, and this endpoint's job is the
   * capability axes nothing else edits.
   */
  if (url.pathname === "/api/model-settings" && req.method === "PUT") {
    let parsedBody: unknown;
    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid model settings request" }, 400);
    const body = parsedBody;
    for (const key of Object.keys(body)) {
      if (!["provider", "modelId", "contextWindow", "inputModalities", "reasoningEfforts", "defaultReasoningEffort"].includes(key)) {
        return jsonResponse({ error: `unknown model settings field: ${key}` }, 400);
      }
    }
    const provider = typeof body.provider === "string" ? body.provider.trim() : "";
    const modelId = typeof body.modelId === "string" ? body.modelId : "";
    if (!provider || !modelId) return jsonResponse({ error: "provider and modelId are required" }, 400);
    if (!isValidModelDiscoveryModelId(modelId) || ["__proto__", "constructor", "prototype"].includes(modelId)) {
      return jsonResponse({ error: "modelId must be an exact non-reserved model id" }, 400);
    }
    if (!isValidProviderName(provider) || !hasOwnProvider(config.providers, provider)) {
      return jsonResponse({ error: "unknown model settings provider" }, 400);
    }
    // "openai" is the native passthrough lane and "combo" is a synthetic row: neither is a
    // provider whose per-model maps the runtime consults for these facts.
    if (provider === "openai" || provider === "combo") {
      return jsonResponse({ error: "model settings are only available for routed providers" }, 400);
    }

    const providerConfig = { ...config.providers[provider] };
    const storedLadder = providerConfig.modelReasoningEfforts?.[modelId];

    let contextWindow: number | null | undefined;
    if (body.contextWindow !== undefined) {
      if (body.contextWindow === null) contextWindow = null;
      else if (typeof body.contextWindow === "number" && Number.isSafeInteger(body.contextWindow) && body.contextWindow > 0) {
        contextWindow = body.contextWindow;
      } else return jsonResponse({ error: "contextWindow must be a positive safe integer or null" }, 400);
    }
    let modalities: DeclaredInputModality[] | null | undefined;
    if (body.inputModalities !== undefined) {
      if (body.inputModalities === null) modalities = null;
      else {
        const parsed = readInputModalities(body.inputModalities);
        if (parsed.error) return jsonResponse({ error: parsed.error }, 400);
        // An empty array means "cleared", exactly like null: a model that accepts no modality at
        // all is not a state this surface can express, and storing [] would advertise text-only
        // through a value the catalog then has to special-case.
        // Deduplicated before the unchanged check and before the write: `["text","text"]` against
        // a stored `["text","image"]` passes a length test and an every-member test, so the
        // operator's edit would be dropped as a no-op; when it did differ, the duplicates would be
        // persisted as submitted.
        const unique = parsed.values ? [...new Set(parsed.values)] : [];
        modalities = unique.length > 0 ? unique : null;
      }
    }
    let ladder: string[] | null | undefined;
    if (body.reasoningEfforts !== undefined) {
      if (body.reasoningEfforts === null) ladder = null;
      else {
        const parsed = readReasoningEfforts(body.reasoningEfforts);
        if (parsed.error) return jsonResponse({ error: parsed.error }, 400);
        ladder = parsed.values ?? [];
      }
    }
    /*
     * Validated against the ladder this write leaves behind, not the one that happens to be stored:
     * a caller replacing both in one request must not be rejected for the value it is replacing, and
     * a default-only request must be judged against the ladder the model actually resolves — which
     * may be the provider-level, registry, native or catalog one, not only a per-model entry.
     * `inheritedModelReasoningEfforts` is what the clear case leaves behind: it removes the model's
     * entry from a copy before resolving, so it answers the post-write state.
     */
    const resultingLadder = ladder === undefined
      ? (Array.isArray(storedLadder) ? storedLadder : effectiveModelReasoningEfforts(config, provider, modelId))
      : (ladder ?? inheritedModelReasoningEfforts(config, provider, modelId));
    const defaultEffort = readDefaultReasoningEffort(body.defaultReasoningEffort, resultingLadder);
    if (defaultEffort.error) return jsonResponse({ error: defaultEffort.error }, 400);

    let changed = false;
    const writePerModel = (
      key: "modelContextWindows" | "modelReasoningEfforts" | "modelDefaultReasoningEfforts",
      value: unknown,
    ) => {
      if (value === undefined) return;
      const bag = providerConfig as unknown as Record<string, unknown>;
      const record: Record<string, unknown> = Object.assign(Object.create(null), (bag[key] as Record<string, unknown> | undefined) ?? {});
      const present = Object.prototype.hasOwnProperty.call(record, modelId);
      if (value === null) {
        if (!present) return;
        delete record[modelId];
        changed = true;
      } else {
        if (present && JSON.stringify(record[modelId]) === JSON.stringify(value)) return;
        record[modelId] = value;
        changed = true;
      }
      // An emptied map is removed rather than left as {}. The maps are optional config fields, and
      // an empty one is indistinguishable from a configured-but-blank state to every reader.
      if (Object.keys(record).length === 0) delete bag[key];
      else bag[key] = record;
    };
    writePerModel("modelContextWindows", contextWindow);
    writePerModel("modelReasoningEfforts", ladder);
    if (body.defaultReasoningEffort !== undefined) {
      writePerModel("modelDefaultReasoningEfforts", defaultEffort.value === undefined ? null : defaultEffort.value);
    } else if (ladder !== undefined) {
      /*
       * A ladder write can strand a stored default that the model can no longer select, and the
       * catalog would then publish a default outside its own ladder. The caller said nothing about
       * the default, so only one that cannot survive is cleared. With `ladder === null` the override
       * is gone and the ladder to test against is the inherited one — read from the config after the
       * write, which no longer carries the removed entry.
       */
      const storedDefault = providerConfig.modelDefaultReasoningEfforts?.[modelId];
      const nextConfig = { ...config, providers: { ...config.providers, [provider]: providerConfig } };
      const effectiveLadder = ladder ?? effectiveModelReasoningEfforts(nextConfig, provider, modelId);
      if (typeof storedDefault === "string" && !(effectiveLadder ?? []).includes(storedDefault)) {
        writePerModel("modelDefaultReasoningEfforts", null);
      }
    }
    if (modalities !== undefined) {
      const capabilities = Object.assign(Object.create(null), providerConfig.modelCapabilities ?? {}) as NonNullable<typeof providerConfig.modelCapabilities>;
      const row = { ...(capabilities[modelId] ?? {}) };
      const declared = Array.isArray(row.inputModalities) ? [...row.inputModalities] : undefined;
      const unchanged = modalities === null
        ? declared === undefined
        : declared !== undefined
          && declared.length === modalities.length
          && modalities.every(modality => declared.includes(modality));
      if (!unchanged) {
        changed = true;
        if (modalities === null) delete row.inputModalities;
        else row.inputModalities = modalities;
        if (Object.keys(row).length === 0) delete capabilities[modelId];
        else capabilities[modelId] = row;
        if (Object.keys(capabilities).length === 0) delete providerConfig.modelCapabilities;
        else providerConfig.modelCapabilities = capabilities;
      }
      /*
       * The legacy `modelInputModalities` record is the fallback `declaredModelInputModalities` and the
       * router read once the capability entry is gone. A clear that left its exact entry behind would
       * report "restored" while the old declaration stayed in force. Only the exact key is removed: a
       * family or case-folded key covers other models too, and stays a provider-level declaration.
       */
      const legacy = providerConfig.modelInputModalities;
      if (modalities === null && legacy && Object.hasOwn(legacy, modelId)) {
        const next: Record<string, string[]> = Object.assign(Object.create(null), legacy);
        delete next[modelId];
        changed = true;
        if (Object.keys(next).length === 0) delete providerConfig.modelInputModalities;
        else providerConfig.modelInputModalities = next;
      }
    }

    const hasOverrides = [providerConfig.modelContextWindows, providerConfig.modelReasoningEfforts,
      providerConfig.modelDefaultReasoningEfforts, providerConfig.modelInputModalities]
      .some(map => map !== undefined && Object.hasOwn(map, modelId))
      || providerConfig.modelCapabilities?.[modelId]?.inputModalities !== undefined;
    const state = {
      ok: true as const,
      provider,
      modelId,
      hasOverrides,
      contextWindow: providerConfig.modelContextWindows?.[modelId] ?? null,
      inputModalities: providerConfig.modelCapabilities?.[modelId]?.inputModalities ?? null,
      reasoningEfforts: providerConfig.modelReasoningEfforts?.[modelId] ?? null,
      defaultReasoningEffort: providerConfig.modelDefaultReasoningEfforts?.[modelId] ?? null,
    };
    // A no-op can still retain stored declarations; `hasOverrides` reports that independently.
    if (!changed) return jsonResponse({ ...state, changed: false, saved: false,
      catalogRefresh: { status: "skipped", reason: "not-requested", retryable: false } });
    let publicationError = false;
    try {
      commitProviderPatch(config, () => { config.providers[provider] = providerConfig; }, persistConfig);
    } catch (error) {
      if (!(error instanceof ConfigWritePublishedError)) {
        return jsonResponse({ error: "model settings could not be saved" }, 500);
      }
      publicationError = true;
    }
    /*
     * Drop this provider's live `/models` cache before converging.
     *
     * The gather bakes the resolved hints into the rows it caches, and on a cache hit it re-applies
     * the config through `clampObservedModelLimits`, where a configured window may only LOWER the
     * observed one. A raised or cleared override would therefore keep reading back the previous
     * answer for the whole TTL, and a cleared modality or ladder would keep the baked one. Clearing
     * the entry is what makes the save visible on the next read, the same reason
     * `PUT /api/provider-context-caps` clears it per affected provider.
     */
    clearModelCache(provider);
    let catalogRefresh: CatalogDisposition;
    if (publicationError) catalogRefresh = { status: "skipped", reason: "not-requested", retryable: true };
    else {
      try { catalogRefresh = await convergeCodexCatalog(); }
      catch { catalogRefresh = { status: "failed", reason: "internal", phase: "gather", retryable: true, partialWrite: false }; }
    }
    return jsonResponse({ ...state, changed: true, saved: true, catalogRefresh });
  }

  if (url.pathname === "/api/custom-models" && req.method === "POST") {
    let parsedBody: unknown;
    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid JSON body" }, 400);
    const body = parsedBody;
    const provider = typeof body.provider === "string" ? body.provider.trim() : "";
    const modelId = typeof body.modelId === "string" ? body.modelId.trim() : "";
    if (!provider || !modelId) return jsonResponse({ error: "provider and modelId are required" }, 400);
    if (!isValidProviderName(provider)) return jsonResponse({ error: "invalid provider name" }, 400);
    if (!hasOwnProvider(config.providers, provider)) return jsonResponse({ error: "provider not configured" }, 404);
    const displayName = typeof body.displayName === "string" && body.displayName.trim() ? body.displayName.trim() : undefined;
    if (displayName?.includes("/")) return jsonResponse({ error: "displayName must not contain /" }, 400);
    const contextWindow = typeof body.contextWindow === "number" && body.contextWindow > 0 ? Math.floor(body.contextWindow) : undefined;
    const modalities = readInputModalities(body.inputModalities);
    if (modalities.error) return jsonResponse({ error: modalities.error }, 400);
    const inputModalities = modalities.values;
    const reasoning = readReasoningEfforts(body.reasoningEfforts);
    if (reasoning.error) return jsonResponse({ error: reasoning.error }, 400);
    const defaultEffort = readDefaultReasoningEffort(body.defaultReasoningEffort, reasoning.values);
    if (defaultEffort.error) return jsonResponse({ error: defaultEffort.error }, 400);
    const existing = config.customModels ?? [];
    const newSlug = routedSlug(provider, modelId);
    if (existing.some(cm => routedSlug(cm.provider, cm.modelId) === newSlug)) {
      return jsonResponse({ error: "duplicate model" }, 409);
    }
    const known = knownModelIdsForProvider(provider, config.providers[provider], config);
    if (encodedModelIdCollides(modelId, known)) {
      return jsonResponse({ error: "ambiguous model id" }, 409);
    }
    const entry: OcxCustomModel = {
      id: randomUUID(),
      provider,
      modelId,
      ...(displayName ? { displayName } : {}),
      ...(contextWindow ? { contextWindow } : {}),
      ...(inputModalities && inputModalities.length > 0 ? { inputModalities } : {}),
      ...(reasoning.values !== undefined ? { reasoningEfforts: reasoning.values } : {}),
      ...(defaultEffort.value ? { defaultReasoningEffort: defaultEffort.value } : {}),
      addedAt: new Date().toISOString(),
    };
    config.customModels = [...existing, entry];
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ...entry, catalogRefresh }, 201);
  }

  const customPutMatch = url.pathname.match(/^\/api\/custom-models\/([^/]+)$/);
  if (customPutMatch && req.method === "PUT") {
    let id: string;
    try { id = decodeURIComponent(customPutMatch[1]); } catch { return jsonResponse({ error: "invalid id encoding" }, 400); }
    let parsedBody: unknown;
    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid JSON body" }, 400);
    const body = parsedBody;
    const list = config.customModels ?? [];
    const idx = list.findIndex(cm => cm.id === id);
    if (idx === -1) return jsonResponse({ error: "not found" }, 404);
    const cm = { ...list[idx] };
    if (typeof body.modelId === "string" && body.modelId.trim()) {
      cm.modelId = body.modelId.trim();
    }
    if (body.displayName !== undefined) {
      const dn = typeof body.displayName === "string" ? body.displayName.trim() : "";
      if (dn.includes("/")) return jsonResponse({ error: "displayName must not contain /" }, 400);
      cm.displayName = dn || undefined;
    }
    if (body.contextWindow !== undefined) {
      cm.contextWindow = typeof body.contextWindow === "number" && body.contextWindow > 0 ? Math.floor(body.contextWindow) : undefined;
    }
    if (body.inputModalities !== undefined) {
      const edited = readInputModalities(body.inputModalities);
      if (edited.error) return jsonResponse({ error: edited.error }, 400);
      cm.inputModalities = edited.values && edited.values.length > 0 ? edited.values : undefined;
    }
    // `null` clears the stored ladder back to "inherit from the provider row"; `[]` stays
    // stored as an explicit "no reasoning" override. The default effort rides along and is
    // validated against the ladder the row ends up with.
    if (body.reasoningEfforts !== undefined) {
      if (body.reasoningEfforts === null) {
        cm.reasoningEfforts = undefined;
      } else {
        const edited = readReasoningEfforts(body.reasoningEfforts);
        if (edited.error) return jsonResponse({ error: edited.error }, 400);
        cm.reasoningEfforts = edited.values;
      }
    }
    if (body.defaultReasoningEffort !== undefined) {
      const edited = readDefaultReasoningEffort(body.defaultReasoningEffort, cm.reasoningEfforts);
      if (edited.error) return jsonResponse({ error: edited.error }, 400);
      cm.defaultReasoningEffort = edited.value;
    }
    // Mirror of the POST invariant: a default only survives as a member of the final ladder.
    // Without this, a ladder shrink/clear on a row that was created with a default leaves a
    // stale default that re-applies itself onto the inherited ladder in the generated catalog
    // (the GUI toggle-off path sends only reasoningEfforts, never the default).
    if (cm.defaultReasoningEffort !== undefined) {
      const ladder = cm.reasoningEfforts;
      if (!ladder || ladder.length === 0 || !ladder.includes(cm.defaultReasoningEffort)) {
        cm.defaultReasoningEffort = undefined;
      }
    }
    const updatedSlug = routedSlug(cm.provider, cm.modelId);
    if (list.some((other, i) => i !== idx && routedSlug(other.provider, other.modelId) === updatedSlug)) {
      return jsonResponse({ error: "duplicate model" }, 409);
    }
    const known = knownModelIdsForProvider(cm.provider, config.providers[cm.provider], {
      customModels: list.filter((_, i) => i !== idx),
    });
    if (encodedModelIdCollides(cm.modelId, known)) {
      return jsonResponse({ error: "ambiguous model id" }, 409);
    }
    list[idx] = cm;
    config.customModels = list;
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ...cm, catalogRefresh });
  }

  const customDelMatch = url.pathname.match(/^\/api\/custom-models\/([^/]+)$/);
  if (customDelMatch && req.method === "DELETE") {
    let id: string;
    try { id = decodeURIComponent(customDelMatch[1]); } catch { return jsonResponse({ error: "invalid id encoding" }, 400); }
    const list = config.customModels ?? [];
    const idx = list.findIndex(cm => cm.id === id);
    if (idx === -1) return jsonResponse({ error: "not found" }, 404);
    list.splice(idx, 1);
    config.customModels = list.length > 0 ? list : undefined;
    persistConfig(config);
    const catalogRefresh = await convergeCodexCatalog();
    return jsonResponse({ ok: true, catalogRefresh });
  }

  // Per-provider catalog allowlist (issue #52): when a provider has a non-empty selectedModels list,
  // only those ids ship to Codex's catalog / /v1/models. GET returns the CURRENT selection plus the
  // FULL available set per provider (unfiltered — the picker needs everything to choose from).
  if (url.pathname === "/api/selected-models" && req.method === "GET") {
    const models = await fetchAllModels(config);
    const available: Record<string, string[]> = {};
    for (const m of models) (available[m.provider] ??= []).push(m.id);
    const selected: Record<string, string[]> = {};
    // Live-catalog provenance. The GUI cannot infer this by subtracting known custom ids: an id
    // that is both custom and discovered would make a real live catalog look custom-only.
    const liveModelCounts: Record<string, number> = {};
    for (const [name, prov] of Object.entries(config.providers)) {
      if (Array.isArray(prov.selectedModels) && prov.selectedModels.length > 0) selected[name] = [...prov.selectedModels];
      const liveCount = getProviderLiveModelCount(name);
      if (liveCount !== undefined) liveModelCounts[name] = liveCount;
    }
    return jsonResponse({ selected, available, liveModelCounts });
  }
  if (url.pathname === "/api/model-presets" && req.method === "GET") {
    // Preview without applying: rules evaluated against the CURRENT catalog, so the count the
    // user sees is the count they would get.
    const models = await fetchAllModels(config);
    const byProvider = new Map<string, string[]>();
    for (const m of models) {
      const ids = byProvider.get(m.provider) ?? [];
      ids.push(m.id);
      byProvider.set(m.provider, ids);
    }
    const providers: Record<string, unknown> = {};
    for (const [name, prov] of Object.entries(config.providers)) {
      const preset = modelPresetFor(name);
      if (!preset) continue;
      const catalogIds = byProvider.get(name) ?? [];
      const presetIds = materializeModelPreset(name, catalogIds);
      providers[name] = {
        mode: prov.modelPreset?.mode ?? "all",
        ...(prov.modelPreset?.appliedVersion !== undefined
          ? { appliedVersion: prov.modelPreset.appliedVersion }
          : {}),
        availableVersion: preset.version,
        presetIds,
        presetCount: presetIds.length,
        totalCount: catalogIds.length,
        ...(prov.modelPreset?.fallback ? { fallback: prov.modelPreset.fallback } : {}),
      };
    }
    return jsonResponse({ providers });
  }
  if (url.pathname === "/api/model-presets" && req.method === "PUT") {
    let body: { provider?: unknown; mode?: unknown };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    const provider = typeof body.provider === "string" ? body.provider : "";
    if (!provider || !hasOwnProvider(config.providers, provider)) {
      return jsonResponse({ error: "unknown provider" }, provider ? 404 : 400);
    }
    const mode = body.mode;
    if (mode !== "preset" && mode !== "all" && mode !== "custom") {
      return jsonResponse({ error: "mode must be preset, all, or custom" }, 400);
    }
    if (mode === "preset" && !hasModelPreset(provider)) {
      return jsonResponse({ error: `no model preset is shipped for provider '${provider}'` }, 400);
    }
    const target = config.providers[provider];
    if (initialModelSelectionPending(target)) {
      return jsonResponse({ error: "Initial model discovery is pending. Refresh the model list and retry.", code: "initial_model_selection_pending" }, 409);
    }
    if (mode === "all") {
      // Same effect as today's empty-list PUT: no allowlist, no marker to reconcile.
      delete target.selectedModels;
      delete target.modelPreset;
      persistConfig(config);
      return jsonResponse({ ok: true, provider, mode, selected: [], ...await convergeVisibleCatalogs() });
    }
    if (mode === "custom") {
      // Keep whatever is selected; only the marker changes, so a user can pin their edits
      // without the proxy re-materializing over them.
      target.modelPreset = { ...(target.modelPreset ?? {}), mode: "custom" };
      persistConfig(config);
      return jsonResponse({ ok: true, provider, mode, selected: [...(target.selectedModels ?? [])] });
    }
    const models = await fetchAllModels(config);
    const catalogIds = models.filter(m => m.provider === provider).map(m => m.id);
    const presetIds = materializeModelPreset(provider, catalogIds);
    const preset = modelPresetFor(provider)!;
    if (presetIds.length === 0) {
      // NEVER write an empty allowlist from a preset: empty means ALL, so it would silently
      // un-curate instead of curating. Keep the previous selection and record the fallback so
      // the next convergence can retry.
      target.modelPreset = {
        mode: "all",
        appliedVersion: preset.version,
        appliedAt: new Date().toISOString(),
        fallback: "preset-empty",
      };
      persistConfig(config);
      return jsonResponse({
        ok: true,
        provider,
        mode: "all",
        fallback: "preset-empty",
        selected: [...(target.selectedModels ?? [])],
      });
    }
    target.selectedModels = presetIds;
    target.modelPreset = {
      mode: "preset",
      appliedVersion: preset.version,
      appliedAt: new Date().toISOString(),
    };
    persistConfig(config);
    return jsonResponse({
      ok: true,
      provider,
      mode: "preset",
      appliedVersion: preset.version,
      selected: presetIds,
      ...await convergeVisibleCatalogs(),
    });
  }
  if (url.pathname === "/api/selected-models" && req.method === "PUT") {
    let body: { provider?: unknown; models?: unknown };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    const provider = typeof body.provider === "string" ? body.provider : "";
    if (!provider || !hasOwnProvider(config.providers, provider)) {
      return jsonResponse({ error: "unknown provider" }, provider ? 404 : 400);
    }
    if (initialModelSelectionPending(config.providers[provider])) {
      return jsonResponse({ error: "Initial model discovery is pending. Refresh the model list and retry.", code: "initial_model_selection_pending" }, 409);
    }
    const models = Array.isArray(body.models)
      ? [...new Set(body.models.filter((m): m is string => typeof m === "string"))]
      : [];
    // Empty list clears the allowlist (provider reverts to exposing all models).
    if (models.length > 0) config.providers[provider].selectedModels = models;
    else delete config.providers[provider].selectedModels;
    // Divergence is detected at the WRITE path, not by diffing (#2465): a user edit while the
    // provider is in preset mode makes the selection theirs, and the proxy must never
    // re-materialize over it afterwards.
    markModelPresetDiverged(config.providers[provider]);
    persistConfig(config);
    return jsonResponse({ ok: true, provider, selected: models, ...await convergeVisibleCatalogs() });
  }
  return null;
}