@yansigit/opencodex 2.31.0

package/src/server/management/api-access.ts

@@ -0,0 +1,141 @@
+import type { OcxConfig } from "../../types";
+import { probeHostname } from "../proxy-liveness";
+
+export interface ApiAccessEndpoints {
+  baseUrl: string;
+  responsesEndpoint: string;
+  chatCompletionsEndpoint: string;
+  messagesEndpoint: string;
+  modelsEndpoint: string;
+  claudeCodeEnabled: boolean;
+  /** Back-compat alias for older GUI clients. */
+  endpoint: string;
+}
+
+export type BuildApiAccessEndpointsOptions = {
+  /** Full request URL (preferred when the bind host is a wildcard). */
+  requestUrl?: string | URL | null;
+  /** Raw `Host` header from the inbound request. */
+  requestHost?: string | null;
+  /** Raw `Origin` header from the inbound request. */
+  requestOrigin?: string | null;
+};
+
+function isWildcardBindHost(hostname: string | undefined): boolean {
+  const trimmed = (hostname ?? "").trim();
+  return !trimmed || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]";
+}
+
+/** Bracket bare IPv6 literals for URL authority composition. */
+export function formatAuthorityHost(hostname: string): string {
+  const trimmed = hostname.trim();
+  if (!trimmed) return "127.0.0.1";
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
+  return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
+}
+
+function hostnameFromAuthority(authority: string): string | null {
+  const raw = authority.trim();
+  if (!raw) return null;
+  if (raw.startsWith("[")) {
+    const end = raw.indexOf("]");
+    if (end > 0) return raw.slice(1, end) || null;
+    return null;
+  }
+  // Host headers for IPv6 are bracketed; treat multi-colon values as unusable.
+  if (raw.includes(":") && raw.split(":").length > 2) return null;
+  const colon = raw.lastIndexOf(":");
+  if (colon > 0 && /^\d+$/.test(raw.slice(colon + 1))) {
+    return raw.slice(0, colon) || null;
+  }
+  return raw;
+}
+
+function originBaseUrl(raw: string): string | null {
+  try {
+    const url = new URL(raw);
+    if (!url.hostname || isWildcardBindHost(url.hostname)) return null;
+    return `${url.protocol}//${url.host}/v1`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Prefer the client's request host/origin when the proxy is bound to a wildcard.
+ * Falls back to loopback only when no usable request context is available.
+ */
+export function resolveApiAccessBaseUrl(
+  config: Pick<OcxConfig, "hostname" | "port">,
+  opts: BuildApiAccessEndpointsOptions = {},
+): string {
+  const port = config.port ?? 10100;
+
+  if (!isWildcardBindHost(config.hostname)) {
+    return `http://${probeHostname(config.hostname)}:${port}/v1`;
+  }
+
+  const fromOrigin = opts.requestOrigin ? originBaseUrl(opts.requestOrigin) : null;
+  if (fromOrigin) return fromOrigin;
+
+  if (opts.requestUrl) {
+    try {
+      const url = typeof opts.requestUrl === "string" ? new URL(opts.requestUrl) : opts.requestUrl;
+      if (url.hostname && !isWildcardBindHost(url.hostname)) {
+        return `${url.protocol}//${url.host}/v1`;
+      }
+    } catch {
+      /* ignore malformed request URL */
+    }
+  }
+
+  const hostHeader = opts.requestHost?.trim();
+  if (hostHeader) {
+    const hostname = hostnameFromAuthority(hostHeader);
+    if (hostname && !isWildcardBindHost(hostname)) {
+      // Preserve an explicit port from the Host header; otherwise use the bind port.
+      const hasPort = hostHeader.startsWith("[")
+        ? /\]:\d+$/.test(hostHeader)
+        : /:\d+$/.test(hostHeader) && hostHeader.split(":").length === 2;
+      const authority = hasPort
+        ? (hostHeader.startsWith("[") ? hostHeader : hostHeader)
+        : `${formatAuthorityHost(hostname)}:${port}`;
+      return `http://${authority}/v1`;
+    }
+  }
+
+  return `http://127.0.0.1:${port}/v1`;
+}
+
+/** @deprecated Prefer resolveApiAccessBaseUrl; retained for focused host-format tests. */
+export function resolveApiAccessDisplayHost(
+  configHostname: string | undefined,
+  opts: BuildApiAccessEndpointsOptions = {},
+): string {
+  if (!isWildcardBindHost(configHostname)) {
+    return probeHostname(configHostname);
+  }
+  try {
+    return new URL(resolveApiAccessBaseUrl({ hostname: configHostname, port: 10100 }, opts)).hostname
+      || "127.0.0.1";
+  } catch {
+    return "127.0.0.1";
+  }
+}
+
+export function buildApiAccessEndpoints(
+  config: OcxConfig,
+  opts: BuildApiAccessEndpointsOptions = {},
+): ApiAccessEndpoints {
+  const baseUrl = resolveApiAccessBaseUrl(config, opts);
+  const responsesEndpoint = `${baseUrl}/responses`;
+  return {
+    baseUrl,
+    responsesEndpoint,
+    chatCompletionsEndpoint: `${baseUrl}/chat/completions`,
+    messagesEndpoint: `${baseUrl}/messages`,
+    modelsEndpoint: `${baseUrl}/models`,
+    claudeCodeEnabled: config.claudeCode?.enabled !== false,
+    endpoint: responsesEndpoint,
+  };
+}

package/src/server/management/api-key-usage.ts

@@ -0,0 +1,193 @@
+import {
+  currentUsageLogRevision,
+  readUsageSnapshotForManagement,
+  usageLogIdentityKey,
+  type PersistedUsageEntry,
+} from "../../usage/log";
+
+/**
+ * Per-key usage as the API tab renders it.
+ *
+ * A discriminated union rather than numbers with a flag beside them: when two
+ * config entries share an id there IS no per-key total, and an optional marker
+ * next to `requests7d: 7` invites a consumer to render the 7 anyway.
+ */
+export type ApiKeyUsage =
+  | { ambiguous: true }
+  | { ambiguous?: false; requests7d: number; totalRequests: number; lastUsedAt?: string };
+
+export interface ApiKeyUsageSnapshot {
+  rollup: Map<string, ApiKeyUsage>;
+  historyTruncated?: true;
+  /**
+   * Earliest row carrying a recognized `admissionKind`. A property of the DATA
+   * SET, not of a key, so it is singular and lives beside the map: it is what
+   * lets the GUI tell "this key was used zero times" from "nothing is
+   * attributable yet". Keyed on the kind rather than on `apiKeyId`, because an
+   * environment or loopback row is attributed traffic with no configured key.
+   */
+  attributionSince?: string;
+}
+
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * A timestamp we can actually do date arithmetic with.
+ *
+ * `usage.jsonl` is hand-editable and JSON permits numbers outside the Date
+ * range: `1e309` survives normalization and then throws `RangeError` from
+ * `toISOString()`. Since the caller catches to protect key management, one bad
+ * row would have zeroed the rollup for EVERY key — active keys reported as
+ * unused is exactly the wrong answer to hand someone deciding what to delete.
+ */
+function usableTimestamp(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Number.isNaN(new Date(value).getTime()) ? null : value;
+}
+
+/**
+ * Pure: one pass over an already-read snapshot, so it is unit-testable without
+ * touching the filesystem.
+ *
+ * Rows are bucketed only when `admissionKind === "configured"`. Keying on
+ * `apiKeyId` alone would let a hand-edited entry whose id is `loopback` absorb
+ * traffic it never admitted.
+ */
+export function rollupApiKeyUsage(
+  entries: PersistedUsageEntry[],
+  configuredIds: string[],
+  now: number = Date.now(),
+): ApiKeyUsageSnapshot {
+  const duplicated = new Set<string>();
+  const seen = new Set<string>();
+  for (const id of configuredIds) {
+    if (seen.has(id)) duplicated.add(id);
+    seen.add(id);
+  }
+
+  const totals = new Map<string, { requests7d: number; totalRequests: number; lastUsedAt?: string }>();
+  let attributionSince: number | undefined;
+  const cutoff = now - SEVEN_DAYS_MS;
+
+  for (const entry of entries) {
+    if (!entry.admissionKind) continue;
+    const timestamp = usableTimestamp(entry.timestamp);
+    if (timestamp !== null && (attributionSince === undefined || timestamp < attributionSince)) {
+      attributionSince = timestamp;
+    }
+    if (entry.admissionKind !== "configured" || !entry.apiKeyId) continue;
+
+    const bucket = totals.get(entry.apiKeyId) ?? { requests7d: 0, totalRequests: 0 };
+    // The request happened even if its clock reading is unusable, so it still
+    // counts toward the total; only the time-based fields are skipped.
+    bucket.totalRequests += 1;
+    if (timestamp !== null) {
+      if (timestamp >= cutoff) bucket.requests7d += 1;
+      const iso = new Date(timestamp).toISOString();
+      if (!bucket.lastUsedAt || iso > bucket.lastUsedAt) bucket.lastUsedAt = iso;
+    }
+    totals.set(entry.apiKeyId, bucket);
+  }
+
+  const rollup = new Map<string, ApiKeyUsage>();
+  for (const id of configuredIds) {
+    if (duplicated.has(id)) {
+      rollup.set(id, { ambiguous: true });
+      continue;
+    }
+    rollup.set(id, totals.get(id) ?? { requests7d: 0, totalRequests: 0 });
+  }
+  return {
+    rollup,
+    ...(attributionSince !== undefined ? { attributionSince: new Date(attributionSince).toISOString() } : {}),
+  };
+}
+
+/**
+ * Rollup cache keyed by the exact usage-log revision, mirroring the /api/usage
+ * summary cache. Without it, every key-list read reparses an append-only log
+ * that only ever grows — and the GUI fetches this route on mount and after every
+ * create/rename/delete. The compact rollup is a handful of counters per key, so
+ * caching it costs nothing; a new row changes the revision and invalidates it.
+ */
+let rollupCache: { revisionKey: string; expiresAt: number; lastSeenSize?: number; snapshot: ApiKeyUsageSnapshot } | null = null;
+
+/**
+ * The rollup is a function of the log AND of the clock: a request ages out of
+ * the seven-day window with no write to bump the file revision, so a purely
+ * revision-keyed entry would report a stale `requests7d` indefinitely.
+ *
+ * A minute is the whole rule. Deriving the exact next-transition instant would
+ * mean tracking the OLDEST counted request per key, which the compact rollup
+ * deliberately does not keep — and a count that can be at most 60s stale is
+ * already far tighter than the window it describes.
+ */
+const ROLLUP_CACHE_TTL_MS = 60_000;
+
+/** Test seam: the cache is module state and would otherwise leak between cases. */
+export function clearApiKeyUsageCacheForTests(): void {
+  rollupCache = null;
+}
+
+/**
+ * Reads the durable usage snapshot the way /api/usage does, then rolls it up.
+ *
+ * Never throws: an unreadable snapshot yields empty rollups and no
+ * `attributionSince`. Key management working matters more than usage numbers
+ * being present, and the GUI already treats an absent field as "no data".
+ */
+export function cacheApiKeyUsageFromSnapshot(
+  entries: PersistedUsageEntry[],
+  configuredIds: string[],
+  identityKey: string,
+  lastSeenSize: number,
+  truncated: boolean,
+  maxReadBytes: number | undefined,
+  now: number = Date.now(),
+): ApiKeyUsageSnapshot {
+  const idsKey = JSON.stringify([configuredIds, maxReadBytes]);
+  const rolled = {
+    ...rollupApiKeyUsage(entries, configuredIds, now),
+    ...(truncated ? { historyTruncated: true as const } : {}),
+  };
+  rollupCache = {
+    revisionKey: `${identityKey}|${idsKey}`,
+    expiresAt: now + ROLLUP_CACHE_TTL_MS,
+    lastSeenSize,
+    snapshot: rolled,
+  };
+  return rolled;
+}
+
+export async function readApiKeyUsageRollup(configuredIds: string[], maxReadBytes?: number): Promise<ApiKeyUsageSnapshot> {
+  // JSON rather than a joined string: ids are only validated as non-empty
+  // strings, so `["a\0b","c"]` and `["a","b\0c"]` join to the same value and one
+  // config could be served the other's cached rollup.
+  const idsKey = JSON.stringify([configuredIds, maxReadBytes]);
+  const now = Date.now();
+  try {
+    const observed = currentUsageLogRevision();
+    const observedKey = `${usageLogIdentityKey(observed)}|${idsKey}`;
+    const observedSize = observed?.size ?? 0;
+    if (rollupCache?.revisionKey === observedKey && now < rollupCache.expiresAt && observedSize >= (rollupCache.lastSeenSize ?? 0)) {
+      return rollupCache.snapshot;
+    }
+
+    const snapshot = await readUsageSnapshotForManagement(maxReadBytes);
+    const rolled = {
+      ...rollupApiKeyUsage(snapshot.entries, configuredIds, now),
+      ...(snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated ? { historyTruncated: true as const } : {}),
+    };
+    rollupCache = {
+      revisionKey: `${usageLogIdentityKey(snapshot.revision)}|${idsKey}`,
+      expiresAt: now + ROLLUP_CACHE_TTL_MS,
+      lastSeenSize: snapshot.revision?.size ?? 0,
+      snapshot: rolled,
+    };
+    return rolled;
+  } catch {
+    const rollup = new Map<string, ApiKeyUsage>();
+    for (const id of configuredIds) rollup.set(id, { requests7d: 0, totalRequests: 0 });
+    return { rollup };
+  }
+}

package/src/server/management/body.ts

@@ -0,0 +1,41 @@
+import type { OcxConfig } from "../../types";
+import { jsonResponse } from "../auth-cors";
+import {
+  DecompressedBodyTooLargeError,
+  readBoundedJsonRequestBody,
+} from "../request-decompress";
+
+export const MANAGEMENT_JSON_BODY_MAX_BYTES = 4 * 1024 * 1024;
+
+export function readManagementJsonBody<T = unknown>(req: Request): Promise<T> {
+  return readBoundedJsonRequestBody(req, MANAGEMENT_JSON_BODY_MAX_BYTES) as Promise<T>;
+}
+
+export function readOptionalManagementJsonBody<T = unknown>(req: Request): Promise<T> {
+  return readBoundedJsonRequestBody(req, MANAGEMENT_JSON_BODY_MAX_BYTES, undefined, {
+    emptyBodyFallback: {},
+  }) as Promise<T>;
+}
+
+export function managementBodyTooLargeResponse(
+  error: unknown,
+  req: Request,
+  config: OcxConfig,
+): Response | null {
+  return error instanceof DecompressedBodyTooLargeError
+    ? jsonResponse({ error: "request body too large" }, 413, req, config)
+    : null;
+}
+
+export function rethrowManagementBodyTooLarge(error: unknown): void {
+  if (error instanceof DecompressedBodyTooLargeError) throw error;
+}
+
+export async function readManagementJsonBodyOr<T>(req: Request, fallback: T): Promise<unknown | T> {
+  try {
+    return await readManagementJsonBody(req);
+  } catch (error) {
+    rethrowManagementBodyTooLarge(error);
+    return fallback;
+  }
+}

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

@@ -0,0 +1,263 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { CatalogModel } from "../../codex/catalog";
+import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import {
+  DEFAULT_SUBAGENT_MODELS,
+  codexAutoStartEnabled,
+  hasOwnProvider,
+  isValidProviderName,
+  multiAgentGuidanceEnabled,
+  providerBaseUrlConfigError,
+  providerHeadersConfigError,
+  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 { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
+import { deriveProviderPresets } from "../../providers/derive";
+import { providerCodexAccountMode } from "../../providers/registry";
+import { routedSlug, slugEquals } from "../../providers/slug-codec";
+import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
+import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+import {
+  CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR,
+  codexAccountNamespaceForModel,
+} from "../../codex/account-namespace-match";
+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 { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
+import {
+  clearDebugSettings,
+  clearDebugSetting,
+  getDebugSettings,
+  setDebugSettings,
+  type DebugFlag,
+} from "../../lib/debug-settings";
+import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
+import { drainAndShutdown } from "../lifecycle";
+import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
+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 } from "../auth-cors";
+import { applySystemEnvToggle } from "../system-env";
+
+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 { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+
+
+/** Management wire shape: omit default imageInput "auto" (persist/response sparse). */
+function sparseComboConfig<T extends { imageInput?: "auto" | "disabled" }>(combo: T): Omit<T, "imageInput"> & { imageInput?: "disabled" } {
+  const { imageInput, ...rest } = combo;
+  return {
+    ...rest,
+    ...(imageInput === "disabled" ? { imageInput: "disabled" as const } : {}),
+  };
+}
+
+export async function handleComboRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
+
+  if (url.pathname === "/api/combos" && req.method === "GET") {
+    const { comboPublicModelId, getCombo, listComboIds } = await import("../../combos");
+    return jsonResponse({ combos: listComboIds(config).map(id => {
+      const combo = getCombo(config, id)!;
+      return {
+        id,
+        model: comboPublicModelId(id, combo),
+        ...sparseComboConfig(combo),
+      };
+    }) });
+  }
+
+  if (url.pathname === "/api/combos" && req.method === "PUT") {
+    let rawBody: unknown;
+    try { rawBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(rawBody)) {
+      return jsonResponse({ error: "request body must be an object" }, 400);
+    }
+    const body = rawBody;
+    if (typeof body.id !== "string" || !body.id.trim()) {
+      return jsonResponse({ error: "id is required and must be a string" }, 400);
+    }
+    const id = body.id.trim();
+    let renameFrom: string | undefined;
+    if (body.renameFrom !== undefined) {
+      if (typeof body.renameFrom !== "string" || !body.renameFrom.trim()) {
+        return jsonResponse({ error: "renameFrom must be a non-empty string" }, 400);
+      }
+      renameFrom = body.renameFrom.trim();
+      if (renameFrom === id) {
+        return jsonResponse({ error: "renameFrom must differ from id" }, 400);
+      }
+      if (!Object.hasOwn(config.combos ?? {}, renameFrom)) {
+        return jsonResponse({ error: `combo "${renameFrom}" does not exist` }, 400);
+      }
+      if (Object.hasOwn(config.combos ?? {}, id)) {
+        return jsonResponse({ error: `combo "${id}" already exists` }, 400);
+      }
+    }
+    const {
+      clearComboSelectionState,
+      clearComboTargetCooldowns,
+      comboConfigError,
+      comboDisabledModelId,
+      comboDisabledModelSelectors,
+      comboModelId,
+      comboPublicModelId,
+      normalizeComboConfig,
+    } = await import("../../combos");
+    const error = comboConfigError(id, body.combo, config.providers, {
+      requireEnabledTarget: true,
+      combos: config.combos,
+      excludeComboId: renameFrom ?? id,
+    });
+    if (error) return jsonResponse({ error }, 400);
+    const normalized = normalizeComboConfig(body.combo as import("../../types").OcxComboConfig);
+    // Persist only non-default identity/capability fields so config stays sparse.
+    const {
+      alias: normalizedAlias,
+      nativeAlias: normalizedNativeAlias,
+      displayName: normalizedDisplayName,
+      imageInput: normalizedImageInput,
+      ...normalizedBase
+    } = normalized;
+    const stored: import("../../types").OcxComboConfig = {
+      ...normalizedBase,
+      ...(normalizedAlias ? { alias: normalizedAlias } : {}),
+      ...(normalizedNativeAlias ? { nativeAlias: true } : {}),
+      ...(normalizedDisplayName ? { displayName: normalizedDisplayName } : {}),
+      ...(normalizedImageInput === "disabled" ? { imageInput: "disabled" as const } : {}),
+    };
+    const sourceId = renameFrom ?? id;
+    const previous = config.combos?.[sourceId];
+    const oldPublicModel = previous ? comboPublicModelId(sourceId, previous) : null;
+    const newPublicModel = comboPublicModelId(id, normalized);
+    const disabledIdentityChanged = previous !== undefined && (
+      renameFrom !== undefined
+      || oldPublicModel !== newPublicModel
+      || (previous.nativeAlias === true) !== normalized.nativeAlias
+    );
+    const oldDisabledSelectors = disabledIdentityChanged
+      ? new Set(comboDisabledModelSelectors(sourceId, previous))
+      : new Set<string>();
+    const newDisabledModel = comboDisabledModelId(id, normalized);
+    if (codexAccountNamespaceForModel(config.codexAccountNamespaces, newPublicModel)) {
+      return jsonResponse({ error: CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR }, 409);
+    }
+    const nextCombos = { ...(config.combos ?? {}) };
+    if (renameFrom) delete nextCombos[renameFrom];
+    nextCombos[id] = stored;
+    config.combos = nextCombos;
+    let shouldSyncClaudeAgentDefs = false;
+    const migratedModels = new Map<string, string>();
+    if (oldPublicModel && oldPublicModel !== newPublicModel && previous?.nativeAlias !== true) {
+      migratedModels.set(oldPublicModel, newPublicModel);
+    }
+    if (renameFrom) {
+      // A bare native id is ambiguous after the alias changes. Preserve it as a native route,
+      // while the unambiguous canonical combo reference follows the renamed combo.
+      migratedModels.set(
+        comboModelId(renameFrom),
+        previous?.nativeAlias === true ? comboModelId(id) : newPublicModel,
+      );
+    }
+    if (migratedModels.size > 0) {
+      const migrateReference = (model: string): string => migratedModels.get(model) ?? model;
+      const migrateAgentReference = (model: string): string => {
+        const migrated = migrateReference(model);
+        if (migrated !== model) shouldSyncClaudeAgentDefs = true;
+        return migrated;
+      };
+      if (config.subagentModels) {
+        config.subagentModels = [...new Set(config.subagentModels.map(migrateAgentReference))];
+      }
+      if (config.subagentRoles) {
+        for (const role of config.subagentRoles) {
+          role.model = migrateAgentReference(role.model);
+        }
+      }
+      if (config.injectionModel && migratedModels.has(config.injectionModel)) {
+        config.injectionModel = migrateReference(config.injectionModel);
+      }
+      if (config.shadowCallIntercept?.model && migratedModels.has(config.shadowCallIntercept.model)) {
+        config.shadowCallIntercept = {
+          ...config.shadowCallIntercept,
+          model: migrateReference(config.shadowCallIntercept.model),
+        };
+      }
+      if (config.claudeCode) {
+        const claudeCode = { ...config.claudeCode };
+        for (const field of ["model", "smallFastModel"] as const) {
+          if (claudeCode[field]) claudeCode[field] = migrateAgentReference(claudeCode[field]);
+        }
+        if (claudeCode.tierModels) {
+          claudeCode.tierModels = Object.fromEntries(
+            Object.entries(claudeCode.tierModels).map(([tier, model]) => [tier, migrateAgentReference(model)]),
+          );
+        }
+        if (claudeCode.modelMap) {
+          claudeCode.modelMap = Object.fromEntries(
+            Object.entries(claudeCode.modelMap).map(([source, model]) => [source, migrateAgentReference(model)]),
+          );
+        }
+        config.claudeCode = claudeCode;
+      }
+    }
+    if (oldDisabledSelectors.size > 0 && config.disabledModels) {
+      config.disabledModels = [...new Set(config.disabledModels.map(model => (
+        oldDisabledSelectors.has(model) ? newDisabledModel : model
+      )))];
+    }
+    saveConfigPreservingClaudeCode(config);
+    reconcileLiveStateStores();
+    clearComboSelectionState(id);
+    clearComboTargetCooldowns(id);
+    if (renameFrom) {
+      clearComboSelectionState(renameFrom);
+      clearComboTargetCooldowns(renameFrom);
+    }
+    const catalogRefresh = await convergeCodexCatalog();
+    if (shouldSyncClaudeAgentDefs) await syncClaudeAgentDefsBestEffort();
+    // Wire shape matches persistence: omit default imageInput "auto".
+    return jsonResponse({ success: true, id, model: newPublicModel, combo: sparseComboConfig(stored), catalogRefresh });
+  }
+
+  if (url.pathname === "/api/combos" && req.method === "DELETE") {
+    const id = url.searchParams.get("id")?.trim();
+    if (!id) return jsonResponse({ error: "id query param is required" }, 400);
+    if (!Object.hasOwn(config.combos ?? {}, id)) {
+      return jsonResponse({ error: "unknown combo" }, 404);
+    }
+    const { clearComboSelectionState, clearComboTargetCooldowns } = await import("../../combos");
+    delete config.combos![id];
+    if (Object.keys(config.combos!).length === 0) delete config.combos;
+    saveConfigPreservingClaudeCode(config);
+    reconcileLiveStateStores();
+    clearComboSelectionState(id);
+    clearComboTargetCooldowns(id);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ success: true, id, catalogRefresh });
+  }
+  return null;
+}