@iislee/opencodex 2.11.0 → 2.35.0

package/src/server/management/model-routes.ts

@@ -29,8 +29,48 @@ function readInputModalities(raw: unknown): { values?: string[]; error?: string
   }
   return { values: raw as string[] };
 }
+
+/**
+ * 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 { catalogModelSlug, disabledNativeSlugs, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import { accountBoundNativeOpenAiSlugsBySelector, catalogModelSlug, configuredNativeAliasSlugs, disabledNativeSlugs, invalidateCodexModelsCache, nativeModelRows, shouldIncludeAccountBoundNativeOpenAi, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
 import { CatalogGatherBusyError } from "../../codex/catalog/provider-fetch";
 import { getProviderLiveModelCount } from "../../codex/model-cache";
 import {
@@ -57,8 +97,11 @@ import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
 import { deriveProviderPresets } from "../../providers/derive";
 import { providerCodexAccountMode } from "../../providers/registry";
-import { routedSlug, slugEquals } from "../../providers/slug-codec";
-import { COMBO_NAMESPACE, comboModelId, comboPublicModelId, preservesPhysicalComboProvider } from "../../combos";
+import { encodedModelIdCollides, routedSlug, slugEquals } from "../../providers/slug-codec";
+import { knownModelIdsForProvider } from "../../router";
+import { effectiveModelAliases, MODEL_ALIAS_PATTERN } from "../../providers/default-aliases";
+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";
@@ -71,6 +114,7 @@ import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summa
 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,
@@ -87,10 +131,11 @@ 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,
-  buildClientConfig,
+  buildClientConfigText,
   isExportClientId,
   opencodeProxyBaseUrl,
 } from "../../clients/config-export";
@@ -104,92 +149,14 @@ import type {
 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 { listManagementModelRows, loadExportModels } from "./model-rows";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
-
-/**
- * One row of the `/api/models` list. Routed rows spread a `CatalogModel`, so the shape is
- * that model plus the identity/visibility fields this boundary computes for every row
- * regardless of source. `disabled` is always present; the rest vary by row origin.
- */
-type ManagementModelRow = Partial<CatalogModel> & {
-  provider: string;
-  id: string;
-  namespaced: string;
-  disabled: boolean;
-  native?: boolean;
-  custom?: boolean;
-  customId?: string;
-};
-
-/**
- * The exact row list `/api/models` returns. Extracted so `/api/client-config` exports the
- * models the GUI's Models tab shows — including this function's `disabled` computation,
- * which the export core (src/clients/config-export.ts) deliberately does not perform.
- */
-async function listManagementModelRows(config: OcxConfig): Promise<ManagementModelRow[]> {
-  const models = await fetchAllModels(config);
-  const disabled = new Set(config.disabledModels ?? []);
-  // Native GPT passthrough rows lead (provider "openai", bare-slug namespaced ids): sourced
-  // from the static supported set so a disabled model stays listed and re-enableable.
-  const native: ManagementModelRow[] = nativeModelRows(config).map(row => ({
-    provider: "openai",
-    id: row.slug,
-    namespaced: row.slug,
-    disabled: row.disabled,
-    native: true,
-    ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
-  }));
-  const customModels: ManagementModelRow[] = (config.customModels ?? []).map(cm => {
-    const namespaced = routedSlug(cm.provider, cm.modelId);
-    return {
-      provider: cm.provider,
-      id: cm.modelId,
-      namespaced,
-      disabled: [...disabled].some(stored => slugEquals(stored, cm.provider, cm.modelId)),
-      custom: true,
-      customId: cm.id,
-      displayName: cm.displayName,
-      ...(cm.contextWindow ? { contextWindow: cm.contextWindow } : {}),
-      ...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
-    };
-  });
-  const publicModels = uniqueCatalogModelsForPublicList(models);
-  const comboNamespaced = new Set(
-    publicModels.filter(model => model.provider === "combo").map(catalogModelSlug),
-  );
-  const visibleCustomModels = customModels.filter(model => !comboNamespaced.has(model.namespaced));
-  // Custom metadata wins when a physical live/static row resolves to the same Codex-facing
-  // slug, while a combo keeps the same precedence it has in routing and /v1/models.
-  const customNamespaced = new Set(visibleCustomModels.map(c => c.namespaced));
-  const dedupedRouted = publicModels.map((m): ManagementModelRow | null => {
-    // Codex-facing slug (one "/", slug-codec); disabledModels compares tolerate both forms.
-    const namespaced = catalogModelSlug(m);
-    if (m.provider !== "combo" && customNamespaced.has(namespaced)) return null;
-    const contextCap = providerContextCap(config, m.provider);
-    return {
-      ...m,
-      namespaced,
-      disabled: [...disabled].some(stored => (
-        stored === namespaced || slugEquals(stored, m.provider, m.id)
-      )),
-      ...(contextCap !== undefined ? { contextCap, contextCapped: m.contextCapped === true } : {}),
-    };
-  }).filter((row): row is ManagementModelRow => row !== null);
-  return [...native, ...dedupedRouted, ...visibleCustomModels];
-}
-
-/** `/api/models` row → the narrower input the client-config serializers accept. */
-function toExportModel(row: ManagementModelRow): ExportModel {
-  return {
-    namespaced: row.namespaced,
-    provider: row.provider,
-    id: row.id,
-    ...(row.native ? { native: true } : {}),
-    ...(row.displayName ? { displayName: row.displayName } : {}),
-    ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
-    ...(row.inputModalities ? { inputModalities: row.inputModalities } : {}),
-  };
-}
+import {
+  hasModelPreset,
+  markModelPresetDiverged,
+  materializeModelPreset,
+  modelPresetFor,
+} from "../../providers/model-presets";
 
 /**
  * Counts read back off the SERIALIZED document rather than recomputed from the input rows.
@@ -198,23 +165,172 @@ function toExportModel(row: ManagementModelRow): ExportModel {
  * core's "authoritative context window" rule would be free to drift from it silently.
  */
 function summarizeExportedModels(client: ExportClientId, document: unknown): { modelCount: number; modelsWithoutLimits: number } {
-  if (client === "opencode") {
-    const models = (document as OpencodeGeneratedConfig).provider[OPENCODE_PROVIDER_ID].models;
-    const entries = Object.values(models);
-    return { modelCount: entries.length, modelsWithoutLimits: entries.filter(entry => entry.limit === undefined).length };
-  }
-  const models = (document as PiGeneratedConfig).providers[OPENCODE_PROVIDER_ID].models;
-  return { modelCount: models.length, modelsWithoutLimits: models.filter(entry => entry.contextWindow === undefined).length };
+  // 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, refreshCodexCatalogBestEffort, syncClaudeAgentDefsBestEffort } = ctx;
+  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;
 
+  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") {
     const { readCatalog, readCodexCatalogPath } = await import("../../codex/catalog");
     const catalog = readCatalog(readCodexCatalogPath());
@@ -249,9 +365,33 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       );
     }
     const spec = EXPORT_CLIENTS[requested];
