@remodex/rmx 1.0.2

package/src/providers/openai-tiers.ts

@@ -0,0 +1,301 @@
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import { OPENAI_PROVIDER_TIER_VERSION } from "../types";
+
+export const OPENAI_CODEX_PROVIDER_ID = "openai";
+export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
+export const OPENAI_API_PROVIDER_ID = "openai-apikey";
+export const LEGACY_CHATGPT_PROVIDER_ID = "chatgpt";
+
+export const CODEX_FORWARD_BASE_URL = "https://chatgpt.com/backend-api/codex";
+const LEGACY_OPENAI_MULTI_PREFIX = `${LEGACY_OPENAI_MULTI_PROVIDER_ID}/`;
+
+function canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfig {
+  return {
+    adapter: "openai-responses",
+    baseUrl: CODEX_FORWARD_BASE_URL,
+    authMode: "forward",
+    codexAccountMode: mode,
+  };
+}
+
+function normalizedBaseUrl(value: string): string | undefined {
+  try {
+    const url = new URL(value.trim());
+    if (url.username || url.password || url.search || url.hash) return undefined;
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${path}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): boolean {
+  return provider.adapter === "openai-responses"
+    && provider.authMode === "forward"
+    && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
+}
+
+const OPENAI_API_BASE_URL = "https://api.openai.com/v1";
+
+/**
+ * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
+ * backend can, and so can the official OpenAI API — but an arbitrary gateway that
+ * merely speaks the Responses wire cannot, and calling it there fails compaction
+ * with an unhelpful error instead of falling back to a routed summary (#422).
+ */
+export function supportsNativeResponsesCompactEndpoint(
+  providerName: string,
+  provider: OcxProviderConfig,
+): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return providerName === OPENAI_API_PROVIDER_ID
+    && provider.adapter === "openai-responses"
+    && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
+}
+
+export interface OpenAiTierMigrationProjection {
+  config: OcxConfig;
+  changed: boolean;
+  resolvedMode: CodexAccountMode;
+  warnings: string[];
+}
+
+export class OpenAiTierMigrationCollisionError extends Error {
+  readonly providerName = LEGACY_OPENAI_MULTI_PROVIDER_ID;
+
+  constructor() {
+    super(`Reserved provider id "${LEGACY_OPENAI_MULTI_PROVIDER_ID}" is already configured with a noncanonical shape`);
+    this.name = "OpenAiTierMigrationCollisionError";
+  }
+}
+
+function managedLegacyMultiOverlay(provider: OcxProviderConfig): Pick<OcxProviderConfig, "disabled" | "selectedModels"> | null {
+  const allowed = new Set(["adapter", "authMode", "baseUrl", "disabled", "selectedModels"]);
+  if (!Object.keys(provider).every(key => allowed.has(key))) return null;
+  if (!isCanonicalOpenAiForwardProvider(provider)) return null;
+  if (provider.disabled !== undefined && typeof provider.disabled !== "boolean") return null;
+  if (provider.selectedModels !== undefined && (
+    !Array.isArray(provider.selectedModels)
+    || provider.selectedModels.some(model => typeof model !== "string")
+  )) return null;
+  return {
+    ...(provider.disabled !== undefined ? { disabled: provider.disabled } : {}),
+    ...(provider.selectedModels !== undefined ? { selectedModels: [...provider.selectedModels] } : {}),
+  };
+}
+
+function rewriteLegacyOpenAiSelectedId(value: string): string {
+  return value.startsWith(LEGACY_OPENAI_MULTI_PREFIX)
+    ? value.slice(LEGACY_OPENAI_MULTI_PREFIX.length)
+    : value;
+}
+
+function rewriteLegacyOpenAiModelList(values: string[] | undefined): string[] | undefined {
+  if (!values) return undefined;
+  return [...new Set(values.map(rewriteLegacyOpenAiSelectedId))];
+}
+
+function mergeLegacyOpenAiProviderRows(
+  openai: OcxProviderConfig | undefined,
+  legacyMulti: OcxProviderConfig | undefined,
+  mode: CodexAccountMode,
+): OcxProviderConfig {
+  const selectedModels = rewriteLegacyOpenAiModelList([
+    ...(openai?.selectedModels ?? []),
+    ...(legacyMulti?.selectedModels ?? []),
+  ]);
+  const formerRows = [openai, legacyMulti].filter((row): row is OcxProviderConfig => row !== undefined);
+  const disabled = formerRows.length > 0 && formerRows.every(row => row.disabled === true);
+  return {
+    ...canonicalCodexForwardProvider(mode),
+    ...(disabled ? { disabled: true } : {}),
+    ...(selectedModels && selectedModels.length > 0 ? { selectedModels } : {}),
+  };
+}
+
+function hasKnownLegacyOpenAiReference(config: OcxConfig): boolean {
+  const matches = (value: unknown): boolean => typeof value === "string" && value.startsWith(LEGACY_OPENAI_MULTI_PREFIX);
+  const matchesList = (value: unknown): boolean => Array.isArray(value) && value.some(matches);
+  const claude = config.claudeCode;
+  return config.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || matchesList(config.disabledModels)
+    || matchesList(config.subagentModels)
+    || matches(config.injectionModel)
+    || matches(config.shadowCallIntercept?.model)
+    || matches(config.webSearchSidecar?.model)
+    || matches(config.visionSidecar?.model)
+    || matches(claude?.webSearchSidecar?.model)
+    || matches(claude?.visionSidecar?.model)
+    || matches(claude?.model)
+    || matches(claude?.smallFastModel)
+    || Object.values(claude?.tierModels ?? {}).some(matches)
+    || Object.values(claude?.modelMap ?? {}).some(matches)
+    || matchesList(config.providers[OPENAI_CODEX_PROVIDER_ID]?.selectedModels)
+    || matchesList(config.providers[LEGACY_OPENAI_MULTI_PROVIDER_ID]?.selectedModels)
+    || config.providerContextCaps?.[LEGACY_OPENAI_MULTI_PROVIDER_ID] !== undefined;
+}
+
+function rewriteLegacyOpenAiReferences(config: OcxConfig, warnings: string[]): void {
+  config.disabledModels = rewriteLegacyOpenAiModelList(config.disabledModels);
+  config.subagentModels = rewriteLegacyOpenAiModelList(config.subagentModels);
+  if (config.injectionModel) config.injectionModel = rewriteLegacyOpenAiSelectedId(config.injectionModel);
+  if (config.shadowCallIntercept?.model) {
+    config.shadowCallIntercept.model = rewriteLegacyOpenAiSelectedId(config.shadowCallIntercept.model);
+  }
+  if (config.webSearchSidecar?.model) config.webSearchSidecar.model = rewriteLegacyOpenAiSelectedId(config.webSearchSidecar.model);
+  if (config.visionSidecar?.model) config.visionSidecar.model = rewriteLegacyOpenAiSelectedId(config.visionSidecar.model);
+
+  const claude = config.claudeCode;
+  if (claude?.webSearchSidecar?.model) claude.webSearchSidecar.model = rewriteLegacyOpenAiSelectedId(claude.webSearchSidecar.model);
+  if (claude?.visionSidecar?.model) claude.visionSidecar.model = rewriteLegacyOpenAiSelectedId(claude.visionSidecar.model);
+  if (claude?.model) claude.model = rewriteLegacyOpenAiSelectedId(claude.model);
+  if (claude?.smallFastModel) claude.smallFastModel = rewriteLegacyOpenAiSelectedId(claude.smallFastModel);
+  if (claude?.tierModels) {
+    for (const tier of ["opus", "sonnet", "haiku", "fable"] as const) {
+      const value = claude.tierModels[tier];
+      if (value) claude.tierModels[tier] = rewriteLegacyOpenAiSelectedId(value);
+    }
+  }
+  if (claude?.modelMap) {
+    for (const key of Object.keys(claude.modelMap)) {
+      claude.modelMap[key] = rewriteLegacyOpenAiSelectedId(claude.modelMap[key]!);
+    }
+  }
+
+  const caps = config.providerContextCaps;
+  const legacyCap = caps?.[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  if (caps && legacyCap !== undefined) {
+    const currentCap = caps[OPENAI_CODEX_PROVIDER_ID];
+    if (currentCap !== undefined) {
+      caps[OPENAI_CODEX_PROVIDER_ID] = Math.min(currentCap, legacyCap);
+      warnings.push("providerContextCaps.openai + providerContextCaps.openai-multi: kept lower positive cap");
+    } else {
+      caps[OPENAI_CODEX_PROVIDER_ID] = legacyCap;
+    }
+    delete caps[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  }
+}
+
+function isKnownLegacyValuePath(path: readonly string[]): boolean {
+  const joined = path.join(".");
+  if (joined === "defaultProvider") return true;
+  if (/^(disabledModels|subagentModels)\.\d+$/.test(joined)) return true;
+  if (/^providers\.(openai|openai-multi)\.selectedModels\.\d+$/.test(joined)) return true;
+  return new Set([
+    "injectionModel",
+    "shadowCallIntercept.model",
+    "webSearchSidecar.model",
+    "visionSidecar.model",
+    "claudeCode.webSearchSidecar.model",
+    "claudeCode.visionSidecar.model",
+    "claudeCode.model",
+    "claudeCode.smallFastModel",
+    "claudeCode.tierModels.opus",
+    "claudeCode.tierModels.sonnet",
+    "claudeCode.tierModels.haiku",
+    "claudeCode.tierModels.fable",
+  ]).has(joined) || /^claudeCode\.modelMap\..+$/.test(joined);
+}
+
+function unknownLegacyOpenAiWarnings(config: OcxConfig): string[] {
+  const warnings = new Set<string>();
+  const visit = (value: unknown, path: string[]): void => {
+    if (typeof value === "string") {
+      if (value.includes(LEGACY_OPENAI_MULTI_PROVIDER_ID) && !isKnownLegacyValuePath(path)) {
+        warnings.add(`${path.join(".")}: legacy OpenAI provider id left unchanged`);
+      }
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => visit(item, [...path, String(index)]));
+      return;
+    }
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      visit(item, [...path, key]);
+    }
+  };
+  visit(config, []);
+  return [...warnings];
+}
+
+function resolvedOpenAiMode(
+  config: OcxConfig,
+  openai: OcxProviderConfig | undefined,
+  legacyMulti: OcxProviderConfig | undefined,
+  knownLegacyReference: boolean,
+): CodexAccountMode {
+  if (openai?.codexAccountMode === "pool" || openai?.codexAccountMode === "direct") {
+    return openai.codexAccountMode;
+  }
+  if (
+    (legacyMulti && legacyMulti.disabled !== true)
+    || config.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || knownLegacyReference
+  ) return "pool";
+  if (config.openaiProviderTierVersion === 1 && openai) return "direct";
+  if (config.openaiProviderTierVersion === 1 && legacyMulti) return "pool";
+  return "pool";
+}
+
+export function projectOpenAiTierMigration(config: OcxConfig): OpenAiTierMigrationProjection {
+  const projected = structuredClone(config);
+  const legacyMulti = projected.providers[LEGACY_OPENAI_MULTI_PROVIDER_ID];
+  if (legacyMulti && !managedLegacyMultiOverlay(legacyMulti)) {
+    throw new OpenAiTierMigrationCollisionError();
+  }
+
+  const openai = projected.providers[OPENAI_CODEX_PROVIDER_ID];
+  const knownLegacyReference = hasKnownLegacyOpenAiReference(projected);
+  const resolvedMode = resolvedOpenAiMode(projected, openai, legacyMulti, knownLegacyReference);
+  if (
+    projected.openaiProviderTierVersion === OPENAI_PROVIDER_TIER_VERSION
+    && !legacyMulti
+    && !Object.hasOwn(projected.providers, LEGACY_CHATGPT_PROVIDER_ID)
+    && projected.defaultProvider !== LEGACY_OPENAI_MULTI_PROVIDER_ID
+    && !knownLegacyReference
+  ) {
+    return { config: projected, changed: false, resolvedMode, warnings: [] };
+  }
+
+  const warnings = unknownLegacyOpenAiWarnings(projected);
+  const referencesCodexForward = !!openai
+    || !!legacyMulti
+    || Object.hasOwn(projected.providers, LEGACY_CHATGPT_PROVIDER_ID)
+    || projected.defaultProvider === OPENAI_CODEX_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_CHATGPT_PROVIDER_ID
+    || knownLegacyReference;
+  const mergedOpenAi = referencesCodexForward
+    ? mergeLegacyOpenAiProviderRows(openai, legacyMulti, resolvedMode)
+    : undefined;
+
+  const nextProviders: Array<[string, OcxProviderConfig]> = [];
+  let inserted = false;
+  for (const [name, provider] of Object.entries(projected.providers)) {
+    if (name === OPENAI_CODEX_PROVIDER_ID) {
+      if (mergedOpenAi && !inserted) nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+      inserted = true;
+      continue;
+    }
+    if (name === LEGACY_OPENAI_MULTI_PROVIDER_ID || name === LEGACY_CHATGPT_PROVIDER_ID) {
+      if (mergedOpenAi && !inserted && !openai) {
+        nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+        inserted = true;
+      }
+      continue;
+    }
+    nextProviders.push([name, provider]);
+  }
+  if (mergedOpenAi && !inserted) nextProviders.push([OPENAI_CODEX_PROVIDER_ID, mergedOpenAi]);
+  projected.providers = Object.fromEntries(nextProviders);
+
+  if (
+    projected.defaultProvider === LEGACY_OPENAI_MULTI_PROVIDER_ID
+    || projected.defaultProvider === LEGACY_CHATGPT_PROVIDER_ID
+  ) projected.defaultProvider = OPENAI_CODEX_PROVIDER_ID;
+
+  rewriteLegacyOpenAiReferences(projected, warnings);
+  projected.openaiProviderTierVersion = OPENAI_PROVIDER_TIER_VERSION;
+  return { config: projected, changed: true, resolvedMode, warnings: [...new Set(warnings)] };
+}

