UNPKG

@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
/** * 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; }