-    let rows: ManagementModelRow[];
+    // 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 {
-      rows = await listManagementModelRows(config);
+      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);
+    }
+    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
@@ -264,21 +404,24 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
         config,
       );
     }
-    // The export core does not filter visibility — it serializes what it is given. A model the
-    // user disabled in the Models tab is absent from /v1/models, so exporting it would hand the
-    // client a selector the proxy refuses to route.
-    const models = rows.filter(row => !row.disabled).map(toExportModel);
-    const document = buildClientConfig(requested, {
+    const built = buildClientConfigText(requested, {
       baseUrl: opencodeProxyBaseUrl(Number(url.port) || config.port, config.hostname),
       models,
       config,
     });
+    const document = built.document;
     return jsonResponse({
       client: spec.id,
       filename: spec.filename,
-      destination: spec.destination(process.env),
+      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);
@@ -292,8 +435,8 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     const disabled = Array.isArray(body.models) ? body.models.filter((m): m is string => typeof m === "string") : [];
     config.disabledModels = disabled;
     persistConfig(config);
-    await refreshCodexCatalogBestEffort();
-    return jsonResponse({ ok: true, disabled });
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, disabled, catalogRefresh });
   }
 
   // One user-facing visibility switch spans two persisted filters: a provider allowlist and the
@@ -315,7 +458,14 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     if (!providerConfig && provider !== "openai" && !isVirtualComboNamespace) {
       return jsonResponse({ error: "unknown model visibility provider" }, 400);
     }
-    const supportedNative = new Set(nativeModelRows(config).map(row => row.slug));
+    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,
+    ]);
     const targets: Array<{ id: string; native: boolean }> = [];
     const seen = new Set<string>();
     for (const value of body.targets) {
@@ -336,17 +486,16 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     if (targets.length === 0) return jsonResponse({ error: "model visibility targets required" }, 400);
 
     const knownComboSelectors = new Set(
-      Object.entries(config.combos ?? {}).flatMap(([id, combo]) => [
-        comboModelId(id),
-        comboPublicModelId(id, combo),
-      ]),
+      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([comboModelId(target.id), comboPublicModelId(target.id, combo)]));
+        targetComboSelectors.set(target.id, new Set(comboDisabledModelSelectors(target.id, combo)));
       }
     }
     const matchesTarget = (stored: string, target: { id: string; native: boolean }) => target.native
@@ -365,9 +514,14 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
           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)