package/src/providers/openai-virtual-models.ts

@@ -0,0 +1,83 @@
+import { PROVIDER_REGISTRY } from "./registry";
+import { OPENAI_API_PROVIDER_ID } from "./openai-tiers";
+import type { OcxParsedRequest } from "../types";
+import type { RouteResult } from "../router";
+import type { RequestLogContext } from "../server/request-log";
+
+export interface OpenAiVirtualModelResolution {
+  selectedModelId: string;
+  wireModelId: string;
+  reasoningMode: "pro";
+}
+
+export class InvalidOpenAiVirtualModelRegistryError extends Error {
+  constructor(selectedModelId: string) {
+    super(`Invalid OpenAI virtual model registry definition: ${selectedModelId}`);
+    this.name = "InvalidOpenAiVirtualModelRegistryError";
+  }
+}
+
+export function validateOpenAiVirtualModelDefinition(
+  selectedModelId: string,
+  definition: unknown,
+): OpenAiVirtualModelResolution {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new InvalidOpenAiVirtualModelRegistryError(selectedModelId);
+  }
+  const raw = definition as { wireModelId?: unknown; reasoningMode?: unknown };
+  if (
+    typeof raw.wireModelId !== "string"
+    || raw.wireModelId.trim() !== raw.wireModelId
+    || raw.wireModelId.length === 0
+    || raw.wireModelId.includes("/")
+    || raw.wireModelId === selectedModelId
+    || raw.reasoningMode !== "pro"
+  ) {
+    throw new InvalidOpenAiVirtualModelRegistryError(selectedModelId);
+  }
+  return { selectedModelId, wireModelId: raw.wireModelId, reasoningMode: "pro" };
+}
+
+export function resolveOpenAiVirtualModel(
+  providerName: string,
+  selectedModelId: string,
+): OpenAiVirtualModelResolution | undefined {
+  if (providerName !== OPENAI_API_PROVIDER_ID) return undefined;
+  const entry = PROVIDER_REGISTRY.find(row => row.id === OPENAI_API_PROVIDER_ID);
+  if (!entry?.virtualModels || !Object.hasOwn(entry.virtualModels, selectedModelId)) return undefined;
+  const definition = entry.virtualModels[selectedModelId];
+  return validateOpenAiVirtualModelDefinition(selectedModelId, definition);
+}
+
+export function applyOpenAiVirtualModel(
+  parsed: OcxParsedRequest,
+  route: RouteResult,
+  logCtx: RequestLogContext,
+): OpenAiVirtualModelResolution | undefined {
+  const selectedModelId = logCtx.model && logCtx.model !== route.modelId ? logCtx.model : route.modelId;
+  const resolution = resolveOpenAiVirtualModel(route.providerName, selectedModelId);
+  if (!resolution) return undefined;
+
+  logCtx.model = resolution.selectedModelId;
+  logCtx.resolvedModel = resolution.wireModelId;
+  route.modelId = resolution.wireModelId;
+  parsed.modelId = resolution.wireModelId;
+  parsed._openAiVirtualSelectedModelId = resolution.selectedModelId;
+
+  if (parsed._rawBody && typeof parsed._rawBody === "object" && !Array.isArray(parsed._rawBody)) {
+    const raw = parsed._rawBody as Record<string, unknown>;
+    raw.model = resolution.wireModelId;
+    const existing = raw.reasoning;
+    raw.reasoning = existing && typeof existing === "object" && !Array.isArray(existing)
+      ? { ...(existing as Record<string, unknown>), mode: resolution.reasoningMode }
+      : { mode: resolution.reasoningMode };
+  }
+  return resolution;
+}
+
+export function resolveOpenAiCompactModel(
+  providerName: string,
+  selectedModelId: string,
+): OpenAiVirtualModelResolution | undefined {
+  return resolveOpenAiVirtualModel(providerName, selectedModelId);
+}

