@iislee/opencodex 2.11.0 → 2.31.0

package/src/providers/openai-sidecar.ts

@@ -1,9 +1,11 @@
 import { resolveEnvValue } from "../config";
 import {
+  CodexPoolAuthenticationError,
   headersForCodexAuthContext,
   hasCallerCodexBearer,
   isCodexAuthContextUsable,
   resolveCodexAuthContext,
+  type CodexAccountSelectionAdmission,
   type CodexAuthContext,
 } from "../codex/auth-context";
 import { recordCodexUpstreamOutcome, type CodexUpstreamOutcome } from "../codex/routing";
@@ -11,6 +13,7 @@ import { extractAccountId } from "../oauth/chatgpt";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "../server/auth-cors";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import {
+  CODEX_FORWARD_BASE_URL,
   isCanonicalOpenAiForwardProvider,
   OPENAI_API_PROVIDER_ID,
   OPENAI_CODEX_PROVIDER_ID,
@@ -29,6 +32,17 @@ export interface ResolvedOpenAiForwardSidecar extends OpenAiForwardSidecarCandid
   recordOutcome?: (outcome: CodexUpstreamOutcome) => void;
 }
 
+/**
+ * Server-resolved exact account selection for a ChatGPT sidecar call.
+ * `accountId` must come from a validated account-qualified route; request headers
+ * are never trusted as account ids. `modelId` is the sidecar's actual upstream
+ * model so cooldown admission and outcome recording use the correct quota scope.
+ */
+export interface ExactOpenAiSidecarAccount {
+  accountId: string;
+  modelId: string;
+}
+
 export interface OpenAiImagesProviderSelection {
   forwardCandidates: OpenAiForwardSidecarCandidate[];
   keyed?: {
@@ -41,11 +55,24 @@ export interface OpenAiImagesProviderSelection {
 
 export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiForwardSidecarCandidate[] {
   const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
-  if (!provider || provider.disabled === true || !isCanonicalOpenAiForwardProvider(provider)) return [];
+  if (!provider || provider.disabled === true) return [];
+  // The built-in registry defaults an omitted authMode to forward. Normalize only that
+  // missing field before the strict adapter/destination check; explicit key mode and
+  // noncanonical destinations remain ineligible for ChatGPT credential injection.
+  const canonicalProvider = provider.authMode === undefined
+    ? { ...provider, authMode: "forward" as const }
+    : provider;
+  if (!isCanonicalOpenAiForwardProvider(canonicalProvider)) return [];
+  // The predicate accepts harmless trailing-slash variants. Pin the provider returned
+  // to credential-bearing sidecars so every consumer builds one exact ChatGPT path
+  // instead of independently concatenating the operator's equivalent spelling.
+  const pinnedProvider = canonicalProvider.baseUrl === CODEX_FORWARD_BASE_URL
+    ? canonicalProvider
+    : { ...canonicalProvider, baseUrl: CODEX_FORWARD_BASE_URL };
   return [{
     providerName: OPENAI_CODEX_PROVIDER_ID,
-    provider,
-    accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, provider) ?? "pool",
+    provider: pinnedProvider,
+    accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, pinnedProvider) ?? "pool",
   }];
 }
 
@@ -70,7 +97,12 @@ export async function resolveFirstUsableOpenAiSidecar(
   candidates: readonly OpenAiForwardSidecarCandidate[],
   incomingHeaders: Headers,
   config: OcxConfig,
+  options: {
+    exactAccount?: ExactOpenAiSidecarAccount;
+    beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
+  } = {},
 ): Promise<ResolvedOpenAiForwardSidecar | undefined> {
+  const { exactAccount } = options;
   let callerBearerMayBeForwarded = true;
   try {
     validateForwardAdmissionCredential(incomingHeaders, config);
@@ -79,6 +111,39 @@ export async function resolveFirstUsableOpenAiSidecar(
     callerBearerMayBeForwarded = false;
   }
   for (const candidate of candidates) {
+    if (exactAccount) {
+      // An account-qualified model is an explicit user choice. Resolve the stored
+      // credential directly even when the provider is globally Direct, and never
+      // consult Pool active state, affinity, probes, or alternates.
+      const authContext = await resolveCodexAuthContext(incomingHeaders, config, "pool", {
+        accountId: exactAccount.accountId,
+        modelId: exactAccount.modelId,
+        beginCodexAccountSelection: options.beginCodexAccountSelection,
+      });
+      if ((authContext.kind !== "pool" && authContext.kind !== "main-pool")
+        || !isCodexAuthContextUsable(authContext, config)) {
+        // Exact selection is fail-closed. A generation/runtime-state race must not fall through
+        // to the caller-bearer error or let a later candidate select another account.
+        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+      }
+      return {
+        ...candidate,
+        authContext,
+        headers: headersForCodexAuthContext(incomingHeaders, authContext),
+        recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
+          config,
+          authContext.accountId,
+          outcome,
+          {
+            modelId: exactAccount.modelId,
+            fixedAccount: true,
+            probeLeaseId: authContext.probeLeaseId,
+            probeQuotaScope: authContext.probeQuotaScope,
+            writerGeneration: authContext.writerGeneration,
+          },
+        ),
+      };
+    }
     if (candidate.accountMode === "direct") {
       if (!callerBearerMayBeForwarded || !hasCallerCodexBearer(incomingHeaders)) continue;
       const headers = directSidecarHeaders(incomingHeaders);
@@ -89,7 +154,9 @@ export async function resolveFirstUsableOpenAiSidecar(
         headers,
       };
     }
-    const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode);
+    const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode, {
+      beginCodexAccountSelection: options.beginCodexAccountSelection,
+    });
     if (!isCodexAuthContextUsable(authContext, config)) continue;
     return {
       ...candidate,
@@ -102,6 +169,7 @@ export async function resolveFirstUsableOpenAiSidecar(
             authContext.accountId,
             outcome,
             {
+              threadId: authContext.affinityKey,
               probeLeaseId: authContext.probeLeaseId,
               writerGeneration: authContext.writerGeneration,
             },

package/src/providers/openai-tier-startup.ts

@@ -1,4 +1,10 @@
-import { backupConfigBeforeOpenAiTierMigration, saveConfig } from "../config";
+import {
+  backupConfigBeforeOpenAiTierMigration,
+  OpenAiTierBackupCollisionError,
+  OpenAiTierRollbackPreserveError,
+  preserveOpenAiTierRollbackSnapshot,
+  saveConfig,
+} from "../config";
 import type { OcxConfig } from "../types";
 import { projectOpenAiTierMigration } from "./openai-tiers";
 
@@ -6,6 +12,23 @@ export interface OpenAiTierStartupDeps {
   project: typeof projectOpenAiTierMigration;
   backup: () => void;
   save: (config: OcxConfig) => void;
+  preserveRollback?: (error: OpenAiTierBackupCollisionError) => void;
+}
+
+function defaultPreserveRollback(error: OpenAiTierBackupCollisionError): void {
+  if (!error.configPath) throw error;
+  try {
+    const preserved = preserveOpenAiTierRollbackSnapshot(error.configPath);
+    console.warn(`[openai-provider-migration] Preserved rollback snapshot at ${preserved}`);
+  } catch (cause) {
+    if (
+      cause instanceof OpenAiTierRollbackPreserveError
+      && (cause.code === "missing" || cause.code === "not-rollback")
+    ) {
+      throw error;
+    }
+    throw cause;
+  }
 }
 
 const DEFAULT_DEPS: OpenAiTierStartupDeps = {
@@ -20,7 +43,13 @@ export function runOpenAiTierStartupMigration(
 ): OcxConfig {
   const projection = deps.project(config);
   if (!projection.changed) return projection.config;
-  deps.backup();
+  try {
+    deps.backup();
+  } catch (error) {
+    if (!(error instanceof OpenAiTierBackupCollisionError)) throw error;
+    (deps.preserveRollback ?? defaultPreserveRollback)(error);
+    deps.backup();
+  }
   deps.save(projection.config);
   for (const warning of projection.warnings) console.warn(`[openai-provider-migration] ${warning}`);
   return projection.config;

package/src/providers/openai-tiers.ts

@@ -1,5 +1,7 @@
-import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig, ProviderCostOverlay } from "../types";
 import { OPENAI_PROVIDER_TIER_VERSION } from "../types";
+import { openaiResponsesUrl } from "../adapters/openai-responses-url";
+import { MAX_COST4_RATE } from "../usage/expected-prices";
 
 export const OPENAI_CODEX_PROVIDER_ID = "openai";
 export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
@@ -35,7 +37,35 @@ export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): b
     && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
 }
 
-const OPENAI_API_BASE_URL = "https://api.openai.com/v1";
+const OPENAI_API_ORIGIN = "https://api.openai.com";
+const OPENAI_API_BASE_URL = `${OPENAI_API_ORIGIN}/v1`;
+const OPENAI_API_RESPONSES_URL = `${OPENAI_API_BASE_URL}/responses`;
+
+/**
+ * The Responses endpoint the adapter would actually POST key-auth traffic to, normalized.
+ *
+ * Mirrors the adapter's own construction (`src/adapters/openai-responses.ts`): a configured
+ * `responsesPath` is appended to the base verbatim, and only the default branch runs the
+ * `/v1/responses` suffix normalization. Classifying on the base URL alone would call
+ * `baseUrl: "https://api.openai.com"` with `responsesPath: "/other"` official even though that
+ * request never reaches the official Responses endpoint.
+ */
+function resolvedResponsesEndpoint(provider: OcxProviderConfig): string | undefined {
+  try {
+    const raw = provider.responsesPath === undefined
+      ? openaiResponsesUrl(provider.baseUrl)
+      : `${provider.baseUrl.replace(/\/$/, "")}${provider.responsesPath}`;
+    return normalizedBaseUrl(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function isOfficialOpenAiResponsesDestination(provider: OcxProviderConfig): boolean {
+  // Exact normalized URL keeps lookalike/suffix hosts out of this set: `api.openai.com.evil.test`
+  // resolves to its own origin, never to the official one.
+  return resolvedResponsesEndpoint(provider) === OPENAI_API_RESPONSES_URL;
+}
 
 /**
  * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
@@ -53,6 +83,36 @@ export function supportsNativeResponsesCompactEndpoint(
     && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
 }
 
+/**
+ * Whether this destination is an OpenAI-operated Responses backend — the canonical ChatGPT Codex
+ * surface or the official OpenAI API.
+ *
+ * Deliberately not keyed on `authMode === "forward"`: a noncanonical forward provider does not
+ * receive the caller's credentials (see the forward-header gate in the Responses adapter), so
+ * forward auth says nothing about which backend is on the other end.
+ */
+export function isOpenAiOperatedResponsesDestination(provider: OcxProviderConfig): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return provider.adapter === "openai-responses"
+    && isOfficialOpenAiResponsesDestination(provider);
+}
+
+/**
+ * Whether this destination can decode a native (non-`ocx1:`) compaction blob.
+ *
+ * Only the backend that minted a blob can decode it. `authMode: "forward"` alone is not a signal:
+ * the adapter forwards caller credentials only to the canonical ChatGPT Codex surface, while a
+ * noncanonical forward provider receives no caller credentials and may point at any backend.
+ *
+ * Relay only to an OpenAI-operated destination or a destination whose operator explicitly opts in.
+ * Keyed by destination rather than provider id: a blob's issuer is the URL that produced it, not the
+ * local config key a replay travels under.
+ */
+export function destinationDecodesNativeCompactionBlob(provider: OcxProviderConfig): boolean {
+  return isOpenAiOperatedResponsesDestination(provider)
+    || provider.decodesNativeCompactionBlobs === true;
+}
+
 export interface OpenAiTierMigrationProjection {
   config: OcxConfig;
   changed: boolean;
@@ -69,11 +129,17 @@ export class OpenAiTierMigrationCollisionError extends Error {
   }
 }
 
-function managedLegacyMultiOverlay(provider: OcxProviderConfig): Pick<OcxProviderConfig, "disabled" | "selectedModels"> | null {
-  const allowed = new Set(["adapter", "authMode", "baseUrl", "disabled", "selectedModels"]);
+function managedLegacyMultiOverlay(
+  provider: OcxProviderConfig,
+): Pick<OcxProviderConfig, "disabled" | "selectedModels" | "modelCosts"> | null {
+  const allowed = new Set(["adapter", "authMode", "baseUrl", "disabled", "selectedModels", "modelCosts"]);
   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;
+  // Keep the migration self-contained: a malformed overlay is a collision, not
+  // something to carry into the canonical row (importing config.ts here would
+  // create an import cycle — config.ts already imports this module).
+  if (provider.modelCosts !== undefined && !validLegacyOverlayCosts(provider.modelCosts)) return null;
   if (provider.selectedModels !== undefined && (
     !Array.isArray(provider.selectedModels)
     || provider.selectedModels.some(model => typeof model !== "string")
@@ -81,9 +147,26 @@ function managedLegacyMultiOverlay(provider: OcxProviderConfig): Pick<OcxProvide
   return {
     ...(provider.disabled !== undefined ? { disabled: provider.disabled } : {}),
     ...(provider.selectedModels !== undefined ? { selectedModels: [...provider.selectedModels] } : {}),
+    ...(provider.modelCosts !== undefined ? { modelCosts: provider.modelCosts } : {}),
   };
 }
 
+/** Shape check for a legacy overlay: a plain record of complete non-negative finite Cost4 rows. */
+function validLegacyOverlayCosts(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const fields = ["input", "output", "cacheRead", "cacheWrite"] as const;
+  return Object.values(value as Record<string, unknown>).every(entry => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+    const rates = entry as Record<string, unknown>;
+    return Object.keys(rates).length === fields.length
+      && fields.every(key => Object.hasOwn(rates, key)
+        && typeof rates[key] === "number"
+        && Number.isFinite(rates[key])
+        && (rates[key] as number) >= 0
+        && (rates[key] as number) <= MAX_COST4_RATE);
+  });
+}
+
 function rewriteLegacyOpenAiSelectedId(value: string): string {
   return value.startsWith(LEGACY_OPENAI_MULTI_PREFIX)
     ? value.slice(LEGACY_OPENAI_MULTI_PREFIX.length)
@@ -95,6 +178,28 @@ function rewriteLegacyOpenAiModelList(values: string[] | undefined): string[] |
   return [...new Set(values.map(rewriteLegacyOpenAiSelectedId))];
 }
 
+/**
+ * Rewrite legacy `openai-multi/<model>` keys in a modelCosts overlay so the
+ * prices still match after the migration resolves logs as provider `openai`
+ * with the bare model id. Keys without the legacy prefix pass through.
+ */
+function rewriteLegacyOpenAiCostKeys(costs: Record<string, ProviderCostOverlay> | undefined): Record<string, ProviderCostOverlay> {
+  // Null-prototype map so prototype-named model ids (e.g. "__proto__") are
+  // stored as own properties instead of invoking the inherited setter.
+  const rewritten = Object.create(null) as Record<string, ProviderCostOverlay>;
+  if (costs) {
+    for (const [key, value] of Object.entries(costs)) {
+      const canonicalKey = rewriteLegacyOpenAiSelectedId(key);
+      // A bare <model> key always wins over its openai-multi/<model> equivalent
+      // inside the same row, regardless of JSON property order.
+      if (key === canonicalKey || !Object.hasOwn(rewritten, canonicalKey)) {
+        rewritten[canonicalKey] = value;
+      }
+    }
+  }
+  return rewritten;
+}
+
 function mergeLegacyOpenAiProviderRows(
   openai: OcxProviderConfig | undefined,
   legacyMulti: OcxProviderConfig | undefined,
@@ -104,12 +209,22 @@ function mergeLegacyOpenAiProviderRows(
     ...(openai?.selectedModels ?? []),
     ...(legacyMulti?.selectedModels ?? []),
   ]);
+  // Both rows can carry disjoint overlays; merge them (canonical openai wins on
+  // key conflicts) so legacy Multi prices are not silently dropped. Keys are
+  // rewritten first so `openai-multi/<model>` entries still resolve after the
+  // provider is canonicalized to `openai`.
+  const modelCosts = {
+    ...rewriteLegacyOpenAiCostKeys(legacyMulti?.modelCosts),
+    ...rewriteLegacyOpenAiCostKeys(openai?.modelCosts),
+  };
+  const hasModelCosts = Object.keys(modelCosts).length > 0;
   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 } : {}),
+    ...(hasModelCosts ? { modelCosts } : {}),
   };
 }
 

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

@@ -62,6 +62,7 @@ export function applyOpenAiVirtualModel(
   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>;

package/src/providers/opencode-zen-rate-limit.ts

@@ -0,0 +1,102 @@
+/**
+ * OpenCode Zen short-window rate-limit guidance (#1145 / OCX-56).
+ *
+ * OpenCode's keyed and keyless Zen chat endpoints share `https://opencode.ai/zen/v1`.
+ * Free-model traffic can hit a short-window burst ceiling around 15–20 RPM
+ * (community-measured). Zen often answers with opaque `429 Rate limit exceeded`
+ * bodies and may omit `Retry-After` / `X-RateLimit-*`; when those headers are
+ * present they still take precedence. Distinct from the keyless desktop
+ * ~200 requests / 5h quota documented on `opencode-free`.
+ */
+import { validateClientRetryAfterHeader } from "../lib/retry-after";
+import { registryEntryForProviderDestination } from "./registry";
+
+const OPENCODE_ZEN_PROVIDER_IDS = new Set(["opencode-zen", "opencode-free"]);
+
+/** Observed free-model burst ceiling on Zen (not an official OpenCode figure). */
+export const OPENCODE_ZEN_OBSERVED_RPM_HINT = "roughly 15-20 requests per minute";
+
+/**
+ * Synthetic client backoff when Zen omits Retry-After after a rate-limit 429.
+ * Longer than the generic 2s default so Codex-shaped clients do not immediately
+ * re-hammer a ~15-20 RPM window.
+ */
+export const OPENCODE_ZEN_SYNTHETIC_RETRY_AFTER_SEC = 15;
+
+const ENRICHMENT_MARKER = "15-20 requests per minute";
+
+export function isOpenCodeZenRateLimitProvider(opts: {
+  providerName?: string;
+  baseUrl?: string;
+  adapter?: string;
+}): boolean {
+  const name = opts.providerName?.trim();
+  if (name && OPENCODE_ZEN_PROVIDER_IDS.has(name)) return true;
+  const baseUrl = opts.baseUrl?.trim();
+  if (!baseUrl) return false;
+  const entry = registryEntryForProviderDestination({
+    baseUrl,
+    adapter: opts.adapter?.trim() || "openai-chat",
+    authMode: "key",
+  });
+  return entry !== undefined && OPENCODE_ZEN_PROVIDER_IDS.has(entry.id);
+}
+
+/**
+ * Same-key `retryOn429` only applies on key-authenticated HTTP paths — not
+ * keyless `opencode-free` traffic and not custom `runTurn` transports.
+ */
+export function supportsOpenCodeZenRetryOn429Guidance(opts: {
+  authMode?: string;
+  hasApiKey?: boolean;
+  supportsHttpSameKeyRetry?: boolean;
+}): boolean {
+  if (opts.supportsHttpSameKeyRetry === false) return false;
+  if (opts.authMode !== undefined && opts.authMode !== "key") return false;
+  return opts.hasApiKey === true;
+}
+
+/**
+ * Append actionable Zen rate-limit context to a generic upstream 429 message and
+ * embed a parseable `try again in Ns` hint so {@link resolveClientRetryAfter}
+ * surfaces a useful Retry-After when the gateway sent none.
+ */
+export function enrichOpenCodeZenRateLimitMessage(
+  message: string,
+  opts: {
+    status: number;
+    providerName?: string;
+    baseUrl?: string;
+    adapter?: string;
+    authMode?: string;
+    hasApiKey?: boolean;
+    /** Upstream Retry-After header; when valid, skip the synthetic 15s text hint. */
+    upstreamRetryAfter?: string | null;
+    /** False for custom `runTurn` transports outside the HTTP retry loop. */
+    supportsHttpSameKeyRetry?: boolean;
+    now?: number;
+  },
+): string {
+  if (opts.status !== 429) return message;
+  if (!isOpenCodeZenRateLimitProvider(opts)) return message;
+  if (!/rate\s*limit/i.test(message)) return message;
+  if (message.includes(ENRICHMENT_MARKER)) return message;
+
+  const upstreamRetry = validateClientRetryAfterHeader(
+    opts.upstreamRetryAfter,
+    opts.now ?? Date.now(),
+  );
+  const retryHint = upstreamRetry || /try again in \d/i.test(message)
+    ? ""
+    : ` Try again in ${OPENCODE_ZEN_SYNTHETIC_RETRY_AFTER_SEC}s.`;
+  const paceHint = supportsOpenCodeZenRetryOn429Guidance(opts)
+    ? " Slow the request pace, or set providers.opencode-zen.retryOn429 for same-key backoff."
+    : " Slow the request pace.";
+  return (
+    `${message}`
+    + ` OpenCode Zen free-model traffic is often limited to ${OPENCODE_ZEN_OBSERVED_RPM_HINT}`
+    + ` (observed; OpenCode does not publish this RPM, and may omit rate-limit headers).`
+    + `${retryHint}`
+    + paceHint
+  );
+}

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

@@ -148,3 +148,32 @@ export function rewriteProviderReferences(config: OcxConfig, from: string, to: s
 
   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;
+}