-            || (!stored.startsWith(`${provider}/`) && !nativeIds.has(stored))
+            || nativeAliasSlugs.has(stored)
+            || (!stored.startsWith(`${provider}/`) && !nativeIds.has(stored) && !accountNativeIds.has(stored))
           ));
         }
       } else {
@@ -376,6 +530,10 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
           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) {
@@ -391,8 +549,8 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
 
     config.disabledModels = disabled;
     persistConfig(config);
-    await refreshCodexCatalogBestEffort();
-    return jsonResponse({ ok: true, scope, provider, enabled: body.enabled, disabled });
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, scope, provider, enabled: body.enabled, disabled, catalogRefresh });
   }
 
   if (url.pathname === "/api/custom-models" && req.method === "GET") {
@@ -400,12 +558,13 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
   }
 
   if (url.pathname === "/api/custom-models" && req.method === "POST") {
-    let body: { provider?: unknown; modelId?: unknown; displayName?: unknown; contextWindow?: unknown; inputModalities?: unknown };
-    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 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 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 (modelId.includes("/")) return jsonResponse({ error: "modelId must not contain /" }, 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;
@@ -414,11 +573,19 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     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,
@@ -426,26 +593,29 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       ...(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);
-    await refreshCodexCatalogBestEffort();
-    return jsonResponse(entry, 201);
+    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 body: { displayName?: unknown; contextWindow?: unknown; inputModalities?: unknown; modelId?: unknown };
-    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 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()) {
-      if (body.modelId.includes("/")) return jsonResponse({ error: "modelId must not contain /" }, 400);
       cm.modelId = body.modelId.trim();
     }
     if (body.displayName !== undefined) {
@@ -461,15 +631,48 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       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);
-    await refreshCodexCatalogBestEffort();
-    return jsonResponse(cm);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ...cm, catalogRefresh });
   }
 
   const customDelMatch = url.pathname.match(/^\/api\/custom-models\/([^/]+)$/);
@@ -482,15 +685,24 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     list.splice(idx, 1);
     config.customModels = list.length > 0 ? list : undefined;
     persistConfig(config);
-    await refreshCodexCatalogBestEffort();
-    return jsonResponse({ ok: true });
+    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).
+  // FULL available set per provider for the management picker.
+  //
+  // `fetchAllModels` hides media-generation ids (image/video) from the Codex-facing catalog, but the
+  // Providers → Models tab must still list every id the user fetched and saved on the provider
+  // (e.g. grok2api's grok-imagine-*). Merge `providers[name].models` on top so those rows are not
+  // silently dropped after a successful refresh-models persist.
+  //
+  // Cold path: prefer cache/configured seeds so the Providers page paints in milliseconds instead
+  // of waiting on every upstream `/models` (often multi-second). When any live provider still needs
+  // a network probe, kick a background gather and set `refreshing: true` so the GUI can re-poll.
   if (url.pathname === "/api/selected-models" && req.method === "GET") {
-    const models = await fetchAllModels(config);
+    const models = await fetchAllModels(config, { preferCached: true });
     const available: Record<string, string[]> = {};
     for (const m of models) (available[m.provider] ??= []).push(m.id);
     const selected: Record<string, string[]> = {};
@@ -501,8 +713,120 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       if (Array.isArray(prov.selectedModels) && prov.selectedModels.length > 0) selected[name] = [...prov.selectedModels];
       const liveCount = getProviderLiveModelCount(name);
       if (liveCount !== undefined) liveModelCounts[name] = liveCount;
+      const configured = prov.models;
+      if (!Array.isArray(configured) || configured.length === 0) continue;
+      const bucket = available[name] ?? (available[name] = []);
+      const seen = new Set(bucket);
+      for (const id of configured) {
+        if (typeof id !== "string" || !id || seen.has(id)) continue;
+        seen.add(id);
+        bucket.push(id);
+      }
+    }
+    // Re-check after the local gather: preferCached may have kicked a background flight whose
+    // first probe already filled some caches, but `refreshing` still means "more work in flight
+    // or still needed" for the GUI re-poll loop.
+    const { catalogGatherNeedsLiveRefresh } = await import("../../codex/catalog");
+    const refreshing = catalogGatherNeedsLiveRefresh(config);
+    return jsonResponse({ selected, available, liveModelCounts, refreshing });
+  }
+  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({ selected, available, liveModelCounts });
+    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);
+    }
+    const target = config.providers[provider];
+    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: [], catalogRefresh: await convergeCodexCatalog() });
+    }
+    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 ?? [])] });
+    }
+    if (!hasModelPreset(provider)) {
+      return jsonResponse({ error: `no model preset is shipped for provider '${provider}'` }, 400);
+    }
+    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,
+      catalogRefresh: await convergeCodexCatalog(),
+    });
   }
   if (url.pathname === "/api/selected-models" && req.method === "PUT") {
     let body: { provider?: unknown; models?: unknown };
@@ -517,9 +841,13 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     // 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);
-    await refreshCodexCatalogBestEffort();
-    return jsonResponse({ ok: true, provider, selected: models });
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ok: true, provider, selected: models, catalogRefresh });
   }
   return null;
 }