package/src/providers/openrouter-routing.ts

@@ -0,0 +1,102 @@
+import type { OcxProviderConfig, OpenRouterProviderRouting } from "../types";
+
+const ROUTING_KEYS = new Set(["order", "only", "allowFallbacks"]);
+const MAX_PROVIDER_SLUGS = 64;
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function isCanonicalOpenRouterTarget(baseUrl: string): boolean {
+  try {
+    const url = new URL(baseUrl);
+    return url.origin === "https://openrouter.ai"
+      && !url.username
+      && !url.password
+      && !url.search
+      && !url.hash
+      && url.pathname.replace(/\/+$/, "") === "/api/v1";
+  } catch {
+    return false;
+  }
+}
+
+function routingPreferenceError(value: unknown, field: string): string | null {
+  if (!isPlainRecord(value)) return `${field} must be a plain object`;
+  const unknown = Object.keys(value).find(key => !ROUTING_KEYS.has(key));
+  if (unknown) return `${field} contains unknown field "${unknown}"`;
+
+  for (const listField of ["order", "only"] as const) {
+    const list = value[listField];
+    if (list === undefined) continue;
+    if (!Array.isArray(list) || list.length === 0 || list.length > MAX_PROVIDER_SLUGS) {
+      return `${field}.${listField} must contain 1-${MAX_PROVIDER_SLUGS} provider slugs`;
+    }
+    const seen = new Set<string>();
+    for (const slug of list) {
+      if (typeof slug !== "string" || !slug.trim() || slug !== slug.trim() || slug.length > 128) {
+        return `${field}.${listField} must contain nonblank trimmed provider slugs up to 128 characters`;
+      }
+      if (seen.has(slug)) return `${field}.${listField} must not contain duplicate provider slugs`;
+      seen.add(slug);
+    }
+  }
+  if (value.allowFallbacks !== undefined && typeof value.allowFallbacks !== "boolean") {
+    return `${field}.allowFallbacks must be a boolean`;
+  }
+  if (value.order === undefined && value.only === undefined && value.allowFallbacks === undefined) {
+    return `${field} must define order, only, or allowFallbacks`;
+  }
+  return null;
+}
+
+export function openRouterRoutingConfigError(provider: OcxProviderConfig): string | null {
+  const hasDefault = provider.openRouterRouting !== undefined;
+  const hasModels = provider.modelOpenRouterRouting !== undefined;
+  if (!hasDefault && !hasModels) return null;
+  if (provider.adapter !== "openai-chat") {
+    return "OpenRouter routing preferences require the openai-chat adapter";
+  }
+  if (!isCanonicalOpenRouterTarget(provider.baseUrl)) {
+    return "OpenRouter routing preferences require the canonical https://openrouter.ai/api/v1 baseUrl";
+  }
+  if (hasDefault) {
+    const error = routingPreferenceError(provider.openRouterRouting, "openRouterRouting");
+    if (error) return error;
+  }
+  if (hasModels) {
+    const routes = provider.modelOpenRouterRouting;
+    if (!isPlainRecord(routes)) return "modelOpenRouterRouting must be a plain object";
+    for (const [modelId, preference] of Object.entries(routes)) {
+      if (!modelId.trim() || modelId !== modelId.trim()) {
+        return "modelOpenRouterRouting keys must be nonblank trimmed model ids";
+      }
+      const error = routingPreferenceError(preference, `modelOpenRouterRouting.${modelId}`);
+      if (error) return error;
+    }
+  }
+  return null;
+}
+
+export function resolveOpenRouterRouting(
+  provider: OcxProviderConfig,
+  modelId: string,
+): OpenRouterProviderRouting | undefined {
+  if (!isCanonicalOpenRouterTarget(provider.baseUrl)) return undefined;
+  const modelRoutes = provider.modelOpenRouterRouting;
+  return modelRoutes && Object.hasOwn(modelRoutes, modelId)
+    ? modelRoutes[modelId]
+    : provider.openRouterRouting;
+}
+
+export function openRouterProviderPayload(
+  preference: OpenRouterProviderRouting,
+): Record<string, unknown> {
+  return {
+    ...(preference.order ? { order: [...preference.order] } : {}),
+    ...(preference.only ? { only: [...preference.only] } : {}),
+    ...(preference.allowFallbacks !== undefined ? { allow_fallbacks: preference.allowFallbacks } : {}),
+  };
+}

