@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
877 lines (853 loc) • 49.3 kB
text/typescript
/**
* The `/api/models` row list and its projection into export models.
*
* Extracted from model-routes.ts so `/api/client-config` and the integration
* routes read the SAME visible-model list. Two callers computing "which models
* does this user actually have" independently is how the export and the toggle
* would quietly disagree about what a client was told.
*
* Bodies are unchanged from their previous home; only `export` was added.
*/
import type { CatalogModel } from "../../codex/catalog";
import { antigravityFamilyDisabled } from "../../providers/antigravity-effort-families";
import { expireModelCache, getProviderDiscoveryStatus, observeModelCacheRevision } from "../../codex/model-cache";
import { isPassiveRead } from "../../lib/passive-read";
import {
captureExportConfigAdmission,
detachedConfigSnapshot,
isExportConfigAdmissionCurrent,
type ExportConfigAdmission,
} from "../../config/admitted-identity";
import {
catalogModelSlug,
filterCatalogVisibleModels,
accountBoundNativeOpenAiSlugsBySelector,
nativeDefaultReasoningEffort,
NATIVE_OPENAI_MODELS,
nativeInputModalities,
nativeModelRows,
nativeReasoningEfforts,
uniqueCatalogModelsForPublicList,
shouldIncludeAccountBoundNativeOpenAi,
catalogModelEfforts,
} from "../../codex/catalog";
import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../../codex/catalog/native-models";
import {
knownReasoningSupport,
knownToolsSupport,
type EffectiveModelExportMetadata,
type ExportModel,
} from "../../clients/config-export/contracts";
import { customRowExportMetadata } from "./model-row-export-metadata";
import { attachExportAliasSelectors } from "../../clients/config-export/alias-selectors";
import { attachNestedSelectors } from "../../clients/config-export/nested-selectors";
import { resolveExportReasoningAxes } from "../../clients/config-export/reasoning-metadata";
import { providerContextCap } from "../../providers/context-cap";
import { isVisionReasoningEffort, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
import { routedSlug, slugEquals } from "../../providers/slug-codec";
import type { OcxConfig } from "../../types";
import { enrichProviderFromRegistry } from "../../providers/derive";
import { ensureCodexEntitlementFreshness } from "../../codex/model-entitlements";
import { fetchAllModels } from "./shared";
import { CatalogGatherBusyError, gatherRoutedModels, type GatherRoutedModelsOptions } from "../../codex/catalog/routed-gather";
import { isProviderDiscoveryInFlight, withProviderDiscoveryInFlight } from "../../codex/catalog/provider-models";
import { captureModelDiscoveryBaseline, finalizeModelDiscovery } from "../../providers/new-model-policy-runtime";
import { reconcileSuccessfulModelDiscoveries } from "../../providers/new-model-policy";
import { initialModelSelectionPending, pendingModelSelectionProviders } from "../../providers/initial-model-selection";
import { captureInitialSelectionBaseline, finalizeInitialModelSelection } from "../../providers/initial-model-selection-runtime";
import { catalogFastRowEligible, fastRowId } from "../fast-row";
import { knownEffortRowIds } from "../effort-row";
import { visionSidecarConsumerClassifier } from "../../vision/eligibility";
/** Admit one manual discovery without joining work started by any caller. */
export async function refreshProviderDiscovery(config: OcxConfig, name: string) {
const provider = config.providers[name];
if (!provider || provider.disabled || provider.adapter === "jev-decision") return undefined;
if (isProviderDiscoveryInFlight(name)) return "in-progress" as const;
if (!expireModelCache(name)) return getProviderDiscoveryStatus(name);
return withProviderDiscoveryInFlight(name, async () => {
const baseline = captureModelDiscoveryBaseline(config);
const initial = initialModelSelectionPending(provider) ? captureInitialSelectionBaseline(config) : null;
const outcomes: NonNullable<GatherRoutedModelsOptions["providerModelOutcomes"]> = [];
const revisions = new Map<string, string>();
const models = await gatherRoutedModels(config, {
onlyProvider: name, providerModelOutcomes: outcomes, providerContentRevisions: revisions,
});
// A later full gather can start while this action runs. Its publication is not this action's receipt.
if (observeModelCacheRevision(name) !== revisions.get(name)) return undefined;
const discovery = getProviderDiscoveryStatus(name);
if (discovery?.status === "ok" && outcomes.some(outcome => outcome.state === "authoritative")) {
if (initial) finalizeInitialModelSelection(config, { ...initial, providers: [name] },
uniqueCatalogModelsForPublicList(models), [name]);
if (!finalizeModelDiscovery(config, baseline, models, [name], revisions)) throw new CatalogGatherBusyError();
}
return discovery;
});
}
/**
* One row of the `/api/models` list. Routed rows spread a `CatalogModel`, so the shape is
* that model plus the identity/visibility fields this boundary computes for every row
* regardless of source. `disabled` is always present; the rest vary by row origin.
*/
export type ManagementModelRow = Partial<CatalogModel> & {
provider: string;
id: string;
namespaced: string;
disabled: boolean;
initialSelectionPending?: boolean;
native?: boolean;
custom?: boolean;
customId?: string;
manualPricing?: boolean;
fastRowAvailable?: boolean;
displayNameOverride?: string;
displayNameSource?: "operator" | "provider" | "fallback";
/**
* The modality declaration a per-model editor writes, read from the same sources the runtime
* consults. It is separate from the row's own `inputModalities` because that one is the
* CATALOG value: an editor that pre-fills from the catalog while writing the declaration shows
* one thing and saves another, so its own writes never appear to take.
*/
inputModalitiesDeclared?: string[];
/**
* The runtime's verdict on whether the Vision Sidecar describes this model's images, from
* the same predicate the request path consults (legacy `noVisionModels`, registry
* enrichment, explicit declarations, custom rows). `inputModalitiesDeclared` cannot answer
* this: a model covered ONLY by legacy `noVisionModels` has no declaration while its
* advertised modalities are widened to image, so a client inferring consumer status from
* declared-vs-advertised modalities misclassifies the row after reload.
*/
visionSidecarConsumer?: boolean;
/** Exact stored context override, distinct from the effective catalog window. */
contextWindowDeclared?: number;
/**
* True when the provider config actually CHANGES reasoning for this model. A persisted key is
* not proof of an operator edit — OpenCodex itself writes the registry ladder into the provider
* config — so this compares values against what the model would inherit anyway.
*/
reasoningOverridden?: boolean;
/**
* Tool support a canonical source positively asserts (native identity, a catalog row's
* `"tools"` capability, or the parallel-call opt-in — the same evidence
* `src/routing/capability.ts` counts). A row without positive evidence stays absent:
* unknown is not false.
*/
supportsTools?: boolean;
/**
* A canonical source's explicit capability, or positive evidence from reasoning efforts
* or delivered summaries. Absent means unknown; an empty ladder alone says only that
* effort is not adjustable, not that the model cannot reason.
*/
supportsReasoning?: boolean;
/**
* Effective export projection for a row, resolved from canonical sources only — for a
* custom row the full effective view (the raw override fields above stay exactly what the
* editor wrote), for routed and native rows the authoritative declared default where the
* row's own `defaultReasoningEffort` is the picker's preference order instead. Additive on
* `/api/models`, and its PRESENCE is the authority signal: an absent field inside it means
* "no declared value", never "fall back to the row".
*/
exportMetadata?: EffectiveModelExportMetadata;
};
/** Resolve the exact text and source shown for one routed discovered model. */
export function effectiveManagementDisplayName(
config: Pick<OcxConfig, "providers">,
model: CatalogModel,
): Pick<ManagementModelRow, "displayName" | "displayNameOverride" | "displayNameSource"> {
const provider = config.providers[model.provider];
const configured = provider?.modelDisplayNames;
if (configured && Object.hasOwn(configured, model.id)) {
const displayName = configured[model.id]?.trim();
if (displayName) {
return { displayName, displayNameOverride: displayName, displayNameSource: "operator" };
}
}
const providerDisplayName = model.displayName?.trim();
if (providerDisplayName) return { displayName: providerDisplayName, displayNameSource: "provider" };
return { displayName: catalogModelSlug(model), displayNameSource: "fallback" };
}
/**
* The modality declaration an editor writes, resolved the way the runtime resolves it: an exact
* `modelCapabilities` entry first, then the legacy `modelInputModalities` record, both after the
* registry has filled in whatever the saved config predates.
*/
export function declaredModelInputModalities(
config: OcxConfig,
providerName: string,
modelId: string,
): string[] | undefined {
const provider = config.providers[providerName];
if (!provider) return undefined;
const enriched = {
...provider,
...(provider.modelInputModalities ? { modelInputModalities: { ...provider.modelInputModalities } } : {}),
...(provider.modelCapabilities ? { modelCapabilities: { ...provider.modelCapabilities } } : {}),
};
enrichProviderFromRegistry(providerName, enriched);
const declared = enriched.modelCapabilities?.[modelId]?.inputModalities
?? modelRecordValue(enriched.modelInputModalities, modelId);
return Array.isArray(declared) && declared.length > 0 ? [...declared] : undefined;
}
/**
* The ladder that actually applies to this model: an explicit declaration wins, then the
* registry-enriched provider map, then the pinned native OpenAI table for a resold native id,
* then the catalog's own effort hints.
*
* The registry enrichment is not optional. The catalog reads the enriched provider, so a registry
* declaration (google-antigravity's `gemini-3.8-flash`, for one) IS the model's ladder; reading
* the saved config alone would report no ladder for a model that has one.
*
* The catalog's own hints are the one source that costs a file read per lookup. `catalogLadders`
* is the batched form of it: a roster projection resolves every routed id once and passes the map
* down, instead of asking `catalogModelEfforts` per row and re-parsing the same file each time.
* Omitting it keeps the single-model behaviour for every other caller.
*/
export type CatalogLadderLookup = ReadonlyMap<string, string[]>;
/** Catalog entries for routed rows carry the Codex-facing `provider/model` slug, never the bare id. */
function catalogLadder(ladders: CatalogLadderLookup | undefined, providerName: string, modelId: string): string[] | undefined {
const slug = routedSlug(providerName, modelId);
return ladders ? ladders.get(slug) : catalogModelEfforts([slug]).get(slug);
}
export function effectiveModelReasoningEfforts(config: OcxConfig, providerName: string, modelId: string, declaredEfforts?: string[], catalogLadders?: CatalogLadderLookup): string[] | undefined {
// An empty array is a declaration, not an absence: the operator stored "this model has no
// reasoning rungs", and falling through to the inherited ladder here would report a ladder the
// row does not have and hand it back to the editor on the next refresh.
if (Array.isArray(declaredEfforts)) return declaredEfforts;
const provider = config.providers[providerName];
if (provider) {
const enriched = {
...provider,
...(provider.modelReasoningEfforts ? { modelReasoningEfforts: { ...provider.modelReasoningEfforts } } : {}),
};
enrichProviderFromRegistry(providerName, enriched);
const raw = modelRecordValue(enriched.modelReasoningEfforts, modelId) ?? enriched.reasoningEfforts;
// Mirrors `configuredReasoningEfforts`, the reader the wire actually uses: a stored array is a
// declaration even when it sanitizes down to nothing, and only a missing entry inherits.
if (Array.isArray(raw)) return sanitizeCodexReasoningEfforts(raw) ?? [];
}
// A provider reselling a native OpenAI id inherits that model's pinned ladder.
if (SUPPORTED_NATIVE_OPENAI_SLUGS.has(modelId)) {
const native = nativeReasoningEfforts(modelId);
if (native.length > 0) return native;
}
const hits = catalogLadder(catalogLadders, providerName, modelId);
if (hits && hits.length > 0) return hits;
return undefined;
}
export function effectiveModelDefaultReasoningEffort(config: OcxConfig, providerName: string, modelId: string, declaredDefault?: string, efforts?: string[]): string | undefined {
if (declaredDefault) return declaredDefault;
const provider = config.providers[providerName];
if (provider) {
const stored = modelRecordValue(provider.modelDefaultReasoningEfforts, modelId);
if (stored) return stored;
}
if (efforts && efforts.length > 0) {
// The default is the ladder's own preference order, not its first entry: a model offering
// low..high defaults to medium, and only a ladder that omits it falls back to low.
if (efforts.includes("medium")) return "medium";
if (efforts.includes("low")) return "low";
return efforts[0];
}
return undefined;
}
/**
* Whether the saved config really overrides reasoning for this model, decided by VALUE rather
* than by key presence.
*
* The distinction is the whole point: OpenCodex writes the registry ladder (and its default) into
* the provider config itself, so a bare `hasOwnProperty` test reports every registry-declared
* model as hand-edited. An entry that resolves to the same ladder and default the model would
* inherit anyway is not an override, and an editor that pre-fills an "override" checkbox from one
* claims an edit nobody made.
*/
export function reasoningOverrideFor(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): boolean {
const provider = config.providers[providerName];
if (!provider) return false;
const owns = (record: Record<string, unknown> | undefined) =>
!!record && Object.prototype.hasOwnProperty.call(record, modelId);
const ownsEfforts = owns(provider.modelReasoningEfforts as Record<string, unknown> | undefined);
const ownsDefault = owns(provider.modelDefaultReasoningEfforts as Record<string, unknown> | undefined);
if (!ownsEfforts && !ownsDefault) return false;
if (ownsEfforts) {
// `undefined` (nothing known) and `[]` (pinned to no rungs) are different facts, and joining
// both to "" would report a pinned-empty ladder as no override at all.
const ladderKey = (values: string[] | undefined) => (values === undefined ? null : values.join(","));
const effective = effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders);
const inherited = inheritedModelReasoningEfforts(config, providerName, modelId, catalogLadders);
if (ladderKey(effective) !== ladderKey(inherited)) return true;
}
if (ownsDefault) {
const effective = effectiveModelDefaultReasoningEffort(config, providerName, modelId);
const inherited = inheritedModelDefaultReasoningEffort(config, providerName, modelId, catalogLadders);
if (effective !== inherited) return true;
}
return false;
}
/** The ladder this model inherits when no per-model override exists. */
export function inheritedModelReasoningEfforts(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): string[] | undefined {
const provider = config.providers[providerName];
if (!provider) return undefined;
const record = provider.modelReasoningEfforts;
if (!record || !Object.prototype.hasOwnProperty.call(record, modelId)) {
return effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders);
}
const next = { ...record };
delete next[modelId];
const stripped = { ...provider, modelReasoningEfforts: next };
const view = { ...config, providers: { ...config.providers, [providerName]: stripped } };
return effectiveModelReasoningEfforts(view, providerName, modelId, undefined, catalogLadders);
}
/** The default this model inherits when no per-model default override exists. */
export function inheritedModelDefaultReasoningEffort(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): string | undefined {
const provider = config.providers[providerName];
if (!provider) return undefined;
const record = provider.modelDefaultReasoningEfforts;
if (!record || !Object.prototype.hasOwnProperty.call(record, modelId)) {
return effectiveModelDefaultReasoningEffort(
config, providerName, modelId, undefined, effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders),
);
}
const next = { ...record };
delete next[modelId];
const stripped = { ...provider, modelDefaultReasoningEfforts: next };
const view = { ...config, providers: { ...config.providers, [providerName]: stripped } };
return effectiveModelDefaultReasoningEffort(
view, providerName, modelId, undefined, effectiveModelReasoningEfforts(view, providerName, modelId, undefined, catalogLadders),
);
}
/**
* The exact row list `/api/models` returns. Extracted so `/api/client-config` exports the
* models the GUI's Models tab shows — including this function's `disabled` computation,
* which the export core (src/clients/config-export.ts) deliberately does not perform.
*/
export async function listManagementModelRows(
config: OcxConfig,
options: {
entitlementWaitMs?: number;
models?: readonly CatalogModel[];
allowSuperseded?: boolean;
/** Filled with each provider's content revision as of the moment its rows were chosen. */
providerContentRevisions?: Map<string, string>;
} = {},
): Promise<ManagementModelRow[]> {
/*
* A supplied roster skips the gather, and that is the point rather than an optimization.
* `fetchAllModels` reaches providers and can persist an initial model selection, which a
* read-only caller must not do. Everything below this line is the projection — the disabled
* computation, native and account-bound rows, custom rows and the public list — so a caller
* that brings its own roster still sees exactly what a writer would, and the two cannot
* disagree about the roster for any reason except the roster itself.
*/
// A passive read (#6959) also skips the entitlement refresh, which reaches the Codex accounts.
const models = options.models === undefined
? isPassiveRead() ? [] : (await Promise.all([
fetchAllModels(config, {
providerContentRevisions: options.providerContentRevisions,
allowSuperseded: options.allowSuperseded,
publishProjection: projection => { config = projection; },
}),
ensureCodexEntitlementFreshness(config, {
waitMs: options.entitlementWaitMs ?? 3_000,
}),
]))[0]
: [...options.models];
const disabled = new Set(config.disabledModels ?? []);
// Native GPT passthrough rows lead (provider "openai", bare-slug namespaced ids): sourced
// from the static supported set so a disabled model stays listed and re-enableable.
const nativeRows = nativeModelRows(config).map(row => ({ ...row, metadataSlug: row.slug }));
const accountNativeRows = shouldIncludeAccountBoundNativeOpenAi(config)
? [...accountBoundNativeOpenAiSlugsBySelector(config).entries()].flatMap(([selector, slugs]) =>
slugs
.filter(slug => !NATIVE_OPENAI_MODELS.includes(slug))
.map(slug => ({
slug: `${selector}/${slug}`,
metadataSlug: slug,
disabled: disabled.has(`${selector}/${slug}`) || disabled.has(slug),
contextWindow: undefined,
maxInputTokens: undefined,
autoCompactTokenLimit: undefined,
})))
: [];
const native: ManagementModelRow[] = [...nativeRows, ...accountNativeRows].map(row => {
const reasoningEfforts = nativeReasoningEfforts(row.metadataSlug).filter(isVisionReasoningEffort);
const defaultReasoningEffort = nativeDefaultReasoningEffort(row.metadataSlug);
const labels = config.providers.openai?.modelDisplayNames;
const displayName = row.slug === row.metadataSlug && labels && Object.hasOwn(labels, row.slug)
? labels[row.slug]?.trim() : undefined;
return {
provider: "openai",
id: row.slug,
namespaced: row.slug,
disabled: row.disabled,
native: true,
...(displayName ? { displayName, displayNameOverride: displayName, displayNameSource: "operator" as const } : {}),
reasoningEfforts,
...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
inputModalities: nativeInputModalities(row.slug),
...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
// The input ceiling is a separate number from the window for GPT-5.6 (922k under
// 1.05M). Dropping it here made /api/models describe a native row as if the whole
// window were usable as input, which is the claim the measurement disproved.
...(row.maxInputTokens !== undefined ? { maxInputTokens: row.maxInputTokens } : {}),
...(row.autoCompactTokenLimit !== undefined
? { autoCompactTokenLimit: row.autoCompactTokenLimit }
: {}),
// The pinned default above IS the declared default for a native row — no heuristic
// touches it — so the authoritative projection carries it verbatim and exists even
// when empty, which is what tells an export consumer "absence means no default"
// rather than "fall back to the row".
exportMetadata: {
...(defaultReasoningEffort !== undefined ? { defaultReasoningEffort } : {}),
},
};
});
const customModels: ManagementModelRow[] = (config.customModels ?? []).map(cm => {
const namespaced = routedSlug(cm.provider, cm.modelId);
return {
provider: cm.provider,
id: cm.modelId,
namespaced,
disabled: [...disabled].some(stored => slugEquals(stored, cm.provider, cm.modelId)),
custom: true,
customId: cm.id,
displayName: cm.displayName,
...(cm.contextWindow ? { contextWindow: cm.contextWindow } : {}),
...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
// Stored override, not the inherited ladder: the edit dialog must show what the user
// set (including an explicit empty "no reasoning" ladder), not what the provider row
// happens to advertise today.
...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
// The stored default rides along so a client reloading /api/models can restore the
// full edit state; the GUI has no default-effort control today, but dropping it here
// would make any future PUT-based edit lose it silently.
...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
};
});
const publicModels = uniqueCatalogModelsForPublicList(models);
// Custom rows below are REBUILT from config.customModels rather than spread from a
// CatalogModel, so every field gather computed for the same slug has to be carried across by
// hand. Without this a custom model whose provider is out of credit would be the one row on
// the page that never shows as inactive (#1711), because the gather-derived row it replaces
// is dropped by the slug dedup below.
const quotaInactiveByNamespaced = new Map(
publicModels
.filter(model => model.quotaInactiveReason !== undefined)
.map(model => [catalogModelSlug(model), model.quotaInactiveReason!] as const),
);
const comboNamespaced = new Set(
publicModels.filter(model => model.provider === "combo").map(catalogModelSlug),
);
const visibleCustomModels = customModels
.filter(model => !comboNamespaced.has(model.namespaced))
.map(model => {
const quotaInactiveReason = quotaInactiveByNamespaced.get(model.namespaced);
return quotaInactiveReason ? { ...model, quotaInactiveReason } : model;
});
// Custom metadata wins when a physical live/static row resolves to the same Codex-facing
// slug, while a combo keeps the same precedence it has in routing and /v1/models.
const customNamespaced = new Set(visibleCustomModels.map(c => c.namespaced));
// One catalog read for the whole roster. Every `catalogModelEfforts` call parses the catalog
// file and scans it once per requested slug, so resolving these per row (and twice per row, as
// the guard and the value) re-read the same file thousands of times on a large roster.
const routedSlugs = publicModels.filter(m => m.provider !== "combo").map(m => routedSlug(m.provider, m.id));
const catalogLadders = catalogModelEfforts([...new Set(routedSlugs)]);
// The gathered roster, keyed once by Codex-facing slug. A custom row looks itself up here —
// the gather materializes custom rows with the provider/native inheritance the catalog
// publishes, so this is the canonical resolved metadata the export must preserve, and no
// per-model fetch ever happens to obtain it.
const rosterByNamespaced = new Map(publicModels.map(model => [catalogModelSlug(model), model] as const));
const customRowsWithExportMetadata = visibleCustomModels.map(model => {
const catalogRow = rosterByNamespaced.get(model.namespaced);
// The gathered materialization's ladder is authoritative when it has one: it already
// folded the explicit override in and then applied the canonical bounds (the native
// clamp for a capability-backed id, learned refusals), so re-declaring the raw override
// here would undo a bound. Two raw values still win: the explicit empty ladder — "no
// rungs" is an operator statement no normalization may fill in, even against a stale
// gathered row — and any override with no gathered ladder behind it.
const declaredEfforts = Array.isArray(model.reasoningEfforts) && model.reasoningEfforts.length === 0
? model.reasoningEfforts
: catalogRow?.reasoningEfforts !== undefined
? catalogRow.reasoningEfforts
: model.reasoningEfforts;
return {
...model,
exportMetadata: customRowExportMetadata(
config,
model,
catalogRow,
effectiveModelReasoningEfforts(config, model.provider, model.id, declaredEfforts, catalogLadders),
),
};
});
const dedupedRouted = publicModels.map((m): ManagementModelRow | null => {
// Codex-facing slug (one "/", slug-codec); disabledModels compares tolerate both forms.
const namespaced = catalogModelSlug(m);
if (m.provider !== "combo" && customNamespaced.has(namespaced)) return null;
const contextCap = providerContextCap(config, m.provider);
const nativeAlias = m.provider === "combo" && m.nativeAlias === true;
const displayName = effectiveManagementDisplayName(config, m);
const routed = m.provider !== "combo";
// Resolved once each: the spread below used to evaluate the same helpers again for the guard.
const reasoningEfforts = routed
? m.supportsReasoningEffort === false || m.supportsReasoning === false ? []
: effectiveModelReasoningEfforts(config, m.provider, m.id, m.reasoningEfforts, catalogLadders)
: undefined;
const defaultReasoningEffort = routed
&& m.supportsReasoningEffort !== false && m.supportsReasoning !== false
? effectiveModelDefaultReasoningEffort(config, m.provider, m.id, m.defaultReasoningEffort, reasoningEfforts)
: undefined;
const inputModalitiesDeclared = routed ? declaredModelInputModalities(config, m.provider, m.id) : undefined;
const contextWindowDeclared = routed ? config.providers[m.provider]?.modelContextWindows?.[m.id] : undefined;
return {
...m,
...displayName,
namespaced,
disabled: antigravityFamilyDisabled(config, m, models) || [...disabled].some(stored => (
(!nativeAlias && stored === namespaced) || slugEquals(stored, m.provider, m.id)
)),
...(contextCap !== undefined ? { contextCap, contextCapped: m.contextCapped === true } : {}),
// A routed row inherits nothing about reasoning or modalities from the row spread above:
// the catalog only carries what discovery reported, so the effective answers are resolved
// here, where the config and the registry are both in hand.
...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
...(defaultReasoningEffort !== undefined ? { defaultReasoningEffort } : {}),
...(routed ? { reasoningOverridden: reasoningOverrideFor(config, m.provider, m.id, catalogLadders) } : {}),
...(inputModalitiesDeclared !== undefined ? { inputModalitiesDeclared } : {}),
...(contextWindowDeclared !== undefined ? { contextWindowDeclared } : {}),
// The authoritative export default is the GATHERED row's own declared default — never
// the picker value above, whose medium → low → first fallback invents a default no
// source declared. The object exists even when empty: its presence is what tells
// `toExportModel` and the CLI that an absent default means "no default", not "fall
// back to the row". A default outside the effective ladder is dropped for the same
// reason the settings route rejects one: the proxy would never send it.
exportMetadata: {
...(m.defaultReasoningEffort !== undefined
&& (reasoningEfforts === undefined || reasoningEfforts.includes(m.defaultReasoningEffort))
? { defaultReasoningEffort: m.defaultReasoningEffort }
: {}),
},
};
}).filter((row): row is ManagementModelRow => row !== null);
// Manual OpenAI rows retain their routed selector but replace the bare dashboard row.
// Account-qualified rows remain distinct, explicitly selected routes.
const visibleNative = native.filter(model => model.id.includes("/")
|| !customNamespaced.has(routedSlug(model.provider, model.id)));
const rows = [...visibleNative, ...dedupedRouted, ...customRowsWithExportMetadata];
// Include disabled rows and configured aliases before the export visibility filter:
// a hidden real `x--fast` must never become a synthetic selector for another model.
const knownIds = config.fastRows === false ? new Set<string>() : knownEffortRowIds(config);
for (const row of rows) knownIds.add(row.namespaced);
const isVisionSidecarConsumer = visionSidecarConsumerClassifier(config);
return rows.map(row => {
const pending = initialModelSelectionPending(config.providers[row.provider]);
const modelCosts = Object.hasOwn(config.providers, row.provider)
? config.providers[row.provider]?.modelCosts : undefined;
// Derived once here so the wire row carries the same booleans the export projection
// serializes; the CLI reads /api/models and cannot re-derive them without duplicating
// this policy. Custom rows read their effective view from `exportMetadata`; routed and
// native rows read their own evidence.
const supportsTools = row.exportMetadata?.supportsTools
?? row.supportsTools
?? knownToolsSupport({
capabilities: row.capabilities,
parallelToolCalls: row.parallelToolCalls,
native: row.native,
});
const supportsReasoning = row.exportMetadata?.supportsReasoning
?? row.supportsReasoning
?? knownReasoningSupport(row);
return {
...row,
// One shared definition with the request path: the GUI must not re-derive consumer
// status from declared-vs-advertised modalities (see the field doc above).
visionSidecarConsumer: isVisionSidecarConsumer(row.provider, row.id),
...(!row.native && modelCosts !== undefined && Object.hasOwn(modelCosts, row.id)
? { manualPricing: true } : {}),
...(pending ? { disabled: true, initialSelectionPending: true } : {}),
fastRowAvailable: !row.disabled && !pending
&& !knownIds.has(fastRowId(row.namespaced)) && catalogFastRowEligible(config, row),
// An explicit false survives; derivation itself is true-or-nothing.
...(typeof supportsTools === "boolean" ? { supportsTools } : {}),
...(typeof supportsReasoning === "boolean" ? { supportsReasoning } : {}),
};
});
}
/**
* `/api/models` row → the narrower input the client-config serializers accept.
*
* A row's `exportMetadata`, when present, is the authority: custom rows project through it
* because their own fields are stored overrides (an absent field means "not overridden"),
* and routed/native rows carry the declared default in it because the row-level
* `defaultReasoningEffort` is the picker's preference order, whose medium → low → first
* fallback fabricates a default no source declared.
*/
export function toExportModel(row: ManagementModelRow): ExportModel {
const effective = row.exportMetadata;
const contextWindow = effective?.contextWindow ?? row.contextWindow;
const maxTokens = effective?.maxTokens ?? row.maxOutputTokens;
const maxInputTokens = effective?.maxInputTokens ?? row.maxInputTokens;
const inputModalities = effective?.inputModalities ?? row.inputModalities;
const { supportsThinkingToggle, supportsReasoningEffort, defaultThinkingEnabled,
reasoningEfforts, defaultReasoningEffort } = resolveExportReasoningAxes(effective, row);
const supportsReasoningSummaries = effective?.supportsReasoningSummaries ?? row.supportsReasoningSummaries;
// Projection first, then the row's own explicit boolean (an external producer may state
// false, which is evidence), and only then derivation from positive evidence.
const supportsTools = effective?.supportsTools
?? row.supportsTools
?? knownToolsSupport({
capabilities: row.capabilities,
parallelToolCalls: row.parallelToolCalls,
native: row.native,
});
const supportsReasoning = effective?.supportsReasoning
?? row.supportsReasoning
?? knownReasoningSupport({ ...row, supportsThinkingToggle, supportsReasoningEffort,
reasoningEfforts, supportsReasoningSummaries });
return {
namespaced: row.namespaced,
provider: row.provider,
id: row.id,
fastRowAvailable: row.fastRowAvailable === true,
...(row.native ? { native: true } : {}),
...(row.displayName && row.displayNameSource !== "fallback" ? { displayName: row.displayName } : {}),
...(contextWindow !== undefined ? { contextWindow } : {}),
...(maxTokens !== undefined ? { maxTokens } : {}),
...(maxInputTokens !== undefined ? { maxInputTokens } : {}),
...(inputModalities ? { inputModalities } : {}),
// An empty array is a declaration ("no rungs"), and `[]` is truthy: it survives here.
...(reasoningEfforts ? { reasoningEfforts } : {}),
...(typeof supportsThinkingToggle === "boolean" ? { supportsThinkingToggle } : {}),
...(typeof supportsReasoningEffort === "boolean" ? { supportsReasoningEffort } : {}),
...(typeof defaultThinkingEnabled === "boolean" ? { defaultThinkingEnabled } : {}),
...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
// An explicit false is evidence and survives; only derivation is true-or-nothing.
...(typeof supportsTools === "boolean" ? { supportsTools } : {}),
...(typeof supportsReasoning === "boolean" ? { supportsReasoning } : {}),
...(supportsReasoningSummaries !== undefined ? { supportsReasoningSummaries } : {}),
};
}
/**
* Visible (non-disabled) rows as export models — the ONE loader both
* `/api/client-config` and the integration routes use, so the two can never
* disagree about which models a client is told about.
*
* The visibility filter lives HERE rather than at each call site: the export
* core serializes what it is given, so a model the user disabled in the Models
* tab is absent from `/v1/models` and exporting it would hand the client a
* selector the proxy refuses to route.
*/
export async function loadExportModels(
config: OcxConfig,
models?: readonly CatalogModel[],
): Promise<ExportModel[]> {
// Initial selection adopts into the live configuration and persists it, so it has to finish
// before anything is admitted. Admitting first would bind this roster to bytes the same load is
// about to rewrite, and finalizing against a detached copy would adopt the choices into the copy
// while leaving the live configuration pending.
if (models === undefined && pendingModelSelectionProviders(config).size > 0) {
const { resolvePendingInitialModelSelection } = await import("../../providers/initial-model-selection-runtime");
await resolvePendingInitialModelSelection(config);
}
// The configuration this pass will use from beginning to end, proved to be the one on disk.
// Without it there is nothing that may be retained, and the caller still gets its rows: only the
// preview authority is withheld.
let admission = captureExportConfigAdmission(config);
let admitted = admission?.config ?? config;
const discoveryBaseline = models === undefined ? captureModelDiscoveryBaseline(admitted) : null;
const outcomes: Array<{ provider: string; state: "authoritative" | "degraded" }> = [];
// The gather stamps each provider as it chooses its rows, so the roster and the revisions that
// vouch for it come from the same moment. Sampling afterwards would let a concurrent flight's
// publication be recorded against rows it never produced.
const gathered = new Map<string, string>();
// Gathering here rather than through the shared fetch is what keeps the detached copy out of the
// initial-selection finalizer: the projection below takes a roster, and that branch performs no
// discovery and no configuration write. The entitlement refresh keeps the budget it has always
// had, and runs alongside as it did inside the projection.
const roster = models === undefined
? (await Promise.all([
(await import("../../codex/catalog")).gatherRoutedModels(admitted, {
providerContentRevisions: gathered, providerModelOutcomes: outcomes,
}),
ensureCodexEntitlementFreshness(admitted, { waitMs: 3_000 }),
]))[0]
: models;
if (discoveryBaseline !== null) {
const authoritative = outcomes.filter(outcome => outcome.state === "authoritative").map(outcome => outcome.provider);
if (admission !== null && isExportConfigAdmissionCurrent(admission, config)
&& [...gathered].every(([provider, revision]) => observeModelCacheRevision(provider) === revision)) {
if (!finalizeModelDiscovery(config, discoveryBaseline, roster, authoritative, gathered)) {
lastExportSnapshot = null;
throw new CatalogGatherBusyError();
}
// Only our scoped discovery decision moved: bind the projection to the committed state.
admission = captureExportConfigAdmission(config);
admitted = admission?.config ?? config;
} else {
// Preserve the old-response contract after a race, without persisting stale evidence or
// retaining it as a current preview. Apply visibility policy only to a detached projection.
const projection = detachedConfigSnapshot(admitted);
if (projection === null) throw new CatalogGatherBusyError();
reconcileSuccessfulModelDiscoveries({ config: projection, models: roster,
authoritativeProviders: authoritative, now: new Date().toISOString(), mode: "discovery" });
admitted = projection;
admission = null;
}
}
const rows = await listManagementModelRows(admitted, { models: roster });
// Management deliberately lists the full roster so hidden models can be enabled.
// A client picker must also honor the provider selection, not just its blocklist.
const visibleRouted = new Set(filterCatalogVisibleModels(rows.filter(row => !row.native), admitted));
const projected = attachNestedSelectors(admitted, attachExportAliasSelectors(admitted, rows.map(toExportModel)));
const exported = projected.filter((_, index) => !rows[index]!.disabled && (rows[index]!.native || visibleRouted.has(rows[index]!)));
// Retain the FINAL projection, not an input to it. A preview that rebuilt from raw provider
// caches would miss static and forward providers, which never populate one, and would skip the
// retention, metadata, combo and filtering this function applies afterwards.
// A deep clone, not a frozen view of the caller's array. Freezing the array alone left the model
// objects shared, so a caller mutating one in place would have silently rewritten the roster a
// later preview plans against, and the fingerprint would have moved with it.
// Still the configuration these rows were chosen under, on disk and in hand alike. Revalidating
// rather than re-reading an identity is what makes this fail closed: a configuration that moved
// during the load leaves no snapshot rather than one recorded under a state its rows never had.
if (admission === null || !isExportConfigAdmissionCurrent(admission, config)) {
lastExportSnapshot = null;
return exported;
}
// Prefer the revisions the gather stamped; fall back to observing only when the roster was
// supplied and no gather happened, where there is nothing tighter to use.
const cacheStamp = gathered.size > 0 ? stampFrom(admitted, gathered) : modelCacheStamp(admitted);
const retained = lastExportSnapshot;
/*
* An identical roster keeps the identity it already had.
*
* The generation moved on every load, so an ordinary read that rebuilt the same rows, which the
* Integrations collection does, invalidated a confirmation an operator was in the middle of
* submitting. Nothing about the roster had changed; only the counter had. The rows themselves
* are compared rather than assumed equal from the configuration and the cache stamp, because a
* projection also reads entitlement state neither of those two describes.
*/
const projection = Object.freeze(structuredClone(exported));
if (retained !== null
&& retained.cacheStamp === cacheStamp
&& isExportConfigAdmissionCurrent(retained.admission, config)
&& JSON.stringify(retained.models) === JSON.stringify(projection)) {
return exported;
}
lastExportSnapshot = { admission, cacheStamp, generation: ++exportSnapshotGeneration, models: projection };
return exported;
}
/**
* The completed export roster from the last ordinary load, if it still describes this config.
*
* A preview may not gather, so it reads only what an authoritative load already finished. The
* admission it carries proved, when the roster was built, that the configuration in hand was the
* one on disk; a later read repeats that proof, so a rewritten file, an edited resident object or
* a mutated working copy each retire the snapshot rather than letting a preview plan against a
* configuration nobody has.
*
* A cold process has no snapshot and the caller answers a bounded refusal, and an ordinary load
* populates one: the Integrations collection read calls `loadExportModels`, so the page an
* operator opens before confirming anything is usually the page that fills this in. That is not a
* repair for every refusal. A configuration that disagrees with its file keeps refusing however
* many times the page is opened, because nothing here reloads or reconciles anything; once the
* two agree again the next ordinary read rebuilds the snapshot by itself.
*/
let lastExportSnapshot:
| { admission: ExportConfigAdmission; cacheStamp: string; generation: number; models: readonly ExportModel[] }
| null = null;
let exportSnapshotGeneration = 0;
/**
* A process-local prefix for the roster identity a caller carries between a preview and the
* mutation that confirms it.
*
* The identity used to be the configuration digest with a counter appended, which handed a
* dashboard an opaque-looking string that was in fact a fingerprint of the operator's
* configuration file. It only has to be unforgeable within this process and distinct across
* restarts, so it says nothing about the configuration at all.
*/
const rosterIdentityPrefix = `r${Math.trunc(Math.random() * 0xffffffff).toString(36)}`;
function rosterIdentity(generation: number): string {
return `${rosterIdentityPrefix}:${generation}`;
}
/**
* Where the gathered half of the roster stands, observed without changing it.
*
* The config key cannot see a provider's models changing underneath an unchanged configuration,
* which is exactly what discovery does. This reads the cache's own generation for each configured
* provider through the passive observer, so a completed discovery retires the snapshot and a
* preview stops planning against a roster that no longer reflects the provider.
*/
function modelCacheStamp(config: OcxConfig): string {
return Object.keys(config.providers ?? {})
.sort()
.map(provider => `${provider}=${observeModelCacheRevision(provider)}`)
.join(",");
}
/**
* The same stamp shape, built from revisions the gather recorded rather than from observation.
*
* A provider the gather did not report falls back to observation so the stamp stays total; that
* happens for a provider configured after the rows were chosen, and it retires the snapshot on
* the next read rather than pretending the roster covered it.
*/
function stampFrom(config: OcxConfig, gathered: ReadonlyMap<string, string>): string {
return Object.keys(config.providers ?? {})
.sort()
.map(provider => `${provider}=${gathered.get(provider) ?? observeModelCacheRevision(provider)}`)
.join(",");
}
/**
* Opaque identity of the snapshot a caller is holding, or null when there is none for this config.
*
* A fingerprint check that rebuilt its own roster could validate against one snapshot while the
* mutation wrote from another, because an ordinary load can replace the snapshot at any moment and
* nothing about that is serialised against the writer lock. Carrying this identity alongside the
* captured roster lets a revalidation prove the snapshot it captured is still the current one
* without ever swapping the roster the mutation is about to use.
*/
export function exportSnapshotIdentity(config: OcxConfig): string | null {
const snapshot = lastExportSnapshot;
if (snapshot === null) return null;
if (!isExportConfigAdmissionCurrent(snapshot.admission, config)) return null;
if (snapshot.cacheStamp !== modelCacheStamp(config)) return null;
return rosterIdentity(snapshot.generation);
}
/** Test seam: a fresh process has no snapshot, and suites must be able to reproduce that. */
export function resetExportSnapshotForTests(): void {
lastExportSnapshot = null;
}
/**
* The export roster for a read that must change nothing at all, or null when there is not one.
*
* Skipping the initial-selection finalizer was not enough. Discovery itself refreshes credentials
* and writes the provider model cache, so a preview that gathered would still be a write dressed
* as a read, and "the models list already does this" describes what a GET happens to do rather
* than what a preview is allowed to do.
*
* So this reads already-captured per-provider cache entries and never fetches. When no provider
* has a cached roster there is no honest snapshot to plan against, and the caller reports a
* bounded refusal rather than triggering a gather to manufacture one.
*/
export function previewExportSnapshot(
config: OcxConfig,
): { models: readonly ExportModel[]; identity: string } | null {
// One synchronous read of one const. Taking the roster and its identity in two steps let a
// concurrent load publish a new snapshot between them, so a caller could hold one roster while
// believing it held the identity of another.
const snapshot = lastExportSnapshot;
if (snapshot === null) return null;
// The roster was built from a configuration proved to be the one on disk; this asks whether both
// are still that same configuration, and reads nothing but the file to answer.
if (!isExportConfigAdmissionCurrent(snapshot.admission, config)) return null;
// A completed discovery retires the snapshot: the configuration is unchanged, but the models it
// resolves to are not the ones this roster was built from.
if (snapshot.cacheStamp !== modelCacheStamp(config)) return null;
// Cloned on the way out as well as on the way in. The retained copy is the authority, and a
// reader holding its objects could edit the roster every later preview plans against without
// going anywhere near this module.
return {
models: structuredClone(snapshot.models) as readonly ExportModel[],
identity: rosterIdentity(snapshot.generation),
};
}
export function previewExportModels(config: OcxConfig): readonly ExportModel[] | null {
return previewExportSnapshot(config)?.models ?? null;
}