@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
823 lines (798 loc) • 39.8 kB
text/typescript
import { projectAntigravitySelectedModels } from "../../providers/antigravity-effort-families";
import { configuredUltraFastSlugs, retainedFlexPolicyBySlug } from "./configured-tiers";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { initializeConfigOwnership } from "../../lib/config-ownership";
import { getConfigDir, loadConfig, ultraFastTierEnabled, websocketsEnabled, withConfigMutationLockSync } from "../../config";
import { resolveMultiAgentMode } from "../../config/multi-agent-surface";
import { resolveRoutedCatalogDefaults } from "../../config/schema/routed-catalog-defaults";
import { shouldSyncCodexOnStart } from "../desired-state";
import { legacyCustomModelCatalogSlugs } from "../custom-model-catalog-migration";
import { getCodexHome } from "../paths";
import type { OcxConfig } from "../../types";
import { pendingModelSelectionProviders } from "../../providers/initial-model-selection";
import { captureModelDiscoveryBaseline, finalizeModelDiscovery } from "../../providers/new-model-policy-runtime";
import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import { providerCodexAccountMode } from "../../providers/registry";
import { COMBO_NAMESPACE } from "../../combos";
import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "../account-namespaces";
import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
import { applyNativeRosterMetadata } from "./access-programs";
import { advanceNativeInheritanceTemplate, captureNativeInheritanceTemplate } from "./native-template";
import { omitDisabledNativeCatalogEntries } from "./native-omission";
import {
availableAccountGatedNativeModels,
codexModelEntitlementStateForAccount,
isCodexModelEntitlementSnapshotCurrent,
type CodexModelEntitlementSnapshot,
} from "../model-entitlements";
import { resolveAdmittedCodexModelEntitlements } from "../model-entitlement-admission";
import { isAccountNeedsReauth } from "../account-runtime-state";
import { codexRuntimeStatePath } from "../runtime";
import {
activeCodexModelsCachePath,
catalogBackupPathFor,
catalogHasRoutedEntries,
findNativeTemplate,
isDefaultCatalogPath,
legacyCatalogBackupPath,
readCatalog,
readCatalogBackup,
readCodexCatalogPath,
readCodexCatalogPathForHome,
nativeMultiAgentDefaults,
} from "./parsing";
import type { CatalogModel, MultiAgentMode, RawCatalog, RawEntry } from "./parsing";
import { readNativeBaseline } from "./native-priority";
import { ocxRoutedNamespaceCounts, routedRemovalBackedByConfigFile, unconfiguredRoutedRemoval } from "./routed-removal";
import { ConfigMutationLockError } from "../../config/mutation-lock";
import {
accountBoundNativeOpenAiSlugsBySelector,
desktopAllowlistSuppressedNativeSlugs,
disabledNativeSlugs,
nativeContextLimits,
observedAccountBoundNativeEntries,
observedReserveCatalogSource,
shouldIncludeAccountBoundNativeOpenAi,
shouldIncludeNativeOpenAi,
shouldUpgradeToUpstreamEntry,
upstreamNativeEntry,
} from "./metadata";
import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
import { bundledCatalogCacheState, bundledCodexCatalogSnapshot, loadBundledCodexCatalogAsync } from "./bundled";
import { isMultiAgentV2Enabled } from "../features";
import { clampCatalogModelsToCodexSupport } from "./effort";
import { suppressedSyntheticMaxCatalogSlugs } from "./model-hints";
import { filterCatalogVisibleModels, gatherRoutedModels, type CatalogGatherProviderModelOutcome } from "./provider-fetch";
import { comboCatalogDescriptions, dedupeCatalogEntriesBySlug, enforceCatalogSlugUniqueness, exactComboCatalogSlugs, type ComboCatalogOmission } from "./aggregation";
import {
withCatalogWriteSerialization,
type CatalogWritePermit,
} from "../catalog-write-serialization";
import {
preparedBytesDifferFromDisk,
auditRefusedCatalogReplacement,
publishHashedCodexCatalogBackup,
publishLegacyCodexCatalogBackup,
replaceActiveCodexCatalog,
replaceCodexModelsCache,
type PreparedCatalogFileWrite,
type CatalogFileReplacement,
} from "../internal/catalog-writer";
import { visibleCodexAccountSelectors } from "./account-models";
import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./native-models";
import { createReserveCatalogProjection, RESERVE_LUNA_METADATA_SOURCE, RESERVE_SOURCE_CATALOG_FIELD } from "./reserve";
import {
CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
buildCatalogEntriesFromObservedState,
mergeCatalogEntriesFromObservedState,
mergeCatalogModelsWithNativeRecovery,
orderForSubagents,
} from "./build-entries";
import { finishUpstreamNativeEntry } from "./derive-entry";
import { finalizeAutoReviewModelOverride } from "./auto-review";
import { gatedNativeAccountLabel, gatedNativeReauthSuppressionReason, warnGatedNativeSuppressedOnce } from "./gated-native-warn";
import { reserveCatalogSuppressionReason, warnReserveSuppressedOnce } from "./reserve-warn";
interface RetainedCatalogSyncRead {
readonly catalogPath: string;
readonly catalog: RawCatalog;
readonly onDiskCatalog: RawCatalog | null;
readonly modelsCache: RawCatalog | null;
readonly evidence: string;
/**
* Process-local epochs, baselined AFTER our own gather rather than with the
* filesystem bytes above. See `retainedCatalogProcessEvidence`.
*/
readonly processEvidence: string;
}
interface RetainedCatalogSyncResult {
added: number;
path: string;
catalogWritten: boolean;
comboOmissions: ComboCatalogOmission[];
/** Validated catalog commit (including identical bytes), or a refused refresh. */
refreshOutcome?: "committed" | "refused";
/**
* `desired_disabled`: observed under K after the provider await. `unbacked_routed_removal`: the
* catalog would lose routed namespaces config.json still enables, or config.json is missing or
* unreadable (#6529). `foreign_owner`: this Codex home is bound to another OPENCODEX_HOME. Nothing
* was written in any of these cases.
*/
skippedReason?: "desired_disabled" | "unbacked_routed_removal" | "foreign_owner" | "owner_unknown";
/** With `unbacked_routed_removal`: how many routed namespaces the refused write would have emptied. */
protectedRoutedNamespaces?: number;
}
/**
* Catalog/cache commit overrides.
*
* An explicit `ocx sync` is also the refresh path for side profiles that consume
* the OpenCodex catalog without injection (for example a custom `model_provider`
* that routes to the proxy). In that mode the Codex integration toggle only
* governs config/history injection; the catalog and models cache may still be
* refreshed, so `allowWhenDesiredDisabled` lets the commit path ignore the OFF
* gate that otherwise protects a fully native home.
*/
export interface CodexCatalogSyncOptions {
allowWhenDesiredDisabled?: boolean;
}
interface RetainedCatalogSyncWrite {
readonly config: OcxConfig;
readonly goModels: CatalogModel[];
readonly providerModelOutcomes: readonly CatalogGatherProviderModelOutcome[];
readonly comboOmissions: ComboCatalogOmission[];
readonly read: RetainedCatalogSyncRead;
readonly permit: CatalogWritePermit;
readonly owningCodexHome: string;
readonly modelEntitlements: CodexModelEntitlementSnapshot;
}
function optionalFileBytes(path: string): string | null {
try {
return readFileSync(path).toString("base64");
} catch (error) {
if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return null;
throw error;
}
}
function loadCatalogForRetainedSync(path: string): RawCatalog | null {
const bundled = isDefaultCatalogPath(path) ? bundledCodexCatalogSnapshot() : null;
if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
const active = readCatalog(path);
// A valid configured custom file remains the content authority even when it has no bare native
// template. The null-template builder is deliberate; a stale backup must not replace active
// custom root metadata merely because the current file contains only routed rows.
if (active && (!isDefaultCatalogPath(path) || findNativeTemplate(active))) return active;
return readCatalog(catalogBackupPathFor(path))
?? (isDefaultCatalogPath(path) ? readCatalog(legacyCatalogBackupPath()) : null)
?? readCatalog(activeCodexModelsCachePath())
?? active;
}
function retainedCatalogSyncEvidence(
config: OcxConfig,
catalogPath: string,
catalog: RawCatalog,
): string {
return JSON.stringify({
config,
catalogPath,
catalog,
catalogBytes: optionalFileBytes(catalogPath),
hashedBackupBytes: optionalFileBytes(catalogBackupPathFor(catalogPath)),
legacyBackupBytes: isDefaultCatalogPath(catalogPath)
? optionalFileBytes(legacyCatalogBackupPath()) : null,
modelsCacheBytes: optionalFileBytes(activeCodexModelsCachePath()),
// The persisted runtime selection is a pre-await filesystem input, not a
// process epoch: another PROCESS can move runtime authority by rewriting this
// file, and that move is invisible to our in-process memo. Recorded PRESENT or
// ABSENT, because its absence is what makes the resolver fall back.
runtimeStateBytes: optionalFileBytes(codexRuntimeStatePath()),
});
}
/**
* The bundled-template half of the same evidence, observed separately.
*
* The runtime process memo is deliberately NOT here, and that exclusion took three
* attempts to get honest. Gathering resolves the Codex runtime lazily and under its
* own cache key, so this path cannot pre-settle that memo: baselining it before the
* await always detected our own side effect and refused every write, and baselining
* it after the await captured a runtime that ANOTHER process had moved as though it
* were ours — a catalog prepared from R1 committing after authority reached R2.
*
* Runtime authority is covered where it is actually durable instead: the persisted
* `codex-runtime.json` bytes sit in the pre-await filesystem evidence, PRESENT or
* ABSENT, so a cross-process runtime move is caught. What is left uncovered, and is
* written down rather than papered over, is a same-process in-memory runtime swap
* that never touches that file — WP11 owns the lock that makes that case decidable.
*/
function retainedCatalogProcessEvidence(): string {
return JSON.stringify({
bundledCatalogCache: bundledCatalogCacheState(),
});
}
/**
* Capture every local catalog input the retained sync path consults before its
* provider await. The exact evidence is compared after K acquisition; a newer
* catalog/backup/cache or target selection makes this attempt a no-write.
*/
function readRetainedCatalogSync(config: OcxConfig): RetainedCatalogSyncRead | null {
const catalogPath = readCodexCatalogPath();
const catalog = loadCatalogForRetainedSync(catalogPath);
if (!catalog) return null;
// The bundled catalog is a reliable native template on the default path, but it is not the
// merge source. Preservation must inspect the file that this sync is about to overwrite;
// otherwise an empty/partial provider gather cannot see routed or user-native rows on disk.
const onDiskCatalog = readCatalog(catalogPath);
const modelsCache = readCatalog(activeCodexModelsCachePath());
const evidence = retainedCatalogSyncEvidence(config, catalogPath, catalog);
// `processEvidence` is filled in after the provider await, not here.
return { catalogPath, catalog, onDiskCatalog, modelsCache, evidence, processEvidence: "" };
}
function revalidateRetainedCatalogSync(
config: OcxConfig,
prepared: RetainedCatalogSyncRead,
): RetainedCatalogSyncRead | null {
const catalogPath = readCodexCatalogPath();
if (catalogPath !== prepared.catalogPath) return null;
const evidence = retainedCatalogSyncEvidence(config, catalogPath, prepared.catalog);
if (evidence !== prepared.evidence) return null;
if (retainedCatalogProcessEvidence() !== prepared.processEvidence) return null;
return {
catalogPath,
catalog: JSON.parse(JSON.stringify(prepared.catalog)) as RawCatalog,
onDiskCatalog: readCatalog(catalogPath),
modelsCache: readCatalog(activeCodexModelsCachePath()),
evidence,
processEvidence: prepared.processEvidence,
};
}
function pristineCatalogBytes(read: RetainedCatalogSyncRead): string | null {
if (read.onDiskCatalog && !catalogHasRoutedEntries(read.onDiskCatalog)) {
try {
return readFileSync(read.catalogPath, "utf8");
} catch {
return null;
}
}
return catalogHasRoutedEntries(read.catalog)
? null
: `${JSON.stringify(read.catalog, null, 2)}\n`;
}
function catalogModelsForMergeWithNativeRecovery(
catalogPath: string,
catalog: RawCatalog,
onDiskCatalog: RawCatalog | null,
): RawEntry[] {
const primaryCatalogModels = onDiskCatalog?.models ?? catalog.models ?? [];
// Native-alias compatibility can omit disabled native rows from the effective catalog because
// Desktop's remote allowlist ignores `visibility: "hide"`. Keep current/pristine native recovery
// sources beside the on-disk rows so re-enabling a model restores its real metadata. Routed and
// user-authored rows still come only from the on-disk catalog.
return mergeCatalogModelsWithNativeRecovery(primaryCatalogModels, [
catalog.models ?? [],
readCatalogBackup(catalogPath)?.models ?? [],
]);
}
/** Merge retained rows, project confirmed account metadata, and publish only changed catalog bytes. */
function writeRetainedCatalogSync({
config,
goModels,
providerModelOutcomes,
comboOmissions,
read,
permit,
owningCodexHome,
modelEntitlements,
}: RetainedCatalogSyncWrite): RetainedCatalogSyncResult {
const { catalogPath, catalog, onDiskCatalog } = read;
const catalogModelsForMerge = catalogModelsForMergeWithNativeRecovery(
catalogPath,
catalog,
onDiskCatalog,
);
try {
// Once-only: preserve the PRISTINE pre-opencodex catalog as the native-priority baseline
// (later syncs would otherwise overwrite it with featured-modified priorities).
const pristine = pristineCatalogBytes(read);
if (pristine !== null) {
// Initialize metadata while the root is empty; never pre-claim the hashed path.
initializeConfigOwnership(getConfigDir());
publishHashedCodexCatalogBackup(permit, owningCodexHome, {
path: catalogBackupPathFor(catalogPath),
content: pristine,
});
if (isDefaultCatalogPath(catalogPath)) {
publishLegacyCodexCatalogBackup(permit, owningCodexHome, {
path: legacyCatalogBackupPath(),
content: pristine,
});
}
}
} catch { /* backup best-effort */ }
// Capture inheritance only after pristine backup preparation, before any row projection.
const template = captureNativeInheritanceTemplate(catalog, config.omitDisabledNativeModels === true);
// Hide disabled models from Codex, then feature the chosen subagent models (native OR routed)
// by giving them the lowest priority — see buildCatalogEntries for why priority, not array order.
const enabledGo = filterCatalogVisibleModels(goModels, config);
const featured = config.subagentModels ?? [];
const orderedGoModels = orderForSubagents(enabledGo, featured); // stable tie-break among equal priorities
const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(
config,
orderedGoModels,
catalogModelsForMerge,
);
const modelPickerOrder = config.modelPickerOrder ?? [];
const multiAgentMode: MultiAgentMode = resolveMultiAgentMode(config);
const exactComboSlugs = exactComboCatalogSlugs(config);
const bareEligibleAccountIds = providerCodexAccountMode(
OPENAI_CODEX_PROVIDER_ID,
config.providers[OPENAI_CODEX_PROVIDER_ID],
) === "direct" ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined;
const availableBareGatedNativeSlugs = availableAccountGatedNativeModels(
modelEntitlements,
bareEligibleAccountIds,
);
const availableAccountGatedNativeSlugs = availableAccountGatedNativeModels(modelEntitlements);
const availableBareNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
!ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableBareGatedNativeSlugs.has(slug)
));
const availableAccountNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
!ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableAccountGatedNativeSlugs.has(slug)
));
const unavailableGatedNativeSlugs = new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(slug => (
!availableBareGatedNativeSlugs.has(slug)
)));
// #4212: this set is the whole record of a model vanishing, and it is a set of strings that
// nothing downstream ever asks a question of. Explain it here, while the entitlement snapshot
// that produced it is still in scope, because after this point the model is simply absent and
// no later surface can tell "never entitled" apart from "the account broke this morning".
for (const slug of unavailableGatedNativeSlugs) {
const reason = gatedNativeReauthSuppressionReason({
snapshot: modelEntitlements,
slug,
eligibleAccountIds: bareEligibleAccountIds,
needsReauth: isAccountNeedsReauth,
label: accountId => gatedNativeAccountLabel(config, accountId),
});
if (reason) warnGatedNativeSuppressedOnce(slug, reason);
}
const suppressedBareNativeSlugs = new Set([
...desktopAllowlistSuppressedNativeSlugs(config),
...unavailableGatedNativeSlugs,
]);
// An omitted source still needs the same upgrade/normalization as a visible native.
// Keep independent combo-alias and entitlement suppression authoritative.
if (template && shouldUpgradeToUpstreamEntry(template)
&& (!ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(String(template.slug)) || availableBareGatedNativeSlugs.has(String(template.slug)))
&& !desktopAllowlistSuppressedNativeSlugs({ ...config, omitDisabledNativeModels: false }).has(String(template.slug))) {
suppressedBareNativeSlugs.delete(String(template.slug));
}
const hasPhysicalComboProvider = Object.hasOwn(config.providers, COMBO_NAMESPACE);
const includeNativeOpenAi = shouldIncludeNativeOpenAi(config);
const includeAccountBoundNativeOpenAi = shouldIncludeAccountBoundNativeOpenAi(config);
// Both user levers. Passing only the cap here is what let a per-model window the dashboard
// had accepted get written back at full width in the on-disk catalog.
const openaiContextCap = nativeContextLimits(config);
const accountSelectors = includeAccountBoundNativeOpenAi
? visibleCodexAccountSelectors(config)
: [];
const observedAccountNativeEntries = [
...(read.modelsCache?.models ?? []),
...(onDiskCatalog?.models ?? []).filter(entry =>
trustedAccountBoundNativeCatalogSlug(entry) !== undefined),
];
const accountTargets = new Map(codexAccountNamespaceEntries(config));
const reserveMainSelectors = accountSelectors.filter(selector =>
isMainCodexAccountTarget(accountTargets.get(selector) ?? ""));
// #4811: an omitted Reserve row carries no reason, so the explanation has to be emitted here,
// where the selector inputs that produced the omission are still in scope. Silent for every
// install that did not opt into authless Codex Desktop routing.
const reserveSuppression = reserveCatalogSuppressionReason(config, {
includeAccountBoundNativeOpenAi,
mainSelectors: reserveMainSelectors,
});
if (reserveSuppression) warnReserveSuppressedOnce(reserveSuppression);
// The active file can own a bare source even when the bundled catalog is the build base.
// A previously clamped qualified projection must not shorten a retained genuine ladder.
const reserveObservations = [
...(onDiskCatalog?.models ?? []),
...(read.modelsCache?.models ?? []),
...(catalog.models ?? []),
];
const retainedReserve = onDiskCatalog?.[RESERVE_SOURCE_CATALOG_FIELD];
const retainedReserveSource = retainedReserve && typeof retainedReserve === "object" && !Array.isArray(retainedReserve)
? observedReserveCatalogSource([retainedReserve as RawEntry], [])
: null;
const observedReserveSource = observedReserveCatalogSource(
// Cache invalidation carries historical bare observations alongside emitted models.
// Only unmarked observations are fresh enough to supersede the retained source.
reserveObservations.filter(entry => entry.slug === NATIVE_RESERVE_MODEL
&& entry.opencodex_account_observed_native === undefined), reserveMainSelectors,
) ?? retainedReserveSource ?? observedReserveCatalogSource(reserveObservations, reserveMainSelectors);
// This root is read only by OCX. Upstream ModelsResponse ignores unknown root fields.
// Retain before final runtime clamping: an omitted row must not turn into Luna next sync.
if (observedReserveSource) catalog[RESERVE_SOURCE_CATALOG_FIELD] = structuredClone(observedReserveSource);
else delete catalog[RESERVE_SOURCE_CATALOG_FIELD];
const lunaSource = upstreamNativeEntry(RESERVE_LUNA_METADATA_SOURCE);
const reserve = createReserveCatalogProjection(
config,
reserveMainSelectors,
observedReserveSource,
lunaSource ? finishUpstreamNativeEntry(lunaSource, 9, openaiContextCap) : null,
);
const accountNativeSlugsBySelector = accountSelectors.length > 0
? new Map([...accountBoundNativeOpenAiSlugsBySelector(config, observedAccountNativeEntries)].map(([selector, slugs]) => {
const target = accountTargets.get(selector);
const accountId = target && isMainCodexAccountTarget(target) ? MAIN_CODEX_ACCOUNT_ID : target;
return [selector, slugs.filter(slug => (
!ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug)
|| (accountId !== undefined
&& codexModelEntitlementStateForAccount(modelEntitlements, accountId, slug) === "granted")
))] as const;
}))
: new Map<string, readonly string[]>();
const accountNativeSlugs = accountSelectors.length > 0
? [...new Set([...accountNativeSlugsBySelector.values()].flatMap(slugs => [...slugs]))]
: [];
// Unknown account-native ids have no safe bare/global identity. They are only projected through
// the selector map above; the no-selector catalog remains the static native/API-key surface.
const observedNativeSlugs: string[] = [];
const wsEnabled = websocketsEnabled(config);
const multiAgentV2Enabled = isMultiAgentV2Enabled();
const goEntries = buildCatalogEntriesFromObservedState({
template: template ? JSON.parse(JSON.stringify(template)) : null,
gptSlugs: [],
goModels: orderedGoModels,
featured,
modelPickerOrder,
wsEnabled,
multiAgentMode,
exactComboSlugs,
accountSelectors,
suppressedBareNativeSlugs,
disabledNativeAccountSlugs: new Set(),
multiAgentV2Enabled,
openaiContextCap,
routedCatalogDefaults: resolveRoutedCatalogDefaults(config),
});
// Keep genuine native entries (gpt-*, codex-*) with their real per-model fields and append
// routed providers as namespaced slugs. Cursor and other adopted providers can expose model ids
// like `gpt-5.5`; those must not delete the native OpenAI/Codex base row.
const baselineCatalog = readCatalogBackup(catalogPath);
const baseline = readNativeBaseline(catalogPath);
const nativePinBaseline = nativeMultiAgentDefaults(baselineCatalog?.models);
const gatheredProviderNames = new Set(
Object.entries(config.providers ?? {})
.filter(([, prov]) => prov.disabled !== true)
.map(([name]) => name),
);
const degradedProviderNames = new Set(
providerModelOutcomes
.filter(outcome => outcome.state === "degraded")
.map(outcome => outcome.provider),
);
const selectedModelsByProvider = new Map<string, ReadonlySet<string>>(
Object.entries(config.providers ?? {}).flatMap(([name, provider]) => (
provider.disabled !== true
&& Array.isArray(provider.selectedModels)
&& provider.selectedModels.length > 0
? [[name, new Set(projectAntigravitySelectedModels(name, provider.selectedModels, goModels))] as const]
: []
)),
);
// Central WS capability override on the FINAL on-disk catalog (the file Codex reads). Applies to
// native AND routed so the advertised flag matches the implemented endpoint (phase 120.4) and a
// native template can never leak supports_websockets while the flag is off.
// #636: when the user only configured non-OpenAI providers (e.g. kimi), do not advertise
// bare gpt-* rows that hard-404 via NoEnabledOpenAiProviderError. Keep natives when no
// providers are configured yet (fresh install / catalog bootstrap tests).
const accountBoundEntries = includeAccountBoundNativeOpenAi && accountSelectors.length > 0
? buildCatalogEntriesFromObservedState({
template: template ? JSON.parse(JSON.stringify(template)) : null,
gptSlugs: availableAccountNativeSlugs,
goModels: [],
featured,
wsEnabled,
multiAgentMode,
exactComboSlugs,
accountSelectors,
suppressedBareNativeSlugs,
disabledNativeAccountSlugs: new Set([...disabledNativeSlugs(config)].filter(slug => suppressedBareNativeSlugs.has(slug))),
multiAgentV2Enabled,
keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
openaiContextCap,
accountNativeSlugs,
accountNativeSlugsBySelector,
reserve,
}).filter(entry => trustedAccountBoundNativeCatalogSlug(entry) !== undefined)
: [];
catalog.models = mergeCatalogEntriesFromObservedState({
ultraFastTier: ultraFastTierEnabled(config),
configuredUltraFastSlugs: configuredUltraFastSlugs(orderedGoModels),
retainedFlexPolicyBySlug: retainedFlexPolicyBySlug(config.providers ?? {}, catalogModelsForMerge, orderedGoModels),
modelPickerOrder,
accountSelectors,
catalogModels: catalogModelsForMerge,
baselineCatalogModels: baselineCatalog?.models ?? [],
routedEntries: goEntries,
baseline,
featured,
wsEnabled,
template,
disabledModels: new Set(config.disabledModels ?? []),
selectedModelsByProvider,
gatheredProviderNames,
pendingProviderNames: pendingModelSelectionProviders(config),
degradedProviderNames,
legacyCustomModelSlugs: legacyCustomModelCatalogSlugs(config),
multiAgentMode,
multiAgentV2Enabled,
keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
exactComboSlugs,
comboDescriptions: comboCatalogDescriptions(config),
hasPhysicalComboProvider,
includeNativeOpenAi,
accountBoundEntries,
suppressedBareNativeSlugs,
suppressedSyntheticMaxSlugs,
openaiContextCap,
nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
nativeMultiAgentDefaults: nativePinBaseline,
policy: {
...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],
warningPolicy: "emit",
},
});
applyNativeRosterMetadata(catalog.models, modelEntitlements, accountTargets, openaiContextCap, catalogModelsForMerge);
clampCatalogModelsToCodexSupport(catalog.models, { observedCatalog: bundledCodexCatalogSnapshot() });
finalizeAutoReviewModelOverride(catalog.models, catalogModelsForMerge, config);
advanceNativeInheritanceTemplate(catalog, catalog.models, shouldUpgradeToUpstreamEntry);
// Last mutation before serialization; see `enforceCatalogSlugUniqueness` for why the ordering
// against the effort clamp is load-bearing rather than cosmetic.
catalog.models = enforceCatalogSlugUniqueness(omitDisabledNativeCatalogEntries(catalog.models, config), true);
const added = goEntries.length + accountBoundEntries.length;
const content = `${JSON.stringify(catalog, null, 2)}\n`;
// A byte-identical rewrite is not a catalog change, but every mtime-keyed reader
// has to treat it as one. The app-server staleness classifier (#857) is the one
// that matters: it compares this file's mtime against each running Codex's start
// time, so an ordinary `ocx start` — or any dashboard action that re-syncs an
// unchanged model set — marked every already-running Codex as holding an outdated
// in-memory catalog. Since #1407 that verdict silences opencodex's own model
// guidance entirely (no preferred model, no roster) for the rest of that Codex's
// lifetime, so a configured injectionModel stops reaching the session even though
// nothing about the catalog changed. Skipping the no-op write keeps both the mtime
// and `catalogWritten` honest; `added` still reports the routed rows the catalog
// carries, because they are on disk either way.
const preparedCatalog: PreparedCatalogFileWrite = { path: catalogPath, content };
if (!preparedBytesDifferFromDisk(preparedCatalog)) {
return { added, path: catalogPath, catalogWritten: false, comboOmissions };
}
// A refresh may drop a provider's rows only when config.json on disk agrees the provider is gone.
// Without that, a config that is not the user's (missing or unreadable file read as defaults,
// another OPENCODEX_HOME) would publish a native-only catalog and exit cleanly (#6529).
const refused = (protectedRoutedNamespaces: number): RetainedCatalogSyncResult => ({
added: 0,
path: catalogPath,
catalogWritten: false,
comboOmissions,
skippedReason: "unbacked_routed_removal",
protectedRoutedNamespaces,
});
let replacement: CatalogFileReplacement | undefined;
const removal = unconfiguredRoutedRemoval(onDiskCatalog, catalog, config);
if (removal !== null) {
// Hold C (K -> C) from the config read through the replacement, so a save that enables one of
// these providers cannot land between the check and the write. A held C is a refusal too.
let backed = false;
try {
backed = withConfigMutationLockSync(() => {
if (!routedRemovalBackedByConfigFile(removal)) return false;
replacement = replaceActiveCodexCatalog(permit, owningCodexHome, preparedCatalog);
return replacement.kind !== "refused";
});
} catch (error) {
if (!(error instanceof ConfigMutationLockError)) throw error;
}
if (!backed) {
if (replacement?.kind !== "refused") {
auditRefusedCatalogReplacement(permit, owningCodexHome, preparedCatalog, "unbacked-routed-removal");
}
return refused(removal.namespaces.length);
}
} else {
replacement = replaceActiveCodexCatalog(permit, owningCodexHome, preparedCatalog);
if (replacement.kind === "refused") return refused(ocxRoutedNamespaceCounts(onDiskCatalog).size);
}
return {
added,
path: catalogPath,
catalogWritten: replacement?.kind === "written",
comboOmissions,
};
}
// Re-exported so the #4730 unit regression keeps importing the guard from the sync module it
// guards; the implementation lives in ./aggregation because the management convergence commit
// is the second writer that has to apply the identical rule.
export { dedupeCatalogEntriesBySlug };
export async function syncCatalogModels(
config: OcxConfig,
options?: CodexCatalogSyncOptions,
): Promise<RetainedCatalogSyncResult> {
if (pendingModelSelectionProviders(config).size) {
const { resolvePendingInitialModelSelection } = await import("../../providers/initial-model-selection-runtime");
await resolvePendingInitialModelSelection(config);
}
const owningCodexHome = getCodexHome();
// Settle before reading content and its matching evidence; no pre-refresh catalog is reused.
await loadBundledCodexCatalogAsync();
const preflightRead = readRetainedCatalogSync(config);
if (preflightRead === null) {
return {
added: 0,
path: readCodexCatalogPath(),
catalogWritten: false,
comboOmissions: [],
refreshOutcome: "refused",
};
}
const comboOmissions: ComboCatalogOmission[] = [];
const providerModelOutcomes: CatalogGatherProviderModelOutcome[] = [];
// Settle the bundled template, then baseline, and only then await. Reading it
// here makes the memo ours before anyone else can move it, so a bundled swap
// during the await is an outside change rather than our own side effect.
//
// The persisted runtime selection is covered by the filesystem evidence above
// rather than by a process epoch; see `retainedCatalogProcessEvidence` for why
// the in-memory runtime memo cannot be baselined honestly from this path.
const prepared: RetainedCatalogSyncRead = {
...preflightRead,
evidence: retainedCatalogSyncEvidence(config, preflightRead.catalogPath, preflightRead.catalog),
processEvidence: retainedCatalogProcessEvidence(),
};
const discoveryBaseline = captureModelDiscoveryBaseline(config);
const providerContentRevisions = new Map<string, string>();
const [goModels, modelEntitlements] = await Promise.all([
gatherRoutedModels(config, {
comboOmissions,
providerModelOutcomes,
providerContentRevisions,
}),
resolveAdmittedCodexModelEntitlements(config),
]);
const committed = withCatalogWriteSerialization(owningCodexHome, permit => {
// Desired state can flip OFF during the provider await above. The catalog
// evidence revalidation below cannot see that — intent lives in our config,
// not in the catalog files — so the policy is re-read here, under K, right
// before the only write. A lost race becomes the discriminated skip instead
// of a routed catalog/cache surviving a completed disable. An explicit
// catalog-only sync opts out of that gate: the user asked for a refresh even
// when injection is OFF, and the toggle only protects config/history writes.
if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) {
return {
added: 0,
path: prepared.catalogPath,
catalogWritten: false,
comboOmissions,
skippedReason: "desired_disabled" as const,
};
}
const current = revalidateRetainedCatalogSync(config, prepared);
if (current === null) return null;
if (!isCodexModelEntitlementSnapshotCurrent(modelEntitlements)) return null;
// Revalidate before adopting discovery: its scoped config mutation would otherwise
// invalidate our own evidence. K -> C is the catalog/config lock order.
if (!finalizeModelDiscovery(config, discoveryBaseline, goModels,
providerModelOutcomes.filter(outcome => outcome.state === "authoritative").map(outcome => outcome.provider),
providerContentRevisions)) return null;
return writeRetainedCatalogSync({
config,
goModels,
providerModelOutcomes,
comboOmissions,
read: current,
permit,
owningCodexHome,
modelEntitlements,
});
}, { intent: "refresh", writer: "retained-sync" });
if (committed.kind === "completed" && committed.value !== null) {
return {
...committed.value,
refreshOutcome: committed.value.skippedReason ? "refused" : "committed",
};
}
return {
added: 0,
path: prepared.catalogPath,
catalogWritten: false,
comboOmissions,
refreshOutcome: "refused",
...(committed.kind === "unavailable" && committed.reason === "foreign-owner"
? { skippedReason: "foreign_owner" as const } : {}),
...(committed.kind === "unavailable" && committed.reason === "owner-unknown"
? { skippedReason: "owner_unknown" as const } : {}),
};
}
export type CodexCacheInvalidationOutcome = "written" | "unchanged" | "missing_catalog" | "desired_disabled" | "failed";
export function invalidateCodexModelsCacheWithPermitOutcome(
permit: CatalogWritePermit,
owningCodexHome: string,
options?: CodexCatalogSyncOptions,
): CodexCacheInvalidationOutcome {
try {
// This permit is a REACQUISITION: refreshCodexModelCatalog's commit released
// K before this rewrite runs, so the commit-path desired-state check cannot
// cover it. A disable landing in that gap must not be overwritten by a
// routed cache write — re-read intent under this permit, same as the commit.
// The catalog-only sync override applies here too so an explicit refresh
// keeps the cache consistent with the catalog it just wrote.
if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) return "desired_disabled";
const catalogPath = readCodexCatalogPathForHome(owningCodexHome);
if (!existsSync(catalogPath)) return "missing_catalog";
const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
const models = catalog.models ?? catalog;
const cachePath = join(owningCodexHome, "models_cache.json");
const currentCache = readCatalog(cachePath);
const existingSlugs = new Set(models.flatMap((entry: RawEntry) =>
typeof entry.slug === "string" ? [entry.slug] : []));
const currentConfig = loadConfig();
const mainSelectors = visibleCodexAccountSelectors(currentConfig).filter(selector => {
const target = new Map(codexAccountNamespaceEntries(currentConfig)).get(selector);
return isMainCodexAccountTarget(target ?? "");
});
const observedAccountModels = observedAccountBoundNativeEntries(currentCache?.models ?? [])
.filter(entry => {
const slug = typeof entry.slug === "string" ? entry.slug : "";
return !existingSlugs.has(slug);
})
.map(entry => ({
...entry,
// Keep the observation in Codex's cache without advertising a new bare picker row. The
// next OpenCodex catalog sync consumes this marker and creates only selector-qualified
// rows for the currently configured public account selectors.
visibility: "hide",
opencodex_account_observed_native: true,
opencodex_account_observed_selectors: mainSelectors,
}));
const wrapper = {
fetched_at: "2000-01-01T00:00:00Z",
client_version: "0.0.0",
models: [...models, ...observedAccountModels],
};
const preparedCache: PreparedCatalogFileWrite = {
path: cachePath,
content: `${JSON.stringify(wrapper, null, 2)}\n`,
};
// The same no-op rule the active catalog already applies (#1459), for the same
// reason and at the second writer that has to obey it.
//
// This function is what `refreshCodexModelCatalog` reports as `cacheSynced`, and
// `handleStart` ORs that into the stale-app-server warning. Rewriting identical
// bytes bumped this file's mtime and returned `true`, so on a start where the
// catalog reproduced byte-identically — the settled case — the warning still
// claimed "Disk catalog/cache were updated" and told the operator their Codex
// model list might be stale, when nothing on disk had changed and Codex held the
// same model set the file already described. Returning `false` here makes
// `cacheSynced` mean what its name and its consumers already assume, and what
// `pullRemoteCatalog` and the early returns in `refreshCodexModelCatalog`
// already assert: a write happened.
return replaceCodexModelsCache(permit, owningCodexHome, preparedCache).kind;
} catch {
return "failed";
}
}
export function invalidateCodexModelsCacheWithPermit(
permit: CatalogWritePermit,
owningCodexHome: string,
options?: CodexCatalogSyncOptions,
): boolean {
return invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, options) === "written";
}
export function invalidateCodexModelsCache(options?: CodexCatalogSyncOptions): boolean {
const owningCodexHome = getCodexHome();
const outcome = withCatalogWriteSerialization(
owningCodexHome,
permit => invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, options),
{ intent: "cache", writer: "cache-invalidate" },
);
return outcome.kind === "completed" && outcome.value;
}