package/src/providers/provider-id-rewrite.ts

@@ -0,0 +1,179 @@
+import type { OcxConfig } from "../types";
+
+export interface ProviderRewriteResult {
+  /** Number of references re-pointed. */
+  changed: number;
+  /**
+   * Sites where the destination key already held a value, left untouched. A
+   * non-empty list means the caller must not treat the rewrite as complete —
+   * merging two settings is not a decision this function can make. The function
+   * is NOT transactional: earlier sites are already rewritten by the time a
+   * collision is found, so a caller that receives collisions must discard the
+   * config it passed in.
+   */
+  collisions: string[];
+}
+
+/**
+ * Re-point every config reference from one provider id to another.
+ *
+ * Three shapes exist and the difference matters: routed model strings
+ * (`"<provider>/<model>"`), bare provider ids (`customModels[].provider`,
+ * `combos[*].targets[].provider`), and keys that ARE provider ids or routes
+ * (`providerContextCaps`, `claudeCode.desktopProfile.assignments`). A rewrite
+ * that handles only the first leaves an orphaned context cap and — worse — a
+ * combo target naming a provider that no longer exists, which fails validation
+ * in `src/combos/types.ts` and makes `loadConfig` discard the whole config.
+ *
+ * `providers[*].selectedModels` is deliberately NOT rewritten: those are
+ * per-provider native model ids, and upstream ids may themselves contain a
+ * slash, so a prefix rewrite could mangle an unrelated provider's allowlist. A
+ * caller that moves a provider row handles its own allowlist, where the
+ * destination catalog is known.
+ */
+export function rewriteProviderReferences(config: OcxConfig, from: string, to: string): ProviderRewriteResult {
+  const prefix = `${from}/`;
+  const collisions: string[] = [];
+  let changed = 0;
+
+  /** Routed string: rewrite only an exact `<from>/…` prefix, never a longer id. */
+  const route = (value: unknown): string | undefined => {
+    if (typeof value !== "string" || !value.startsWith(prefix)) return undefined;
+    changed += 1;
+    return `${to}/${value.slice(prefix.length)}`;
+  };
+
+  /**
+   * Rewrite a routed-string list in place. Assigning the result unconditionally
+   * would add an own property with value `undefined` where the field was absent,
+   * which breaks the no-op contract. The key type is an explicit union rather
+   * than `keyof OcxConfig`: the latter also admits `customModels` and friends, so
+   * `map` would infer a union array that is not assignable back.
+   */
+  type RoutedListKey = "disabledModels" | "subagentModels" | "subagentModelFallback";
+  const routeListAt = (key: RoutedListKey): void => {
+    const list = config[key];
+    if (!list) return;
+    config[key] = list.map(id => route(id) ?? id);
+  };
+
+  const routeRecordValues = (record: Record<string, string> | undefined): void => {
+    if (!record) return;
+    for (const [key, value] of Object.entries(record)) {
+      const next = route(value);
+      if (next) record[key] = next;
+    }
+  };
+
+  if (config.defaultProvider === from) {
+    config.defaultProvider = to;
+    changed += 1;
+  }
+
+  routeListAt("disabledModels");
+  routeListAt("subagentModels");
+  routeListAt("subagentModelFallback");
+
+  const scalarOwners: Array<[Record<string, unknown> | undefined, string]> = [
+    [config as unknown as Record<string, unknown>, "injectionModel"],
+    [config.shadowCallIntercept as Record<string, unknown> | undefined, "model"],
+    [config.webSearchSidecar as Record<string, unknown> | undefined, "model"],
+    [config.visionSidecar as Record<string, unknown> | undefined, "model"],
+    [config.claudeCode as unknown as Record<string, unknown> | undefined, "model"],
+    [config.claudeCode as unknown as Record<string, unknown> | undefined, "smallFastModel"],
+    [config.claudeCode?.webSearchSidecar as Record<string, unknown> | undefined, "model"],
+    [config.claudeCode?.visionSidecar as Record<string, unknown> | undefined, "model"],
+  ];
+  for (const [owner, key] of scalarOwners) {
+    if (!owner) continue;
+    const next = route(owner[key]);
+    if (next) owner[key] = next;
+  }
+
+  routeRecordValues(config.claudeCode?.tierModels as Record<string, string> | undefined);
+  routeRecordValues(config.claudeCode?.modelMap as Record<string, string> | undefined);
+
+  // Bare provider ids.
+  for (const model of config.customModels ?? []) {
+    if (model.provider === from) {
+      model.provider = to;
+      changed += 1;
+    }
+  }
+  for (const combo of Object.values(config.combos ?? {})) {
+    for (const target of combo.targets ?? []) {
+      if (target.provider === from) {
+        target.provider = to;
+        changed += 1;
+      }
+    }
+  }
+
+  // Keys. `providerContextCaps` is KEYED by provider id — a prefix rewrite would
+  // silently orphan the cap — and a destination key may already be occupied.
+  const caps = config.providerContextCaps;
+  if (caps && Object.hasOwn(caps, from)) {
+    if (Object.hasOwn(caps, to)) {
+      collisions.push(`providerContextCaps.${to}`);
+    } else {
+      caps[to] = caps[from]!;
+      delete caps[from];
+      changed += 1;
+    }
+  }
+
+  // `desktopProfile` is nested and asymmetric: `assignments` is KEYED by route
+  // while `defaults` holds routes as VALUES.
+  const profile = config.claudeCode?.desktopProfile;
+  if (profile) {
+    for (const key of Object.keys(profile.assignments ?? {})) {
+      const next = route(key);
+      if (!next) continue;
+      if (Object.hasOwn(profile.assignments, next)) {
+        changed -= 1; // `route` counted it; the move did not happen.
+        collisions.push(`claudeCode.desktopProfile.assignments.${next}`);
+        continue;
+      }
+      profile.assignments[next] = profile.assignments[key]!;
+      delete profile.assignments[key];
+    }
+    const defaults = profile.defaults as Record<string, string | null> | undefined;
+    if (defaults) {
+      for (const [family, value] of Object.entries(defaults)) {
+        const next = route(value);
+        if (next) defaults[family] = next;
+      }
+    }
+  }
+
+  return { changed, collisions };
+}
+
+/**
+ * Drop the custom-model rows that belonged to a provider being removed.
+ *
+ * The sibling of the rename pass above. `rewriteProviderReferences` already
+ * carries `customModels[].provider` across a rename, so the array tracks the
+ * provider lifecycle — but removal used to delete only `config.providers[name]`
+ * and leave the rows behind. Those orphans still reach `/api/models` and the
+ * generated Codex catalog, which key on the row rather than on provider
+ * existence, so they surface as models that resolve to nothing (#1273).
+ *
+ * Only the rows are touched: the `customModelCatalogMigration` marker records
+ * one-time ownership of pre-marker rows and must survive removal unchanged, or
+ * an older binary's view of that ownership silently changes.
+ *
+ * Returns the number of rows dropped so callers can report it.
+ */
+export function dropProviderCustomModels(config: OcxConfig, provider: string): number {
+  const existing = config.customModels;
+  if (!Array.isArray(existing) || existing.length === 0) return 0;
+  const kept = existing.filter(model => model.provider !== provider);
+  if (kept.length === existing.length) return 0;
+  // Match the add/remove routes: an emptied list is dropped rather than left as
+  // `[]`, so the `customModels` field is absent either way. Only that field —
+  // the `customModelCatalogMigration` marker is deliberately left in place.
+  if (kept.length > 0) config.customModels = kept;
+  else delete config.customModels;
+  return existing.length - kept.length;
+}