@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,990 lines • 107 kB
text/typescript
import { contextTierRecordConfigError, modelCapabilitiesConfigError, mergeModelCapabilities } from "../../config/provider-validation";
import { preserveOmittedLiveProviderFields } from "./provider-omitted-fields";
import { DECLARABLE_HOSTED_TOOL_TYPES } from "../../responses/hosted-tool-policy";
import { randomUUID } from "node:crypto";
import { cleanupRemovedGcpCredentials, providerGcpCredentialMarkers, snapshotProviderGcpCredentialMarkers } from "../../providers/gcp-credential-cleanup";
import { providerHasStoredApiKey } from "../../providers/api-keys";
import { providerGcpCredentialInputResponse, removeProviderWithGcpCredentials } from "./provider-gcp-credential-routes";
import { readFileSync } from "node:fs";
import { isDeepStrictEqual } from "node:util";
import type { CatalogModel } from "../../codex/catalog";
import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
import { clearGatherRoutedModelsInflight } from "../../codex/catalog/provider-fetch";
import {
DEFAULT_SUBAGENT_MODELS,
adoptPersistedProviderIntoLiveConfig,
codexAutoStartEnabled,
hasOwnProvider,
isValidProviderName,
modelDisplayNamesConfigError,
multiAgentGuidanceEnabled,
mutatePersistedConfig,
nonBlankStringArrayConfigError,
normalizeNonBlankStringArray,
normalizeAutoReviewModelOverrides,
providerBaseUrlConfigError,
providerHeadersConfigError,
requestPacingConfigError,
readConfigAdmissionSnapshot,
saveConfigPreservingClaudeCode,
upstreamHttpVersionConfigError,
validateConfigCandidate,
withConfigMutationLockSync,
} from "../../config";
import {
clearLoginState,
getLoginStatus,
isPublicOAuthProvider,
listOAuthProviders,
startLoginFlow,
submitManualLoginCode,
upsertOAuthProvider,
} from "../../oauth";
import { commitProviderPatch } from "./provider-patch-transaction";
import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
import { canonicalAutoReviewModelKey, mergeModelPinnedEfforts, modelPinnedEffortsConfigError, pinnedReasoningEffortConfigError } from "../../config/provider-validation";
import { releaseRemovedProviderCredentials } from "./provider-credential-release";
import { captureModelsOAuthTarget, mayResolveModelsOAuth, modelsOAuthTargetMatches } from "../../oauth/model-discovery-auth";
import { providerDestinationResolvedError } from "../../lib/destination-policy";
import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
import { ProviderOutboundPolicyError, providerOutboundGet, providerOutboundPost, providerRedirectError } from "../../lib/provider-outbound";
import { fetchCursorUsableModels } from "../../adapters/cursor/live-models";
import { fetchDevinUsableModels } from "../../adapters/devin/live-models";
import { resolveDevinApiBaseUrl } from "../../oauth/devin/api-base";
import { parseAntigravityAvailableModels } from "../../providers/antigravity-models";
import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
import {
applyProviderCompatPatchFields,
carryProviderCompatFields,
providerCompatFieldConfigError,
providerOverwriteKeepsDestination,
sampleProviderOverwrite,
} from "./provider-overwrite-carry";
import { shadowInterceptProviderDependency } from "./shadow-call-validation";
import { deriveProviderPresets, providerConfigSeed } from "../../providers/derive";
import { initializeProviderModelSelection } from "../../providers/initial-model-selection";
import { invalidModelDiscoveryHint } from "../../providers/model-discovery-diagnostic";
import { effectiveGoogleMode, providerCodexAccountMode, providerMatchesRegistryTransport } from "../../providers/registry";
import {
extractModelEnvelopeRows,
extractProviderModelItems,
isRegistryModelDiscoveryUrl,
readBoundedDiscoveryJson,
resolveProviderModelDiscovery,
} from "../../providers/model-discovery";
import {
buildVertexProviderModelsRequest,
collectVertexPublisherModelPages,
countDiscoveryResponseBytes,
extractGoogleNativeModelItems,
resolveVertexDiscoveryAuth,
vertexDiscoveryAuthIsCurrent,
vertexDiscoveryDeadline,
type VertexDiscoveryAuth,
} from "../../providers/google-vertex-model-discovery";
import { routedSlug, slugEquals } from "../../providers/slug-codec";
import { isXaiGrokOAuth, readXaiLegacyPrivacyError, XAI_LEGACY_PRIVACY_MESSAGE } from "../../providers/xai-privacy-mode";
import { clearAccountQuotaCache, clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
import { clearPassiveKeyLimits, listPassiveKeyLimits, passiveProviderOwnership } from "../../providers/passive-key-observation";
import { providerRoutingQuota } from "./provider-routing-quota";
import { probeJevDecisionProvider } from "../../combos/jev";
import { comboDependsOnProviderRoute } from "./decision-model-validation";
import { clearKeyCooldowns, forgetApiKeyRotationCursor } from "../../providers/key-failover";
import { handleProviderKeyPacingRoutes } from "./provider-key-pacing-routes";
import { CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
import { codexAccountNamespaceProviderCollisionError } from "../../codex/account-namespace-match";
import { clearThreadAccountMap } from "../../codex/routing";
import { primeCodexPoolQuotas } from "../../codex/auth-api";
import { clearModelCache, getProviderDiscoveryStatus } from "../../codex/model-cache";
import { getCodexModelEntitlementStatus } from "../../codex/model-entitlements";
import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, selectedProviderContextCaps, forgetProviderContextCap, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
import { modelAutoCompactTokenLimitsConfigError } from "../../providers/auto-compact-budget";
import { resolveCodexHomeDir } from "../../codex/home";
import { readUsageEntries } from "../../usage/log";
import { getUsageDebugLogEntries } from "../../usage/debug";
import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
import { getProviderRegistryEntry } from "../../providers/registry";
import { getDebugLogEntries } from "../../lib/debug-log-buffer";
import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
import {
clearDebugSettings,
clearDebugSetting,
getDebugSettings,
setDebugSettings,
type DebugFlag,
} from "../../lib/debug-settings";
import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
import { drainAndShutdown } from "../lifecycle";
import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
import type { PersistedUsageAttempt } from "../../usage/log";
import {
isAllowedRequestOrigin,
jsonResponse,
parseProviderEditorConfigDTO,
providerEditorConfigDTO,
providerManagementConfigError,
publicProviderBaseUrl,
safeConfigDTO,
type ProviderEditorConfigDTO,
} from "../auth-cors";
import { providerCatalogCapabilityConfigError } from "./provider-capability-config";
import { providerEmptyToolOutputConfigError } from "../../config/provider-validation";
import { applyThinkingDisplayPatchFields } from "./provider-thinking-display-patch";
import { applySystemEnvToggle } from "../system-env";
import {
LOCAL_PROVIDER_RELOAD_NAME_HEADER,
LOCAL_PROVIDER_RELOAD_PATH,
} from "../../lib/local-provider-reload-contract";
import { refreshConfigDerivedRegistries } from "../../config/derived-registries";
import { redactSecretString } from "../../lib/redact";
import {
XAI_RESPONSES_OPT_IN_MODELS,
XAI_RESPONSES_DEFAULT_VERSION,
xaiResponsesOptInState,
} from "../../providers/xai-responses-opt-in";
import { ZAI_PROVIDER_ID } from "../../providers/zai-responses-migration";
import { dropProviderCustomModels } from "../../providers/provider-id-rewrite";
import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
import type { ManagementContext } from "./context";
import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
import { anthropicInstancePublicationError, mergeProviderEditorRow, preserveAnthropicInstanceMarker } from "./provider-instance-ownership";
import { providerTlsProfileDiagnostic } from "../../lib/provider-tls-profile";
type ProviderPatchApplication =
| { error: string }
| {
next: OcxProviderConfig;
touched: boolean;
editorTouched: boolean;
enablingOpenAi: boolean;
headersTouched: boolean;
};
const PROVIDER_ALIAS_OVERLAY_FIELDS = ["alias", "modelAliases", "defaultAliases", "aliasTemplate"] as const;
type ProviderAliasOverlayField = typeof PROVIDER_ALIAS_OVERLAY_FIELDS[number];
/**
* Alias overlays are owned by the dedicated alias management routes. A full provider POST
* may round-trip an already-persisted value, but it must not create, clear, or change one.
* PATCH is field-masked and rejects these keys outright below.
*/
function providerAliasOverlayOwnershipError(
submitted: Record<string, unknown>,
existing: OcxProviderConfig | undefined,
): string | null {
for (const field of PROVIDER_ALIAS_OVERLAY_FIELDS) {
if (!Object.hasOwn(submitted, field)) continue;
if (!existing || !Object.hasOwn(existing, field)) {
return `${field} is managed by the dedicated alias API`;
}
const incoming = submitted[field];
const persisted = existing[field];
if (field === "modelAliases") {
if (!isPlainRecord(incoming) || !isPlainRecord(persisted)) {
return "modelAliases is managed by the dedicated alias API";
}
const incomingEntries = Object.entries(incoming);
const persistedEntries = Object.entries(persisted);
if (
incomingEntries.length !== persistedEntries.length
|| incomingEntries.some(([model, alias]) => typeof alias !== "string" || persisted[model] !== alias)
) {
return "modelAliases is managed by the dedicated alias API";
}
continue;
}
if (incoming !== persisted) return `${field} is managed by the dedicated alias API`;
}
return null;
}
/** Remove only alias overlays whose ownership has already been established by the caller. */
function providerTransportValidationCandidate(provider: Record<string, unknown>): Record<string, unknown> {
const candidate = { ...provider };
for (const field of PROVIDER_ALIAS_OVERLAY_FIELDS) delete candidate[field];
return candidate;
}
/** Preserve the authoritative alias values from the stored provider during a full edit. */
function restorePersistedAliasOverlays(target: OcxProviderConfig, existing: OcxProviderConfig | undefined): void {
for (const field of PROVIDER_ALIAS_OVERLAY_FIELDS) {
delete (target as Record<ProviderAliasOverlayField, unknown>)[field];
if (!existing || !Object.hasOwn(existing, field)) continue;
const value = existing[field];
(target as Record<ProviderAliasOverlayField, unknown>)[field] = field === "modelAliases"
? structuredClone(value)
: value;
}
}
type ProviderEditorCandidateResult =
| { ok: true; config: OcxConfig; removedProviders: string[] }
| { ok: false; status: 400 | 409; error: string; code: string };
type ProviderEditorMutationValue = ProviderEditorCandidateResult;
/** Build and validate a complete candidate without mutating the caller's snapshot. */
function providerEditorCandidate(
persisted: OcxConfig,
baseline: ProviderEditorConfigDTO,
next: ProviderEditorConfigDTO,
): ProviderEditorCandidateResult {
const candidate = structuredClone(persisted);
const removedProviders = Object.keys(persisted.providers)
.filter(name => !Object.hasOwn(next.providers, name));
for (const name of removedProviders) {
const dependentCombos = Object.entries(persisted.combos ?? {})
.filter(([, combo]) => comboDependsOnProviderRoute(persisted, combo, name))
.map(([id]) => id)
.sort((a, b) => a.localeCompare(b));
if (dependentCombos.length > 0) {
return {
ok: false,
status: 409,
error: `cannot delete provider ${JSON.stringify(redactSecretString(name))} while combos depend on it`,
code: "provider_has_dependent_combos",
};
}
}
const providers: Record<string, OcxProviderConfig> = Object.create(null);
for (const [name, publicProvider] of Object.entries(next.providers)) {
if (!isValidProviderName(name)) {
return {
ok: false,
status: 400,
error: "provider name must use letters, numbers, dot, underscore, or hyphen and cannot be a reserved object key",
code: "invalid_provider_name",
};
}
const namespaceCollision = codexAccountNamespaceProviderCollisionError(candidate.codexAccountNamespaces, name);
if (namespaceCollision) return { ok: false, status: 409, error: namespaceCollision, code: "provider_namespace_conflict" };
const merged = mergeProviderEditorRow(persisted.providers[name], baseline.providers[name], publicProvider);
const markerCollision = anthropicInstancePublicationError(name, merged, persisted.providers[name]);
if (markerCollision) return { ok: false, status: 409, error: markerCollision, code: "anthropic_instance_collision" };
const transportCandidate = providerTransportValidationCandidate(merged as unknown as Record<string, unknown>);
// The editor merges onto the persisted row, so stored operator overlays (selectedModels,
// disabled, …) ride along in the candidate. They are owned by their own write boundaries;
// the seed check must only pin the canonical transport/auth keys.
const providerError = providerManagementConfigError(name, transportCandidate, { allowOperatorOverlays: true })
?? providerEmptyToolOutputConfigError(name, transportCandidate)
?? providerCatalogCapabilityConfigError(name, transportCandidate);
if (providerError) return { ok: false, status: 400, error: providerError, code: "invalid_provider" };
providers[name] = merged;
}
const defaultProvider = next.defaultProvider.trim();
const selectedDefault = providers[defaultProvider];
if (!selectedDefault) {
return { ok: false, status: 400, error: "defaultProvider must name a configured provider", code: "invalid_default_provider" };
}
if (selectedDefault.disabled === true) {
return { ok: false, status: 400, error: "defaultProvider cannot be disabled", code: "default_provider_disabled" };
}
candidate.defaultProvider = defaultProvider;
candidate.providers = providers;
for (const name of removedProviders) {
dropProviderCustomModels(candidate, name);
forgetProviderContextCap(candidate, name);
}
const validated = validateConfigCandidate(candidate);
if (!validated.ok) {
return { ok: false, status: 400, error: validated.error, code: "invalid_provider_editor_config" };
}
for (const [name, provider] of Object.entries(candidate.providers)) {
if (provider.modelPinnedReasoningEfforts !== undefined) {
provider.modelPinnedReasoningEfforts = validated.config.providers[name]!.modelPinnedReasoningEfforts;
}
const normalized = validated.config.providers[name]!;
if (normalized.autoReviewModel === undefined) delete provider.autoReviewModel;
else provider.autoReviewModel = normalized.autoReviewModel;
if (normalized.autoReviewModelOverrides === undefined) delete provider.autoReviewModelOverrides;
else provider.autoReviewModelOverrides = normalized.autoReviewModelOverrides;
if (normalized.modelCapabilities === undefined) delete provider.modelCapabilities;
else provider.modelCapabilities = normalized.modelCapabilities;
}
return { ok: true, config: candidate, removedProviders };
}
function adoptProviderEditorCandidate(live: OcxConfig, persisted: OcxConfig): void {
live.defaultProvider = persisted.defaultProvider;
for (const name of Object.keys(live.providers)) {
if (!Object.hasOwn(persisted.providers, name)) delete live.providers[name];
}
for (const [name, provider] of Object.entries(persisted.providers)) {
live.providers[name] = structuredClone(provider);
}
if (persisted.customModels === undefined) delete live.customModels;
else live.customModels = structuredClone(persisted.customModels);
if (persisted.providerContextCaps === undefined) delete live.providerContextCaps;
else live.providerContextCaps = structuredClone(persisted.providerContextCaps);
if (persisted.providerContextCapValues === undefined) delete live.providerContextCapValues;
else live.providerContextCapValues = structuredClone(persisted.providerContextCapValues);
if (persisted.disabledModels === undefined) delete live.disabledModels;
else live.disabledModels = [...persisted.disabledModels];
if (persisted.modelDiscovery === undefined) delete live.modelDiscovery;
else live.modelDiscovery = structuredClone(persisted.modelDiscovery);
}
/** Share pin merge/clear semantics between POST and the PATCH mask. */
function applyProviderPinFields(
next: OcxProviderConfig,
patch: Record<string, unknown>,
current: OcxProviderConfig | undefined,
): string | null {
const scalarError = pinnedReasoningEffortConfigError(patch.pinnedReasoningEffort, true);
const mapError = modelPinnedEffortsConfigError(patch.modelPinnedReasoningEfforts, "modelPinnedReasoningEfforts", true);
if (scalarError || mapError) return scalarError ?? mapError;
const scalar = Object.hasOwn(patch, "pinnedReasoningEffort")
? patch.pinnedReasoningEffort : current?.pinnedReasoningEffort;
const map = Object.hasOwn(patch, "modelPinnedReasoningEfforts")
? mergeModelPinnedEfforts(current?.modelPinnedReasoningEfforts, patch.modelPinnedReasoningEfforts)
: current?.modelPinnedReasoningEfforts;
if (scalar === undefined || scalar === null || scalar === "") delete next.pinnedReasoningEffort;
else next.pinnedReasoningEffort = scalar as string;
if (map === undefined) delete next.modelPinnedReasoningEfforts;
else next.modelPinnedReasoningEfforts = { ...map };
return null;
}
/**
* Apply the recognized PATCH field mask onto a provider copy. The caller runs this once
* for validation and again inside the config mutation lock against the newest provider,
* so a concurrent PATCH cannot be erased by a save of a stale snapshot. Only synchronous
* checks live here; the async destination probe stays in the route.
*/
function applyProviderPatchFields(
name: string,
provider: OcxProviderConfig,
rawBody: Record<string, unknown>,
keys: string[],
config: OcxConfig,
): ProviderPatchApplication {
const next: OcxProviderConfig = { ...provider };
let touched = false;
let headersTouched = false;
if (Object.hasOwn(rawBody, "disabled")) {
if (typeof rawBody.disabled !== "boolean") return { error: "disabled must be a boolean" };
if (rawBody.disabled && name === config.defaultProvider) {
return { error: "cannot disable the default provider; set another default first" };
}
next.disabled = rawBody.disabled;
touched = true;
}
if (Object.hasOwn(rawBody, "adapter")) {
if (typeof rawBody.adapter !== "string" || !rawBody.adapter.trim()) return { error: "adapter must be a non-empty string" };
next.adapter = rawBody.adapter.trim();
touched = true;
}
if (Object.hasOwn(rawBody, "baseUrl")) {
if (typeof rawBody.baseUrl !== "string" || !rawBody.baseUrl.trim()) return { error: "baseUrl must be a non-empty string" };
next.baseUrl = rawBody.baseUrl.trim();
touched = true;
}
if (Object.hasOwn(rawBody, "defaultModel")) {
if (typeof rawBody.defaultModel !== "string") return { error: "defaultModel must be a string" };
const dm = rawBody.defaultModel.trim();
if (dm) next.defaultModel = dm;
else delete next.defaultModel;
touched = true;
}
for (const field of ["project", "location"] as const) {
if (!Object.hasOwn(rawBody, field)) continue;
const value = rawBody[field];
if (typeof value !== "string") return { error: `${field} must be a string` };
if (value.trim()) next[field] = value.trim();
else delete next[field];
touched = true;
}
if (Object.hasOwn(rawBody, "authMode")) {
if (typeof rawBody.authMode !== "string") return { error: "authMode must be a string" };
const mode = rawBody.authMode.trim();
if (mode === "key" || mode === "forward" || mode === "oauth" || mode === "local") {
next.authMode = mode;
touched = true;
} else if (mode === "") {
delete next.authMode;
touched = true;
} else {
return { error: "authMode must be key, forward, oauth, or local" };
}
}
if (Object.hasOwn(rawBody, "apiKeyTransport")) {
const transport = rawBody.apiKeyTransport;
if (transport === "x-api-key" || transport === "bearer") {
next.apiKeyTransport = transport;
touched = true;
} else if (transport === "") {
delete next.apiKeyTransport;
touched = true;
} else {
return { error: "apiKeyTransport must be x-api-key, bearer, or empty to clear" };
}
}
if (Object.hasOwn(rawBody, "note")) {
if (typeof rawBody.note !== "string") return { error: "note must be a string" };
const note = rawBody.note.trim();
if (note) next.note = note;
else delete next.note;
touched = true;
}
if (Object.hasOwn(rawBody, "allowPrivateNetwork")) {
if (typeof rawBody.allowPrivateNetwork !== "boolean") return { error: "allowPrivateNetwork must be a boolean" };
next.allowPrivateNetwork = rawBody.allowPrivateNetwork;
touched = true;
}
if (Object.hasOwn(rawBody, "liveModels")) {
if (typeof rawBody.liveModels !== "boolean") return { error: "liveModels must be a boolean" };
next.liveModels = rawBody.liveModels;
touched = true;
}
if (Object.hasOwn(rawBody, "annotateEmptyToolOutputs")) {
const value = rawBody.annotateEmptyToolOutputs;
if (value === null) {
delete next.annotateEmptyToolOutputs;
} else if (typeof value === "boolean") {
next.annotateEmptyToolOutputs = value;
} else {
return { error: "annotateEmptyToolOutputs must be a boolean or null" };
}
touched = true;
}
if (Object.hasOwn(rawBody, "fastEnabled")) {
const value = rawBody.fastEnabled;
if (value === null) delete next.fastEnabled;
else if (typeof value === "boolean") next.fastEnabled = value;
else return { error: "fastEnabled must be a boolean or null" };
touched = true;
}
if (Object.hasOwn(rawBody, "xaiResponsesOptIn")) {
if (name !== "xai") return { error: "xaiResponsesOptIn is valid only for provider xai" };
if (typeof rawBody.xaiResponsesOptIn !== "boolean") {
return { error: "xaiResponsesOptIn must be a boolean" };
}
const modelAdapters = { ...(next.modelAdapters ?? {}) };
for (const model of XAI_RESPONSES_OPT_IN_MODELS) {
if (rawBody.xaiResponsesOptIn) modelAdapters[model] = "openai-responses";
else modelAdapters[model] = "openai-chat";
}
if (Object.keys(modelAdapters).length > 0) next.modelAdapters = modelAdapters;
else delete next.modelAdapters;
next.xaiResponsesDefaultVersion = Math.max(next.xaiResponsesDefaultVersion ?? 0, XAI_RESPONSES_DEFAULT_VERSION);
touched = true;
}
if (Object.hasOwn(rawBody, "requestPacing")) {
const value = rawBody.requestPacing;
if (value === null) {
delete next.requestPacing;
} else {
if (!isPlainRecord(value)) return { error: "requestPacing must be a plain object or null" };
const pacingError = requestPacingConfigError(value);
if (pacingError) return { error: pacingError };
// `requestPacingConfigError` is the runtime narrowing boundary above; keep the
// assertion explicit because a generic plain record cannot express `enabled`.
next.requestPacing = structuredClone(value) as unknown as OcxProviderConfig["requestPacing"];
}
touched = true;
}
if (Object.hasOwn(rawBody, "upstreamHttpVersion")) {
const value = rawBody.upstreamHttpVersion;
if (value === null || value === "") {
delete next.upstreamHttpVersion;
} else {
const versionError = upstreamHttpVersionConfigError(value);
if (versionError) return { error: versionError };
// `upstreamHttpVersionConfigError` is the shared write boundary; the assertion is
// explicit because the incoming value is an unknown JSON scalar.
next.upstreamHttpVersion = value as OcxProviderConfig["upstreamHttpVersion"];
}
touched = true;
}
if (Object.hasOwn(rawBody, "upstreamWebsocket")) {
if (typeof rawBody.upstreamWebsocket !== "boolean") return { error: "upstreamWebsocket must be a boolean" };
next.upstreamWebsocket = rawBody.upstreamWebsocket;
touched = true;
}
// The Models page edits the catalog hints in place; keep them on the existing
// provider mutation path so validation, cache invalidation, and convergence stay unified (#1073).
if (Object.hasOwn(rawBody, "contextWindow")) {
const value = rawBody.contextWindow;
if (value === null) {
delete next.contextWindow;
// `Number.isInteger(1e100)` is true, so an integer check alone admits a value that
// serializes into the catalog as an enormous number and can make Codex reject the whole
// file. Safe-integer is the real bound for something that ends up in a JSON int field.
} else if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) {
next.contextWindow = value;
} else {
return { error: "contextWindow must be a positive safe integer or null" };
}
touched = true;
}
if (Object.hasOwn(rawBody, "modelCapabilities")) {
const error = modelCapabilitiesConfigError(rawBody.modelCapabilities, true);
if (error) return { error };
const capabilities = mergeModelCapabilities(next.modelCapabilities, rawBody.modelCapabilities);
if (capabilities === undefined) delete next.modelCapabilities;
else next.modelCapabilities = capabilities;
touched = true;
}
if (Object.hasOwn(rawBody, "modelContextTiers")) {
const error = contextTierRecordConfigError(rawBody.modelContextTiers, true);
if (error) return { error };
if (rawBody.modelContextTiers === null) delete next.modelContextTiers;
else next.modelContextTiers = Object.assign(Object.create(null), next.modelContextTiers ?? {}, rawBody.modelContextTiers);
touched = true;
}
if (Object.hasOwn(rawBody, "modelContextWindows")) {
const value = rawBody.modelContextWindows;
if (value === null) {
delete next.modelContextWindows;
} else {
if (!isPlainRecord(value)) return { error: "modelContextWindows must be a plain object or null" };
// A prototype-named model id must survive the merge: assigning
// "__proto__" on an ordinary object invokes the inherited setter instead
// of creating an own property, so the PATCH would report success while
// silently dropping that override.
const windows: Record<string, number> = Object.assign(
Object.create(null),
next.modelContextWindows ?? {},
);
for (const [model, window] of Object.entries(value)) {
if (!model.trim()) return { error: "modelContextWindows keys must be nonblank model ids" };
if (window === null) {
delete windows[model];
continue;
}
if (typeof window !== "number" || !Number.isSafeInteger(window) || window <= 0) {
return { error: "modelContextWindows values must be positive safe integers or null" };
}
windows[model] = window;
}
if (Object.keys(windows).length > 0) next.modelContextWindows = windows;
else delete next.modelContextWindows;
}
touched = true;
}
if (Object.hasOwn(rawBody, "pinnedReasoningEffort") || Object.hasOwn(rawBody, "modelPinnedReasoningEfforts")) {
const error = applyProviderPinFields(next, rawBody, provider);
if (error) return { error };
touched = true;
}
if (Object.hasOwn(rawBody, "autoReviewModel")) {
const value = rawBody.autoReviewModel;
if (value === null || value === "") {
delete next.autoReviewModel;
} else if (typeof value === "string" && value.trim()) {
next.autoReviewModel = value.trim();
} else {
return { error: "autoReviewModel must be a catalog selector string or null" };
}
touched = true;
}
if (Object.hasOwn(rawBody, "autoReviewModelOverrides")) {
const value = rawBody.autoReviewModelOverrides;
if (value === null) {
delete next.autoReviewModelOverrides;
} else if (isPlainRecord(value)) {
const merged: Record<string, string> = { ...(next.autoReviewModelOverrides ?? {}) };
const existingByCanonical = new Map<string, string>();
for (const existingKey of Object.keys(merged)) {
existingByCanonical.set(canonicalAutoReviewModelKey(existingKey), existingKey);
}
const submittedCanonicalKeys = new Set<string>();
for (const [model, target] of Object.entries(value)) {
const key = model.trim();
if (["__proto__", "prototype", "constructor"].includes(key)) {
return { error: "autoReviewModelOverrides keys must be non-reserved model ids" };
}
const canonicalKey = canonicalAutoReviewModelKey(model);
// Uniqueness is enforced before the tombstone branch: a clear and a set that normalize to
// the same key would otherwise resolve in object order instead of being rejected.
if (submittedCanonicalKeys.has(canonicalKey)) {
return { error: "autoReviewModelOverrides keys must be unique after trimming and slash normalization" };
}
submittedCanonicalKeys.add(canonicalKey);
if (target === null || target === "") {
const previousKey = existingByCanonical.get(canonicalKey);
if (previousKey !== undefined) delete merged[previousKey];
if (Object.hasOwn(merged, key)) delete merged[key];
continue;
}
if (typeof target !== "string" || !target.trim()) {
return { error: "autoReviewModelOverrides values must be catalog selectors, null, or empty to remove" };
}
const previousKey = existingByCanonical.get(canonicalKey);
if (previousKey !== undefined && previousKey !== key) delete merged[previousKey];
merged[key] = target.trim();
existingByCanonical.set(canonicalKey, key);
}
if (Object.keys(merged).length > 0) next.autoReviewModelOverrides = merged;
else delete next.autoReviewModelOverrides;
} else {
return { error: "autoReviewModelOverrides must be a plain object or null" };
}
touched = true;
}
if (Object.hasOwn(rawBody, "modelAutoCompactTokenLimits")) {
const value = rawBody.modelAutoCompactTokenLimits;
const error = modelAutoCompactTokenLimitsConfigError(value, {
allowTombstones: true,
requireNativeIds: name === "openai",
});
if (error) return { error };
if (value === null) {
delete next.modelAutoCompactTokenLimits;
} else {
const budgets: Record<string, number> = Object.assign(
Object.create(null) as Record<string, number>,
next.modelAutoCompactTokenLimits ?? {},
);
for (const [model, budget] of Object.entries(value as Record<string, number | null>)) {
if (budget === null) delete budgets[model];
else budgets[model] = budget;
}
if (Object.keys(budgets).length > 0) next.modelAutoCompactTokenLimits = budgets;
else delete next.modelAutoCompactTokenLimits;
}
touched = true;
}
if (Object.hasOwn(rawBody, "modelSupportsServiceTier")) {
const value = rawBody.modelSupportsServiceTier;
if (value === null) {
delete next.modelSupportsServiceTier;
} else {
if (!isPlainRecord(value)) return { error: "modelSupportsServiceTier must be a plain object or null" };
const capabilities: Record<string, boolean> = { ...(next.modelSupportsServiceTier ?? {}) };
for (const [model, supported] of Object.entries(value)) {
if (!model.trim()) return { error: "modelSupportsServiceTier keys must be nonblank model ids" };
if (supported === null) {
delete capabilities[model];
continue;
}
if (typeof supported !== "boolean") {
return { error: "modelSupportsServiceTier values must be booleans or null" };
}
capabilities[model] = supported;
}
if (Object.keys(capabilities).length > 0) next.modelSupportsServiceTier = capabilities;
else delete next.modelSupportsServiceTier;
}
touched = true;
}
if (Object.hasOwn(rawBody, "modelSuppressSyntheticMax")) {
const value = rawBody.modelSuppressSyntheticMax;
if (value === null) {
delete next.modelSuppressSyntheticMax;
} else {
if (!isPlainRecord(value)) return { error: "modelSuppressSyntheticMax must be a plain object or null" };
const capabilities: Record<string, boolean> = { ...(next.modelSuppressSyntheticMax ?? {}) };
for (const [model, suppressed] of Object.entries(value)) {
if (!model.trim()) return { error: "modelSuppressSyntheticMax keys must be nonblank model ids" };
if (suppressed === null) {
delete capabilities[model];
continue;
}
if (typeof suppressed !== "boolean") {
return { error: "modelSuppressSyntheticMax values must be booleans or null" };
}
capabilities[model] = suppressed;
}
if (Object.keys(capabilities).length > 0) next.modelSuppressSyntheticMax = capabilities;
else delete next.modelSuppressSyntheticMax;
}
touched = true;
}
if (Object.hasOwn(rawBody, "thinkingDisplay") || Object.hasOwn(rawBody, "modelThinkingDisplay")) {
const displayError = applyThinkingDisplayPatchFields(next, rawBody);
if (displayError) return displayError;
touched = true;
}
if (Object.hasOwn(rawBody, "noStructuredOutputModels")) {
const value = rawBody.noStructuredOutputModels;
if (value === null) {
delete next.noStructuredOutputModels;
} else {
const error = nonBlankStringArrayConfigError(value, "noStructuredOutputModels");
if (error) return { error };
const models = normalizeNonBlankStringArray(value as string[]);
if (models.length > 0) next.noStructuredOutputModels = models;
else delete next.noStructuredOutputModels;
}
touched = true;
}
if (Object.hasOwn(rawBody, "noJsonSchemaModels")) {
const value = rawBody.noJsonSchemaModels;
if (value === null) {
delete next.noJsonSchemaModels;
} else {
const error = nonBlankStringArrayConfigError(value, "noJsonSchemaModels");
if (error) return { error };
const models = normalizeNonBlankStringArray(value as string[]);
if (models.length > 0) next.noJsonSchemaModels = models;
else delete next.noJsonSchemaModels;
}
touched = true;
}
// The conditional list (#8204) shares the unconditional list's vocabulary and clearing rules.
for (const field of ["unsupportedHostedTools", "unsupportedHostedToolsWithClientTools"] as const) {
if (!Object.hasOwn(rawBody, field)) continue;
const value = rawBody[field];
if (value === null) {
delete next[field];
} else {
const error = nonBlankStringArrayConfigError(value, field);
if (error) return { error };
const tools = normalizeNonBlankStringArray(value as string[]);
const unknownTool = tools.find(tool => !DECLARABLE_HOSTED_TOOL_TYPES.has(tool));
if (unknownTool !== undefined) {
return {
error: `${field} must name only hosted tool types: `
+ `${[...DECLARABLE_HOSTED_TOOL_TYPES].join(", ")}`,
};
}
if (tools.length > 0) next[field] = tools;
else delete next[field];
}
touched = true;
}
if (Object.hasOwn(rawBody, "retainModels")) {
const value = rawBody.retainModels;
if (value === null) {
delete next.retainModels;
} else {
const error = nonBlankStringArrayConfigError(value, "retainModels");
if (error) return { error };
const models = normalizeNonBlankStringArray(value as string[]);
if (models.length > 0) next.retainModels = models;
else delete next.retainModels;
}
touched = true;
}
if (Object.hasOwn(rawBody, "omitReasoningEffortWithToolsModels")) {
const value = rawBody.omitReasoningEffortWithToolsModels;
if (value === null) {
delete next.omitReasoningEffortWithToolsModels;
} else {
const error = nonBlankStringArrayConfigError(value, "omitReasoningEffortWithToolsModels");
if (error) return { error };
const models = normalizeNonBlankStringArray(value as string[]);
if (models.length > 0) next.omitReasoningEffortWithToolsModels = models;
else delete next.omitReasoningEffortWithToolsModels;
}
touched = true;
}
// The reasoning-replay lists, foldDeveloperRoleToSystem and reasoningWireFormat (#5563).
const compat = applyProviderCompatPatchFields(rawBody, next);
if ("error" in compat) return { error: compat.error };
if (compat.touched) touched = true;
// headers is the one object-valued field in the mask. PATCH semantics merge it
// shallowly into the existing block so a single fingerprint header can be added
// without wiping the rest; null or an empty object clears user-managed headers.
if (Object.hasOwn(rawBody, "headers")) {
const headersValue = rawBody.headers;
if (headersValue === null || (isPlainRecord(headersValue) && Object.keys(headersValue).length === 0)) {
// Registry-owned static metadata (e.g. meta-muse's x-api-version marker)
// is not user-managed: restoring it keeps the upstream transport intact after a
// clear instead of deleting the whole block.
const entry = getProviderRegistryEntry(name);
if (entry?.staticHeaders && providerMatchesRegistryTransport(name, next)) {
next.headers = { ...entry.staticHeaders };
} else {
delete next.headers;
}
} else {
if (!isPlainRecord(headersValue)) return { error: "headers must be an object" };
const headersError = providerHeadersConfigError(headersValue);
if (headersError) return { error: headersError };
// Header names are case-insensitive on the wire. Drop any existing key whose
// lowercase name collides with an incoming one, or Headers normalization would
// send a combined "x-custom: v1, v2" value upstream.
const incoming = new Map(
Object.entries(headersValue as Record<string, string>).map(([key, value]) => [key.toLowerCase(), [key, value] as const]),
);
const merged: Record<string, string> = {};
for (const [key, value] of Object.entries(next.headers ?? {})) {
if (!incoming.has(key.toLowerCase())) merged[key] = value;
}
for (const [key, value] of incoming.values()) merged[key] = value;
next.headers = merged;
}
touched = true;
headersTouched = true;
}
if (!touched) return { error: "no recognized fields to update" };
// A disabled-only toggle preserves the v2 fast lane for non-openai providers: it changes
// routing eligibility, not the provider shape. Re-enabling `openai` is different — a
// malformed disabled row must not come back online unchanged, so canonicalize/reject
// against the same built-in gate used by mode PATCH and POST.
const editorTouched = keys.some(key => key !== "disabled");
const enablingOpenAi = name === "openai"
&& Object.hasOwn(rawBody, "disabled")
&& rawBody.disabled === false
&& provider.disabled === true;
if (!editorTouched && enablingOpenAi) {
if (!isCanonicalOpenAiForwardProvider(next)) {
return { error: "provider openai must be the canonical built-in provider" };
}
// Persist the byte-identical canonical URL so config.ts startup checks (case-sensitive)
// accept the row after we fill mode. Equivalent hosts like CHATGPT.com/:443 normalize here.
next.baseUrl = CODEX_FORWARD_BASE_URL;
// Fill missing mode so a disabled canonical row becomes a complete live openai entry.
if (next.codexAccountMode !== "pool" && next.codexAccountMode !== "direct") {
next.codexAccountMode = "pool";
}
if (next.disabled === false) delete next.disabled;
// Canonical openai never uses private-network opt-in; drop a stale flag that
// was ignored for the DNS probe so it cannot linger on the live row.
delete next.allowPrivateNetwork;
}
return { next, touched, editorTouched, enablingOpenAi, headersTouched };
}
/** Validate the canonical OpenAI soft-budget overlay against a fresh registry seed. */
function canonicalOpenAiBudgetPatchError(
provider: OcxProviderConfig,
rawBody: Record<string, unknown>,
keys: string[],
config: OcxConfig,
): string | null {
if (!isCanonicalOpenAiForwardProvider(provider)) {
return "provider openai must be the canonical built-in provider";
}
const entry = getProviderRegistryEntry("openai");
if (!entry) return "provider openai registry seed is unavailable";
const seed = providerConfigSeed(entry);
if (provider.codexAccountMode !== undefined) seed.codexAccountMode = provider.codexAccountMode;
if (provider.modelAutoCompactTokenLimits !== undefined) {
seed.modelAutoCompactTokenLimits = { ...provider.modelAutoCompactTokenLimits };
}
const applied = applyProviderPatchFields("openai", seed, rawBody, keys, config);
if ("error" in applied) return applied.error;
return providerManagementConfigError("openai", applied.next)
?? providerEmptyToolOutputConfigError("openai", applied.next);
}
export async function handleProviderRoutes(ctx: ManagementContext): Promise<Response | null> {
const { req, url, config, deps, principal, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
if (url.pathname === "/api/provider-quotas" && req.method === "GET") {
const forceRefresh = url.searchParams.get("refresh") === "1" || url.searchParams.get("refresh") === "true";
const snapshot = await fetchProviderQuotaReports(config, forceRefresh);
const now = Date.now();
return jsonResponse({
...snapshot,
passiveKeyLimits: listPassiveKeyLimits(config),
reports: snapshot.reports.map(report => ({
...report,
routingQuota: providerRoutingQuota(config, report.provider, now),
})),
});
}
const keyPacingResponse = handleProviderKeyPacingRoutes(ctx);
if (keyPacingResponse) return keyPacingResponse;
if (url.pathname === "/api/providers" && req.method === "GET") {
return jsonResponse(Object.entries(config.providers).map(([name, p]) => ({
name, adapter: p.adapter, baseUrl: publicProviderBaseUrl(p.baseUrl), defaultModel: p.defaultModel,
hasApiKey: providerHasStoredApiKey(p),
// Presence only (#959 review): header names and values never leave the process.
hasHeaders: !!p.headers && Object.keys(p.headers).length > 0,
allowPrivateNetwork: p.allowPrivateNetwork === true,
preserveResponsesReasoningContent: p.preserveResponsesReasoningContent,
promoteAdditionalTools: p.promoteAdditionalTools,
forwardAdvisorTool: p.forwardAdvisorTool,
liveModels: p.liveModels !== false,
requestPacing: p.requestPacing,
models: p.models ?? [],
contextWindow: p.contextWindow,
inferContextWindow: p.inferContextWindow,
modelContextWindows: p.modelContextWindows,
modelContextTiers: p.modelContextTiers,
modelCapabilities: p.modelCapabilities,
pinnedReasoningEffort: p.pinnedReasoningEffort,
modelPinnedReasoningEfforts: p.modelPinnedReasoningEfforts,
modelAutoCompactTokenLimits: p.modelAutoCompactTokenLimits,
modelSupportsServiceTier: p.modelSupportsServiceTier,
modelSuppressSyntheticMax: p.modelSuppressSyntheticMax,
noStructuredOutputModels: p.noStructuredOutputModels,
noJsonSchemaModels: p.noJsonSchemaModels,
unsupportedHostedTools: p.unsupportedHostedTools,
unsupportedHostedToolsWithClientTools: p.unsupportedHostedToolsWithClientTools,
retainModels: p.retainModels,
omitReasoningEffortWithToolsModels: p.omitReasoningEffortWithToolsModels,
upstreamHttpVersion: p.upstreamHttpVersion,
transientRetryOn5xx: p.transientRetryOn5xx,
upstreamWebsocket: p.upstreamWebsocket, // Unset keeps upstream WebSocket enabled for canonical OpenAI.
authMode: p.authMode,
apiKeyTransport: p.apiKeyTransport,
disabled: p.disabled === true,
codexAccountMode: providerCodexAccountMode(name, p),
...(name === "xai" ? { xaiResponsesOptInState: xaiResponsesOptInState(p) } : {}),
// Only opt-in Fast lanes (Anthropic fast mode bills usage credits) get a dashboard switch.
...(getProviderRegistryEntry(name)?.fastOptIn === true ? { fastOptIn: { enabled: p.fastEnabled === true } } : {}),
discovery: p.liveModels === false ? undefined : getProviderDiscoveryStatus(name), ...providerTlsProfileDiagnostic(name, p),
...(name === "openai" && isCanonicalOpenAiForwardProvider(p)
? { entitlement: getCodexModelEntitlementStatus(config) }
: {}),
})));
}
if (url.pathname === LOCAL_PROVIDER_RELOAD_PATH && req.method === "POST") {
if (principal !== "local-provider-reload-capability") {
return jsonResponse({ error: "provider reload capability required" }, 403);
}
const name = req.headers.get(LOCAL_PROVIDER_RELOAD_NAME_HEADER) ?? "";
if (!isValidProviderName(name)) return jsonResponse({ error: "invalid provider reload target" }, 400);
const admitted = readConfigAdmissionSnapshot();
if (
admitted.kind !== "read"
|| admitted.diagnostics.source !== "file"
|| admitted.diagnostics.error !== null
) {
return jsonResponse({ error: "provider reload source unavailable" }, 409);
}
const diskConfig = admitted.diagnostics.config;
if (!hasOwnProvider(diskConfig.providers, name)) {
return jsonResponse({ error: "provider reload target unavailable" }, 404);
}
const provider = diskConfig.providers[name]!;
const providerError = providerManagementConfigError(
name,
providerTransportValidationCandidate(provider as unknown as Record<string, unknown>),
// Reload validates a row straight off disk, which legitimately carries stored
// operator overlays; only the canonical transport/auth keys need to match the seed.
{ allowOperatorOverlays: true },
)
?? providerEmptyToolOutputConfigError(name, provider);
if (providerError) return jsonResponse({ error: "provider reload target invalid" }, 409);
const namespaceCollision = codexAccountNamespaceProviderCollisionError(
diskConfig.codexAccountNamespaces,
name,
);
if (namespaceCollision) return jsonResponse({ error: "provider reload target conflicts with routing" }, 409);
const allowBenchmarkAddresses = name === "openai" && isCanonicalOpenAiForwardProvider(provider);
const resolvedError = await providerDestinationResolvedError(name, provider, { allowBenchmarkAddresses });
if (resolvedError) return jsonResponse({ error: "provider reload target rejected" }, 409);
// Destination validation awaits DNS. A cooperating writer holds the same SQLite
// mutation lock, so the final exact-byte check and live adoption happen as one
// synchronous authority decision. The route does not save or reserialize disk.
let currentDiskConfig: OcxConfig | null = null;
let sourceChanged = false;
withConfigMutationLockSync(() => {
const current = readConfigAdmissionSnapshot();
if (
current.kind !== "read"
|| current.diagnostics.source !== "file"
|| current.diagnostics.error !== null
|| current.contentSha256 !== admitted.contentSha256
) {
sourceChanged = true;
return;
}
currentDiskConfig = current.diagnostics.config;
adoptPersistedProviderIntoLiveConfig(
config,
name,
current.diagnostics.config.providers[name]!,
current.diagnostics.config,
);
});
if (sourceChanged || currentDiskConfig === null) {
return jsonResponse({ error: "provider reload source changed" }, 409);
}
clearPassiveKeyLimits(name);
reconcileLiveStateStores();
// The complete disk snapshot owns display overlays, including providers that this
// live routing instance deliberately does not adopt.
refreshConfigDerivedRegistries(currentDiskConfig);
clearGatherRoutedModelsInflight();
(deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
clearAccountQuotaCache(name);
clearKeyCooldowns(name);
// The rotation cursor describes a pool this edit just changed; keeping it would let a
// stale position steer the next proactive pick.
forgetApiKeyRotationCursor(name);
clearModelCache(name);
if (name === "openai") (deps.clearThreadAccountMap ?? clearThreadAccountMap)();
const catalogRefresh = await convergeCodexCatalog();
return jsonResponse({ success: true, name, catalogRefresh });
}
if (url.pathname === "/api/providers" && req.method === "PUT") {
let rawBody: unknown;
try {
rawBody = await readManagementJsonBody(req);
} catch (error) {
rethrowManagementBodyTooLarge(error);
return jsonResponse({ error: "invalid JSON body" }, 400);
}
if (!isPlainRecord(rawBody)) {
return jsonResponse({ error: "provider batch body must be a plain object", code: "invalid_provider_editor_body" }, 400);
}
const bodyKeys = Object.keys(rawBody);
if (bodyKeys.length !== 2 || !Object.hasOwn(rawBody, "baseline") || !Object.hasOwn(rawBody, "next")) {
return jsonResponse({ error: "provider batch body must contain only baseline and next", code: "invalid_provider_editor_body" }, 400);
}
const baselineResult = parseProviderEditorConfigDTO(rawBody.baseline);
if (!baselineResult.ok) return jsonResponse({ error: baselineResult.error, code: baselineResult.code }, 400);
const nextResult = parseProviderEditorConfigDTO(rawBody.next);
if (!nextResult.ok) return jsonResponse({ error: nextResult.error, code: nextResult.code }, 400);
const observed = readConfigAdmissionSnapshot();
if (observed.kind !== "read" || observed.diagnostics.source !== "file" || observed.diagnostics.error !== null) {
return jsonResponse({ error: "provider config is unavailable", code: "provider_config_unavailable" }, 409);
}
if (!isDeepStrictEqual(providerEditorConfigDTO(observed.diagnostics.config), baselineResult.value)) {
return jsonResponse({ error: "provider editor baseline is stale", code: "stale_provider_editor_baseline" }, 409);
}
const preview = providerEditorCandidate(observed.diagnostics.config, baselineResult.value, nextResult.value);
if (!preview.ok) return jsonResponse({ error: preview.error, code: preview.code }, preview.status);
// DNS/SSRF validation happens before the persistence callback. The callback repeats every
// synchronous check against a fresh snapshot and rejects a changed baseline, so this awaited
// phase can never authorize a stale provider set.
for (const [name, provider] of Object.entries(preview.config.providers)) {
const allowBenchmarkAddresses = name === "openai" && isCanonicalOpenAiForwardProvider(provider);
const resolvedError = await providerDestinationResolvedError(name, provider, { allowBenchmarkAddresses });
if (resolvedError) return jsonResponse({ error: resolvedError, code: "invalid_provider_destination" }, 400);
}
let removedCredentials: string[] = [];
const outcome = mutatePersistedConfig<ProviderEditorMutationValue>(persisted => {
if (!isDeepStrictEqual(providerEditorConfigDTO(persisted), baselineResult.value)) {
return {
changed: false,
value: {
ok: false,
status: 409,
error: "provider editor baseline is stale",
code: "stale_provider_editor_baseline",
},
};
}
const candidate = providerEditorCandidate(persisted, baselineResult.value, nextResult.value);
if (!candidate.ok) return { changed: false, value: candidate };
const changed = !isDeepStrictEqual(providerEditorConfigDTO(persisted), nextResult.value);
if (!changed) return { changed: false, value: candidate };
for (const [name, provider] of Object.entries(candidate.config.providers)) {
if (!Object.hasOwn(persisted.providers, name)) {
initializeProviderModelSelection(name, provider, undefined, candidate.config);
}
}
removedCredentials = Object.values(persisted.providers).flatMap(providerGcpCredentialMarkers);
persisted.defaultProvider = candidate.config.defaultProvider;
persisted.providers = structuredClone(candidate.config.providers);
persisted.disabledModels = candidate.config.disabledModels;
persisted.modelDiscovery = candidate.config.modelDiscovery;
for (const name of candidate.removedProviders) {
dropProviderCustomModels(persisted, name);
forgetProviderContextCap(persisted, name);
}
return {
changed: true,
value: {
ok: true,
config: structuredClone(persisted),
removedProviders: candidate.removedProviders,
},
};
});
if (outcome.status === "unavailable") {
const code = outcome.reason === "conflict" ? "provider_config_conflict" : "provider_config_unavailable";
return jsonResponse({ error: "provider config changed before it could be saved", code }, 409);
}
if (!outcome.value.ok) {
return jsonResponse({ error: outcome.value.error, code: outcome.value.code }, outcome.value.status);
}
cleanupRemovedGcpCredentials(removedCredentials);
adoptProviderEditorCandidate(config, outcome.value.config);
clearPassiveKeyLimits();
reconcileLiveStateStores();
refreshConfigDerivedRegistries(outcome.value.config);
clearGatherRoutedModelsInflight();
(deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
clearAccountQuotaCache();
clearKeyCooldowns();
// Cursors too, for the same reason the cooldown clear above takes no name: this PUT
// replaces the whole roster, and a cursor that outlives it still names a real id, so
// round-robin would resume after the pre-edit position instead of the new roster head.
forgetApiKeyRotationCursor();
clearModelCache();
(deps.clearThreadAccountMap ?? clearThreadAccountMap)();
const catalogRefresh = await convergeCodexCatalog();
return jsonResponse({ success: true, catalogRefresh });
}
// Provider POST merges directly; existing secrets never round-trip through masked DTOs.
if (url.pathname === "/api/providers" && req.method === "POST") {
let body: { name?: unknown; provider?: unknown; setDefault?: boolean };
try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
const name = typeof body.name === "string" ? body.name.trim() : "";
if (!isPlainRecord(body.provider)) return jsonResponse({ error: "provider must be a plain object" }, 400);
const credentialResponse = providerGcpCredentialInputResponse(body.provider);
if (credentialResponse) return credentialResponse;
// Reject canonical-row clears before normalization hides their ownership.
if (name === "openai" && (Object.hasOwn(body.provider, "autoReviewModel") || Object.hasOwn(body.provider, "autoReviewModelOverrides"))) {
return jsonResponse({ error: "provider openai must not include autoReviewModel or autoReviewModelOverrides" }, 400);
}
const existing = config.providers[name];
const aliasOwnershipError = providerAliasOverlayOwnershipError(body.provider, existing);
if (aliasOwnershipError) return jsonResponse({ error: aliasOwnershipError }, 400);
const transportCandidate = providerTransportValidationCandidate(body.provider);
preserveAnthropicInstanceMarker(name, transportCandidate as unknown as OcxProviderConfig, existing);
const markerCollision = anthropicInstancePublicationError(name, transportCandidate as unknown as OcxProviderConfig, existing);
if (markerCollision) return jsonResponse({ error: markerCollision }, 409);
const pinError = applyProviderPinFields(transportCandidate as unknown as OcxProviderConfig, body.provider, existing);
if (pinError) return jsonResponse({ error: pinError }, 400);
const providerError = providerManagementConfigError(name, transportCandidate)
?? providerEmptyToolOutputConfigError(name, transportCandidate)
?? providerCompatFieldConfigError(body.provider as Record<string, unknown>);
if (providerError) return jsonResponse({ error: providerError }, 400);
const rawProvider = body.provider as Record<string, unknown>;
if (rawProvider.upstreamWebsocket !== undefined && typeof rawProvider.upstreamWebsocket !== "boolean") {
return jsonResponse({ error: "upstreamWebsocket must be a boolean" }, 400);
}
const catalogCapabilityError = providerCatalogCapabilityConfigError(name, transportCandidate);
if (catalogCapabilityError) return jsonResponse({ error: catalogCapabilityError }, 400);
const prov = stripCodexRuntimeProviderFields(transportCandidate as unknown as OcxProviderConfig);
// PATCH already clears on null; POST persisted the body as submitted, so a `null` here
// reached disk and the next loadConfig() refused it. Canonicalize to absent, which is what
// "clear" means everywhere else.
if (prov && prov.upstreamHttpVersion === null) delete prov.upstreamHttpVersion;
if (!name || !prov?.adapter || !prov?.baseUrl) {
return jsonResponse({ error: "name, provider.adapter and provider.baseUrl are required" }, 400);
}
const displayNamesError = modelDisplayNamesConfigError(prov.modelDisplayNames);
if (displayNamesError) return jsonResponse({ error: displayNamesError }, 400);
if (!isValidProviderName(name)) {
return jsonResponse({ error: "provider name must use letters, numbers, dot, underscore, or hyphen and cannot be a reserved object key" }, 400);
}
const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
if (namespaceCollision) {
return jsonResponse({ error: namespaceCollision }, 409);
}
// Hostname destinations additionally get a DNS-resolved SSRF check at write time —
// the sync check above only classifies literal IPs (review finding, PR #96).
// Canonical openai still runs the resolver: only Clash fake-IP (198.18.0.0/15)
// answers are ignored; loopback/RFC1918/metadata/mixed sets still fail.
const allowBenchmarkAddresses = name === "openai" && isCanonicalOpenAiForwardProvider(prov);
const resolvedError = await providerDestinationResolvedError(name, prov, { allowBenchmarkAddresses });
if (resolvedError) return jsonResponse({ error: resolvedError }, 400);
if (body.setDefault !== undefined && typeof body.setDefault !== "boolean") {
return jsonResponse({ error: "setDefault must be a boolean" }, 400);
}
if (body.setDefault === true && prov.disabled) {
return jsonResponse({ error: "cannot set a disabled provider as default", code: "default_provider_disabled" }, 400);
}
// Catalog providers (e.g. ollama-cloud) carry a models + vision/reasoning classification the GUI
// doesn't send — merge it in so the sidecars are gated correctly.
// Sample request ownership BEFORE enrichment. Enrichment fills absent fields from the
// registry seed, after which "the client omitted this" and "the registry supplied it" are
// indistinguishable — so a carry-over guard written as `prov.x === undefined` after this
// call can never fire.
const submittedContextWindow = Object.hasOwn(prov, "contextWindow");
const submittedModelContextWindows = Object.hasOwn(prov, "modelContextWindows");
const submittedModelContextTiers = Object.hasOwn(prov, "modelContextTiers");
const submittedModelAutoCompactTokenLimits = Object.hasOwn(prov, "modelAutoCompactTokenLimits");
const submittedModelDisplayNames = Object.hasOwn(prov, "modelDisplayNames");
const submittedRequestPacing = Object.hasOwn(prov, "requestPacing");
const submittedUpstreamWebsocket = Object.hasOwn(prov, "upstreamWebsocket");
const submittedFastEnabled = Object.hasOwn(prov, "fastEnabled");
// Same trap, one more field: DeepSeek carries a registry default of `true` for
// annotateEmptyToolOutputs, so enrichment cannot distinguish "the client omitted it"
// from "the registry supplied it" either. Without this sample, an unrelated edit that
// omits the key resurrects the registry default over an operator's explicit `false`.
const submittedAnnotateEmptyToolOutputs = Object.hasOwn(prov, "annotateEmptyToolOutputs");
// And for the compatibility settings, several of which enrichment fills from the registry
// seed (#5563); the sample also records whether the request named an auth mode.
const overwriteSample = sampleProviderOverwrite(prov);
enrichProviderFromCatalog(name, prov);
const { saveConfigPreservingClaudeCode: save } = await import("../../config");
// Overwriting an existing provider must not drop its multi-key pool: carry it over, then
// let the (possibly new) apiKey join the pool as the active entry. Only while the provider
// keeps its destination: those keys were issued for the previous upstream.
const existingPool = config.providers[name]?.apiKeyPool;
if (existingPool && !prov.apiKeyPool
&& providerOverwriteKeepsDestination(prov, config.providers[name], overwriteSample)) prov.apiKeyPool = existingPool;
// The same rule applies to user-configured price overlays: the dashboard's
// add/edit form does not send modelCosts, so an overwrite must not silently
// erase hand-edited per-model prices from Logs/Usage estimates.
const existingCosts = config.providers[name]?.modelCosts;
if (existingCosts && !prov.modelCosts) prov.modelCosts = existingCosts;
// The add/edit form also omits auto-review selectors. Preserve hand-configured
// provider-wide and per-model targets across an unrelated overwrite; clearing is
// explicit through PATCH with null.
const submittedAutoReviewModel = Object.hasOwn(body.provider, "autoReviewModel");
const submittedAutoReviewOverrides = Object.hasOwn(body.provider, "autoReviewModelOverrides");
const existingAutoReviewModel = config.providers[name]?.autoReviewModel;
if (!submittedAutoReviewModel && existingAutoReviewModel && !prov.autoReviewModel) prov.autoReviewModel = existingAutoReviewModel;
const existingAutoReviewOverrides = config.providers[name]?.autoReviewModelOverrides;
if (!submittedAutoReviewOverrides && existingAutoReviewOverrides && !prov.autoReviewModelOverrides) {
prov.autoReviewModelOverrides = { ...existingAutoReviewOverrides };
}
if (prov.autoReviewModel !== undefined) {
if (typeof prov.autoReviewModel === "string" && prov.autoReviewModel.trim()) {
prov.autoReviewModel = prov.autoReviewModel.trim();
} else {
delete prov.autoReviewModel;
}
}
if (prov.autoReviewModelOverrides !== undefined) {
const normalizedOverrides = normalizeAutoReviewModelOverrides(prov.autoReviewModelOverrides);
if (normalizedOverrides) prov.autoReviewModelOverrides = normalizedOverrides;
else delete prov.autoReviewModelOverrides;
}
// And to the per-provider account-failover opt-out (#2568d). `ProviderPayload` has no
// member for it either, so an add/edit save structurally cannot carry it — and dropping it
// silently ENABLES rotation, because activation is presence-driven once the knob is gone.
// An overwrite must not spend a second subscription account's quota as a side effect.
const existingFailover = config.providers[name]?.oauthAccountFailover;
if (existingFailover && !prov.oauthAccountFailover) prov.oauthAccountFailover = existingFailover;
if (!Object.hasOwn(body.provider, "cacheAffinity") && config.providers[name]?.cacheAffinity !== undefined) {
prov.cacheAffinity = config.providers[name]!.cacheAffinity;
}
// ...and to hand-edited context windows. `ProviderPayload` (gui/src/provider-payload.ts)
// has no member for either field, so the add/edit form structurally cannot send them:
// absence in the request means "not carried", never "the user deleted it". Deletion goes
// through PATCH with an explicit null (#1409).
if (!submittedModelDisplayNames && existing?.modelDisplayNames) {
prov.modelDisplayNames = { ...existing.modelDisplayNames };
}
if (!submittedRequestPacing && existing?.requestPacing) {
prov.requestPacing = structuredClone(existing.requestPacing);
}
if (!submittedContextWindow && existing?.contextWindow !== undefined) {
prov.contextWindow = existing.contextWindow;
}
// `!== undefined` rather than a truthiness test: the whole point of this field is that
// an explicit `false` must survive, and `false` is falsy.
if (!submittedAnnotateEmptyToolOutputs && existing?.annotateEmptyToolOutputs !== undefined) {
prov.annotateEmptyToolOutputs = existing.annotateEmptyToolOutputs;
}
// The provider add/edit form may omit this transport option. Preserve the stored value
// during a full overwrite; PATCH remains the explicit mutation path, and `!== undefined`
// keeps an operator's explicit false from being treated as absent.
if (!submittedUpstreamWebsocket && existing?.upstreamWebsocket !== undefined) {
prov.upstreamWebsocket = existing.upstreamWebsocket;
}
// The Models-page Fast switch is PATCH-owned and the provider form never sends it, so an
// unrelated full save must not silently turn an opted-in Anthropic Fast lane back off.
const liveFastEnabled = config.providers[name]?.fastEnabled;
if (!submittedFastEnabled && liveFastEnabled !== undefined) prov.fastEnabled = liveFastEnabled;
// The form sends none of the compatibility settings either (#5563). Read the live row rather
// than `existing`, like the alias overlays below: a PATCH that saved one of them while DNS
// validation awaited must not be undone. Only the hideRawReasoning display policy follows the
// provider to a new destination; the upstream compatibility settings do not.
carryProviderCompatFields(prov, config.providers[name], overwriteSample);
if (existing?.modelContextWindows) {
// When the client did send a map, its keys win and the user's other keys survive. When
// it did not, the stored value is the user's map alone: merging the registry seed in
// would persist seed keys into user config as a side effect of an unrelated save, and
// router.ts already fills registry values beneath user entries at resolve time.
prov.modelContextWindows = submittedModelContextWindows
? { ...existing.modelContextWindows, ...(prov.modelContextWindows ?? {}) }
: { ...existing.modelContextWindows };
}
if (existing?.modelAutoCompactTokenLimits) {
prov.modelAutoCompactTokenLimits = submittedModelAutoCompactTokenLimits
? { ...existing.modelAutoCompactTokenLimits, ...(prov.modelAutoCompactTokenLimits ?? {}) }
: { ...existing.modelAutoCompactTokenLimits };
}
// DNS validation above awaits. Re-read the live row so a dedicated alias write that
// completed during that wait remains authoritative instead of being overwritten by the
// older ownership snapshot used to admit this POST.
const lateMarkerCollision = anthropicInstancePublicationError(name, prov, config.providers[name]);
if (lateMarkerCollision) return jsonResponse({ error: lateMarkerCollision }, 409);
preserveAnthropicInstanceMarker(name, prov, config.providers[name]);
restorePersistedAliasOverlays(prov, config.providers[name]);
const capabilities = Object.hasOwn(body.provider, "modelCapabilities")
? mergeModelCapabilities(undefined, prov.modelCapabilities)
: mergeModelCapabilities(config.providers[name]?.modelCapabilities, undefined);
if (capabilities === undefined) delete prov.modelCapabilities;
else prov.modelCapabilities = capabilities;
// The add/edit form omits wire choices. Read after DNS so a concurrent switch
// remains authoritative, including the marker that protects it on the next boot.
if (name === "xai") {
const latest = config.providers[name];
if (!Object.hasOwn(body.provider, "modelAdapters") && latest?.modelAdapters) {
prov.modelAdapters = { ...latest.modelAdapters };
}
if (latest?.xaiResponsesDefaultVersion !== undefined) {
prov.xaiResponsesDefaultVersion = latest.xaiResponsesDefaultVersion;
}
}
// Same reason for the Z.AI marker: the provider form never carries it, and losing it on an
// unrelated edit would let the one-time wire rewrite run a second time.
if (name === ZAI_PROVIDER_ID) {
const latest = config.providers[name];
if (latest?.zaiResponsesDefaultVersion !== undefined) {
prov.zaiResponsesDefaultVersion = latest.zaiResponsesDefaultVersion;
}
}
// Reapply pins after DNS/import awaits; validate the complete draft before adoption.
const latest = config.providers[name];
const latestPinError = applyProviderPinFields(prov, body.provider, latest);
if (latestPinError) return jsonResponse({ error: latestPinError }, 400);
const pinsOwned = Object.hasOwn(body.provider, "pinnedReasoningEffort")
|| Object.hasOwn(body.provider, "modelPinnedReasoningEfforts")
|| latest?.pinnedReasoningEffort !== undefined || latest?.modelPinnedReasoningEfforts !== undefined;
// Stage new-registration discovery state in a draft until validation passes.
const registrationDraft = !latest ? {
...config,
...(config.modelDiscovery === undefined ? {} : { modelDiscovery: structuredClone(config.modelDiscovery) }),
} : undefined;
initializeProviderModelSelection(name, prov, latest, registrationDraft ?? config);
const candidate = stripRegistryOnlyStaticHeaders(name, prov);
const previous = Object.getOwnPropertyDescriptor(config.providers, name);
const rollback = pinsOwned ? captureConfigTopLevelRollback(config, ["defaultProvider", "modelDiscovery", "disabledModels"]) : undefined;
let validationError: string | undefined, removedCredentials: string[] = [];
withConfigMutationLockSync(() => {
validationError = anthropicInstancePublicationError(name, candidate, config.providers[name]);
if (validationError) return;
const liveTiers = config.providers[name]?.modelContextTiers;
if (submittedModelContextTiers && liveTiers) candidate.modelContextTiers = Object.assign(Object.create(null), liveTiers, candidate.modelContextTiers ?? {});
else if (!submittedModelContextTiers && liveTiers) candidate.modelContextTiers = { ...liveTiers };
else if (!submittedModelContextTiers) delete candidate.modelContextTiers;
preserveOmittedLiveProviderFields(candidate, rawProvider, config.providers[name]);
const draft = { ...(registrationDraft ?? config), providers: { ...config.providers, [name]: candidate }, ...(body.setDefault === true ? { defaultProvider: name } : {}) };
const validation = validateConfigCandidate(draft); if (!validation.ok) { validationError = validation.error; return; }
try {
if (registrationDraft) {
for (const key of ["modelDiscovery", "disabledModels"] as const) {
if (Object.hasOwn(registrationDraft, key)) Object.defineProperty(config, key, {
value: registrationDraft[key], writable: true, enumerable: true, configurable: true,
});
}
}
removedCredentials = snapshotProviderGcpCredentialMarkers(name, config.providers[name]);
config.providers[name] = candidate;
if (body.setDefault === true) config.defaultProvider = name;
(deps.saveConfigPreservingClaudeCode ?? save)(config);
} catch (error) {
if (rollback) {
if (previous) Object.defineProperty(config.providers, name, previous);
else delete config.providers[name];
rollback();
}
throw error;
}
});
if (validationError !== undefined) return jsonResponse({ error: validationError }, 400);
clearPassiveKeyLimits(name);
cleanupRemovedGcpCredentials(removedCredentials);
reconcileLiveStateStores();
if (prov.apiKey && prov.apiKeyPool) {
const { addProviderApiKey } = await import("../../providers/api-keys");
addProviderApiKey(config, name, prov.apiKey);
}
const { clearModelCache } = await import("../../codex/model-cache");
clearModelCache(name);
const catalogRefresh = await convergeCodexCatalog();
return jsonResponse({ success: true, name, catalogRefresh });
}
if (url.pathname === "/api/providers" && req.method === "PATCH") {
const name = url.searchParams.get("name")?.trim();
if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
let rawBody: unknown;
try { rawBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
if (!isPlainRecord(rawBody)) return jsonResponse({ error: "provider patch body must be a plain object" }, 400);
const keys = Object.keys(rawBody);
const aliasField = PROVIDER_ALIAS_OVERLAY_FIELDS.find(field => Object.hasOwn(rawBody, field));
if (aliasField) return jsonResponse({ error: `${aliasField} is managed by the dedicated alias API` }, 400);
const hasMode = Object.hasOwn(rawBody, "codexAccountMode");
const hasSetDefault = Object.hasOwn(rawBody, "setDefault");
const canonicalBudgetOnly = name === "openai"
&& keys.length === 1
&& keys[0] === "modelAutoCompactTokenLimits";
// codexAccountMode keeps its dedicated side-effect path (quota cache clear, thread map
// clear, pool prime) and is mutually exclusive with every other patch field.
if (hasMode) {
if (keys.length !== 1) {
return jsonResponse({ error: "codexAccountMode cannot be combined with other patch fields" }, 400);
}
if (name !== "openai") return jsonResponse({ error: "codexAccountMode is valid only for provider openai" }, 400);
const mode = rawBody.codexAccountMode;
if (mode !== "pool" && mode !== "direct") {
return jsonResponse({ error: "codexAccountMode must be pool or direct" }, 400);
}
const provider = config.providers.openai;
if (!provider || !isCanonicalOpenAiForwardProvider(provider)) {
return jsonResponse({ error: "provider openai must be the canonical built-in provider" }, 400);
}
commitProviderPatch(config, () => {
config.providers.openai = { ...provider, codexAccountMode: mode };
}, deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode);
reconcileLiveStateStores();
(deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
(deps.clearThreadAccountMap ?? clearThreadAccountMap)();
if (mode === "pool") {
try {
const prime = deps.primeCodexPoolQuotas ?? primeCodexPoolQuotas;
void Promise.resolve(prime(config, "mode-change")).catch(() => undefined);
} catch {
// Quota priming is best-effort; the persisted live mode is already authoritative.
}
}
return jsonResponse({ success: true, name: "openai", codexAccountMode: mode });
}
// Default-provider changes must be a deliberate, standalone action. This keeps
// routing changes out of ordinary provider edits and lets the dashboard expose a
// simple "Set as default" control without round-tripping the full config.
if (hasSetDefault) {
if (keys.length !== 1 || rawBody.setDefault !== true) {
return jsonResponse({ error: "setDefault must be true and cannot be combined with other patch fields" }, 400);
}
if (config.providers[name]!.disabled) {
return jsonResponse({ error: "cannot set a disabled provider as default", code: "default_provider_disabled" }, 400);
}
commitProviderPatch(config, () => {
config.defaultProvider = name;
}, deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode);
reconcileLiveStateStores();
return jsonResponse({ success: true, name, defaultProvider: name });
}
// Field-mask editor: apply recognized fields onto a copy, then validate the MERGED
// provider (canonical-seed guard covers openai; local-guard covers registry key providers).
// API keys are never writable here — the api-keys endpoints own pool-integrated key writes.
if (Object.hasOwn(rawBody, "apiKey")) {
return jsonResponse({ error: "apiKey cannot be patched here; use the provider API-key endpoints" }, 400);
}
// The canonical OpenAI row rejects these fields outright on create. A PATCH that only clears
// or restates them would otherwise slip past the merged-row guard and answer 200, which reads
// as acceptance for a field the provider does not support.
if (name === "openai" && (Object.hasOwn(rawBody, "autoReviewModel") || Object.hasOwn(rawBody, "autoReviewModelOverrides"))) {
return jsonResponse({ error: "provider openai must not include autoReviewModel or autoReviewModelOverrides" }, 400);
}
const applied = applyProviderPatchFields(name, config.providers[name]!, rawBody, keys, config);
if ("error" in applied) return jsonResponse({ error: applied.error }, 400);
const next = applied.next;
const pacingOnly = keys.every(key => key === "requestPacing");
// A combo naming this row as its decisionProvider is only as valid as the row: an adapter
// or baseUrl edit could fail the combo's load-time checks and get it salvaged away on the
// next reload. Disabling the row stays allowed (not editorTouched; runtime fails open).
const decisionDependent = () => Object.values(config.combos ?? {})
.some(combo => (typeof combo.decisionProvider === "string" && combo.decisionProvider.trim() === name)
|| (typeof combo.decisionModel === "string" && combo.decisionModel.trim().startsWith(`${name}/`)));
const { decisionModelProviderPatchError } = await import("./decision-model-validation");
const decisionModelError = applied.editorTouched ? decisionModelProviderPatchError(config, name, next) : null;
if (decisionModelError) return jsonResponse({ error: decisionModelError }, 400);
if (applied.editorTouched && !pacingOnly) {
const providerError = canonicalBudgetOnly
? canonicalOpenAiBudgetPatchError(next, rawBody, keys, config)
: providerManagementConfigError(
name,
providerTransportValidationCandidate(next as unknown as Record<string, unknown>),
// PATCH merges the mask onto the persisted row, which legitimately carries
// stored operator overlays (selectedModels, disabled, …); only the canonical
// transport/auth keys need to match the seed.
{ allowOperatorOverlays: true },
)
?? providerEmptyToolOutputConfigError(name, next);
if (providerError) return jsonResponse({ error: providerError }, 400);
if (!canonicalBudgetOnly) {
const catalogCapabilityError = providerCatalogCapabilityConfigError(name, next);
if (catalogCapabilityError) return jsonResponse({ error: catalogCapabilityError }, 400);
// Same DNS gate as POST and re-enable: the canonical built-in OpenAI forward
// provider may resolve through Clash/Mihomo fake-IP DNS (198.18.0.0/15), so the
// ordinary PATCH must not reject the very same destination the provider was
// created with. Loopback, RFC1918, metadata, and mixed dangerous answers still
// fail closed; nothing else gains the exception.
const allowBenchmarkAddresses = name === "openai" && isCanonicalOpenAiForwardProvider(next);
const resolvedError = await providerDestinationResolvedError(name, next, { allowBenchmarkAddresses });
if (resolvedError) return jsonResponse({ error: resolvedError }, 400);
}
if (decisionDependent()) {
const validation = validateConfigCandidate({ ...config, providers: { ...config.providers, [name]: next } });
if (!validation.ok) return jsonResponse({ error: validation.error }, 400);
}
} else if (applied.enablingOpenAi) {
// Same DNS gate as POST: Clash fake-IP only. Never honor a persisted
// allowPrivateNetwork on this path — it must not bypass the built-in guard.
const resolvedError = await providerDestinationResolvedError(
"openai",
{ baseUrl: CODEX_FORWARD_BASE_URL },
{ allowBenchmarkAddresses: true },
);
if (resolvedError) return jsonResponse({ error: resolvedError }, 400);
}
// The live config is shared and the destination probe above is awaited. Re-apply the
// mask onto the newest provider under the mutation lock right before saving, so two
// concurrent PATCHes updating different fields/headers both survive instead of the
// later save clobbering the earlier snapshot.
// Read before the save: once the provider is disabled the target no longer resolves (#5618).
const shadowDependency = rawBody.disabled === true && config.providers[name]!.disabled !== true
? shadowInterceptProviderDependency(config, name)
: null;
let replayError: string | undefined;
withConfigMutationLockSync(() => {
const replay = applyProviderPatchFields(name, config.providers[name]!, rawBody, keys, config);
if ("error" in replay) {
replayError = replay.error;
return;
}
if (replay.editorTouched && !pacingOnly) {
const syncError = canonicalBudgetOnly
? canonicalOpenAiBudgetPatchError(replay.next, rawBody, keys, config)
: providerManagementConfigError(
name,
providerTransportValidationCandidate(replay.next as unknown as Record<string, unknown>),
{ allowOperatorOverlays: true },
)
?? providerEmptyToolOutputConfigError(name, replay.next);
if (syncError) {
replayError = syncError;
return;
}
if (!canonicalBudgetOnly) {
const catalogCapabilityError = providerCatalogCapabilityConfigError(name, replay.next);
if (catalogCapabilityError) {
replayError = catalogCapabilityError;
return;
}
}
} else if (replay.enablingOpenAi && !isCanonicalOpenAiForwardProvider(replay.next)) {
replayError = "provider openai must be the canonical built-in provider";
return;
}
// A PATCH that managed headers owns the resulting block: the clear path restores
// registry static headers, so exact-match stripping must not erase them again.
const candidate = replay.headersTouched ? replay.next : stripRegistryOnlyStaticHeaders(name, replay.next);
const decisionModelError = replay.editorTouched ? decisionModelProviderPatchError(config, name, candidate) : null;
if (decisionModelError) { replayError = decisionModelError; return; }
const pinsTouched = Object.hasOwn(rawBody, "pinnedReasoningEffort") || Object.hasOwn(rawBody, "modelPinnedReasoningEfforts");
if (pinsTouched || (replay.editorTouched && !pacingOnly && decisionDependent())) {
const validation = validateConfigCandidate({ ...config, providers: { ...config.providers, [name]: candidate } });
if (!validation.ok) { replayError = validation.error; return; }
}
const previousOwnership = passiveProviderOwnership(config.providers[name]);
try {
commitProviderPatch(config, () => {
config.providers[name] = candidate;
}, deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode);
} finally {
// Persistence may rebase the row or publish before throwing. Compare the resulting
// live owner under the lock, after rollback when the save did not publish.
if (!isDeepStrictEqual(previousOwnership, passiveProviderOwnership(config.providers[name]))) {
clearPassiveKeyLimits(name);
}
}
});
if (replayError !== undefined) return jsonResponse({ error: replayError }, 409);
reconcileLiveStateStores();
if (applied.editorTouched && !pacingOnly) {
const { clearModelCache } = await import("../../codex/model-cache");
clearModelCache(name);
}
const catalogRefresh = pacingOnly ? null : await convergeCodexCatalog();
return jsonResponse({
success: true,
name,
disabled: config.providers[name]!.disabled === true,
hasApiKey: providerHasStoredApiKey(config.providers[name]!),
...(shadowDependency ? { dependentShadowIntercept: shadowDependency } : {}),
...(name === "xai"
? { xaiResponsesOptInState: xaiResponsesOptInState(config.providers[name]!) }
: {}),
catalogRefresh,
});
}
if (url.pathname === "/api/providers/test-completion" && req.method === "POST") return (await import("./provider-completion-test")).handleProviderCompletionTestRoute(ctx);
// Lightweight connectivity probe: perform the provider's live /models fetch DIRECTLY and
// report only real upstream evidence. The catalog aggregate (fetchAllModels) deliberately
// hides fetch failures behind stale/static fallbacks, so a catalog-presence check would
// let a static-catalog provider with a fake key "pass" — this endpoint never uses it.
if (url.pathname === "/api/providers/test" && req.method === "POST") {
const name = url.searchParams.get("name")?.trim();
if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) {
return jsonResponse({ error: "unknown provider" }, 404);
}
const prov = { ...config.providers[name]! };
const authorizedTarget = captureModelsOAuthTarget(name, prov);
if (prov.disabled) {
return jsonResponse({ ok: false, error: "Provider is disabled", latencyMs: 0 });
}
if (prov.authMode === "forward") {
return jsonResponse({
ok: true,
latencyMs: 0,
message: "Passthrough provider is configured (forwards your Codex login; no upstream /models).",
});
}
// Decision services answer through the bounded JEV client. A retargeted `jev` row is neither
// TypeSafe nor a self-hosted service, so it is not probed at all: its key stays unsent.
if (prov.adapter === "jev-decision") {
if (name === "jev" && !providerMatchesRegistryTransport(name, prov)) {
return jsonResponse({ applicable: false, reason: "retargeted_decision_service", latencyMs: 0 });
}
return jsonResponse(await probeJevDecisionProvider(config, name, { signal: req.signal }));
}
if (prov.liveModels === false) {
// No live discovery endpoint. Only Vertex ADC still has a credential to verify; every other
// static catalog must stay before credential resolution/network access (e.g. Antigravity).
const { staticCatalogConnectionTest } = await import("./static-catalog-probe");
return jsonResponse(await staticCatalogConnectionTest(name, prov, req.signal));
}
const { buildModelsRequest, getModelsOAuthAccessSnapshot, resolveModelsAuthToken } = await import("../../oauth");
const antigravity = effectiveGoogleMode(name, prov) === "cloud-code-assist";
const snapshot = prov.authMode === "oauth" && mayResolveModelsOAuth(name, config.providers[name])
? await getModelsOAuthAccessSnapshot(name, prov).catch(() => undefined)
: undefined;
const vertexDeadline = effectiveGoogleMode(name, prov) === "vertex" ? vertexDiscoveryDeadline(req.signal) : undefined;
let vertexAuth: VertexDiscoveryAuth | undefined;
const apiKey = prov.authMode === "oauth"
? snapshot?.accessToken
: vertexDeadline
? (vertexAuth = await resolveVertexDiscoveryAuth(prov, vertexDeadline))?.token
: await resolveModelsAuthToken(name, prov);
if ((prov.authMode === "oauth" || effectiveGoogleMode(name, prov) === "vertex") && !apiKey) {
return jsonResponse({ ok: false, latencyMs: 0, error: "static catalog only — upstream not verified (not logged in)" });
}
if (prov.adapter === "m365-copilot") return (await import("./m365-copilot-provider-probe")).probeM365CopilotProvider(name, prov, snapshot, req.signal);
if (prov.adapter === "zed") return (await import("./zed-provider-probe")).probeZedProvider(prov, apiKey, snapshot?.providerUserId);
if (prov.adapter === "cursor") {
const started = Date.now();
const live = await fetchCursorUsableModels({
apiKey: apiKey ?? "",
baseUrl: prov.baseUrl,
});
const latencyMs = Date.now() - started;
if (!live.ok) {
return jsonResponse({
ok: false,
latencyMs,
error: `cursor discovery ${live.error}${live.detail ? `: ${live.detail}` : ""}`,
});
}
return jsonResponse({
ok: true,
latencyMs,
models: live.models.length,
message: `Connected. ${live.models.length} models.`,
});
}
if (prov.adapter === "devin") {
const started = Date.now();
const configuredBase = name === "devin" ? getProviderRegistryEntry(name)?.baseUrl ?? prov.baseUrl : prov.baseUrl;
const destination = resolveDevinApiBaseUrl(snapshot?.apiBaseUrl ?? configuredBase);
const liveResult = await fetchDevinUsableModels({
apiKey: apiKey ?? "",
baseUrl: destination,
});
const latencyMs = Date.now() - started;
if (!liveResult.ok) {
return jsonResponse({
ok: false,
latencyMs,
error: `devin discovery ${liveResult.error}${liveResult.detail ? `: ${liveResult.detail}` : ""}`,
});
}
return jsonResponse({
ok: true,
latencyMs,
models: liveResult.models.length,
message: `Connected. ${liveResult.models.length} models.`,
});
}
if (prov.adapter === "qoder") {
// A late success re-syncs the catalog through the same convergence every mutation uses.
return (await import("./qoder-provider-probe")).probeQoderProvider(name, prov, apiKey, convergeCodexCatalog);
}
const project = prov.project ?? snapshot?.projectId;
if (antigravity && !project) {
return jsonResponse({ ok: false, latencyMs: 0, error: "Antigravity project unavailable — re-run `ocx login google-antigravity`" });
}
const { method, url: modelsUrl, headers } = buildVertexProviderModelsRequest(name, prov, apiKey)
?? buildModelsRequest(prov, apiKey, name, { oauthApiBaseUrl: snapshot?.apiBaseUrl, workbuddy: snapshot?.workbuddy });
const discovery = resolveProviderModelDiscovery(name, prov);
const started = Date.now();
try {
// Same canonical-URL TUN transparency as catalog discovery: the registry's
// own fixed discovery URL survives purely-benchmark (Clash/Surge/Mihomo
// fake-IP) DNS without proxy env.
const outboundDependencies = (requestUrl: string) => ({ isCanonicalUrl: isRegistryModelDiscoveryUrl,
beforeSend: () => (!vertexAuth || vertexDiscoveryAuthIsCurrent(prov, vertexAuth, headers, requestUrl))
&& (prov.authMode !== "oauth" || (mayResolveModelsOAuth(name, config.providers[name])
&& modelsOAuthTargetMatches(name, config.providers[name], authorizedTarget)
&& (name !== "anthropic2" || new URL(requestUrl).href === authorizedTarget))) });
const res = method === "POST"
? await providerOutboundPost(name, prov, modelsUrl, {
headers,
body: JSON.stringify({ project }),
signal: AbortSignal.timeout(8000),
}, outboundDependencies(modelsUrl))
: await providerOutboundGet(name, prov, modelsUrl, {
headers,
signal: vertexDeadline ?? AbortSignal.timeout(8000),
}, outboundDependencies(modelsUrl));
const latencyMs = Date.now() - started;
const redirectError = await providerRedirectError(res, modelsUrl);
if (redirectError) {
return jsonResponse({
ok: false,
latencyMs,
error: redirectError,
});
}
if (!res.ok) {
if (isXaiGrokOAuth(name, prov) && await readXaiLegacyPrivacyError(res)) {
return jsonResponse({ ok: false, latencyMs, error: XAI_LEGACY_PRIVACY_MESSAGE });
}
try {
void res.body?.cancel().catch(() => undefined);
} catch {
// Best-effort release for non-conforming response streams.
}
return jsonResponse({ ok: false, latencyMs, error: `upstream model discovery returned ${res.status}` });
}
const vertexFirstPage = vertexDeadline ? countDiscoveryResponseBytes(res) : undefined;
const bounded = await readBoundedDiscoveryJson(vertexFirstPage?.response ?? res, discovery.maxResponseBytes);
if (!bounded.ok) {
return jsonResponse({
ok: false,
latencyMs,
error: bounded.reason === "response_too_large"
? `upstream model discovery exceeded the ${discovery.maxResponseBytes}-byte response limit`
: "upstream model discovery returned invalid JSON",
});
}
const ccaModels = antigravity ? parseAntigravityAvailableModels(bounded.value, discovery.maxModels) : undefined;
if (antigravity && !ccaModels) {
return jsonResponse({ ok: false, latencyMs, error: "upstream CCA model discovery returned an unexpected shape" });
}
const listing = !ccaModels && vertexDeadline
? await collectVertexPublisherModelPages(modelsUrl, bounded.value,
{ ...discovery, firstPageBytes: vertexFirstPage?.bytes(), signal: vertexDeadline },
(pageUrl, signal) => providerOutboundGet(name, prov, pageUrl, { headers, signal }, outboundDependencies(pageUrl)))
: { ok: true as const, value: bounded.value };
if (!listing.ok) return jsonResponse({ ok: false, latencyMs, error: `upstream Vertex model listing is incomplete: ${listing.diagnostic}` });
// OpenAI-style lists (and Together top-level arrays) use the same validation/dedupe/filter
// as catalog discovery. Google AI Studio parses the native `models[]` envelope and filters to
// `generateContent`, while other providers fall back to generic envelope rows if they return `models[]`.
const record = listing.value !== null && typeof listing.value === "object" && !Array.isArray(listing.value)
? listing.value as Record<string, unknown>
: undefined;
const googleNative = !ccaModels
? extractGoogleNativeModelItems(name, prov, listing.value, discovery.maxModels)
: undefined;
const extracted = ccaModels
? undefined
: googleNative
?? (Array.isArray(listing.value) || Array.isArray(record?.data)
? extractProviderModelItems(listing.value, discovery)
: extractModelEnvelopeRows(listing.value, discovery.maxModels, ["models"]));
if (extracted && !extracted.ok) {
return jsonResponse({
ok: false,
latencyMs,
error: extracted.reason === "too_many_models"
? `upstream /models exceeded the ${discovery.maxModels}-row model limit`
: `upstream /models returned an unexpected shape${invalidModelDiscoveryHint("diagnostic" in extracted && typeof extracted.diagnostic === "string" ? extracted.diagnostic : undefined, discovery.skipInvalidRows === true)}`,
});
}
const models = ccaModels?.length ?? ("items" in extracted! ? extracted!.items.length : extracted!.rows.length);
return jsonResponse({
ok: true,
latencyMs,
models,
message: `Connected — ${models} model${models === 1 ? "" : "s"} available${extracted && "skippedInvalidRows" in extracted && extracted.skippedInvalidRows ? ` (${extracted.skippedInvalidRows} invalid row${extracted.skippedInvalidRows === 1 ? "" : "s"} skipped)` : ""}.`,
});
} catch (err) {
return jsonResponse({
ok: false,
latencyMs: Date.now() - started,
error: err instanceof ProviderOutboundPolicyError
? `upstream /models blocked by destination policy: ${err.message}`
: err instanceof Error ? err.message : "Connection test failed",
});
}
}
if (url.pathname === "/api/providers" && req.method === "DELETE") {
const name = url.searchParams.get("name")?.trim();
if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
// Config validation requires a default provider. Reassigning before deletion keeps
// the persisted config valid and makes removal of the current default a one-step UI
// operation. Prefer the first remaining *enabled* provider so DELETE cannot leave a
// disabled default that setDefault / disable already refuse. Object-key order is the
// documented configuration order and is stable through JSON persistence.
const fallbackDefault = name === config.defaultProvider
? Object.entries(config.providers)
.find(([provider, providerConfig]) => provider !== name && providerConfig.disabled !== true)
?.[0]
: undefined;
if (name === config.defaultProvider && !fallbackDefault) {
return jsonResponse({
error: "cannot delete the default provider when no enabled replacement remains",
code: "last_provider",
}, 409);
}
const dependentCombos = Object.entries(config.combos ?? {})
.filter(([, combo]) => comboDependsOnProviderRoute(config, combo, name))
.map(([id]) => id)
.sort((a, b) => a.localeCompare(b));
if (dependentCombos.length > 0) {
return jsonResponse({
error: `cannot delete provider "${name}" while combos depend on it`,
code: "provider_has_dependent_combos",
combos: dependentCombos,
}, 409);
}
const { saveConfigPreservingClaudeCode: save } = await import("../../config");
// Deleting still succeeds; the response names the shadow-call target left without a provider.
const shadowDependency = shadowInterceptProviderDependency(config, name);
const droppedCustomModels = removeProviderWithGcpCredentials(config, name, fallbackDefault, save);
await releaseRemovedProviderCredentials(config, name);
reconcileLiveStateStores();
const { clearModelCache: clearCache } = await import("../../codex/model-cache");
clearCache(name);
const catalogRefresh = await convergeCodexCatalog();
return jsonResponse({
success: true,
...(fallbackDefault ? { defaultProvider: fallbackDefault } : {}),
...(droppedCustomModels > 0 ? { droppedCustomModels } : {}),
...(shadowDependency ? { dependentShadowIntercept: shadowDependency } : {}),
catalogRefresh,
});
}
if (url.pathname === "/api/provider-context-caps" && req.method === "GET") {
return jsonResponse({ cap: DEFAULT_PROVIDER_CONTEXT_CAP, value: globalContextCapValue(config), caps: providerContextCaps(config), values: selectedProviderContextCaps(config) });
}
if (url.pathname === "/api/provider-context-caps" && req.method === "PUT") {
let rawBody: unknown;
try { rawBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
// Reject non-object payloads (e.g. `{"provider": true}` or a bare array) before any
// property access, with the route's consistent 400 response.
if (!isPlainRecord(rawBody)) return jsonResponse({ error: "provider-context-caps body must be a plain object" }, 400);
const body = rawBody as { provider?: unknown; enabled?: unknown; value?: unknown; setAll?: unknown };
const { saveConfigPreservingClaudeCode: save } = await import("../../config");
const { clearModelCache } = await import("../../codex/model-cache");
const respond = (catalogRefresh: Awaited<ReturnType<typeof convergeCodexCatalog>>) => jsonResponse({
ok: true,
cap: DEFAULT_PROVIDER_CONTEXT_CAP,
value: globalContextCapValue(config),
caps: providerContextCaps(config), values: selectedProviderContextCaps(config),
catalogRefresh,
});
// Reject malformed and mixed payloads before branch selection: `provider` and `enabled`
// must appear together with their expected types, and provider updates cannot be
// combined with `setAll` (which would otherwise be silently ignored).
const hasProviderFields = Object.hasOwn(body, "provider") || Object.hasOwn(body, "enabled");
if (hasProviderFields) {
if (typeof body.provider !== "string" || typeof body.enabled !== "boolean") {
return jsonResponse({ error: "provider and enabled are required together" }, 400);
}
if (Object.hasOwn(body, "setAll")) {
return jsonResponse({ error: "setAll cannot be combined with provider updates" }, 400);
}
}
// Branch 1: per-provider toggle (checked first: a per-provider request may carry an
// explicit `value`, which must never fall through to the global-value branch). Enable
// restores the selected provider value, then the global default, unless an explicit
// per-provider value is supplied; that value is never copied to other providers.
if (typeof body.provider === "string" && typeof body.enabled === "boolean") {
const provider = body.provider.trim();
if (!isValidProviderName(provider)) {
return jsonResponse({ error: "provider name must use letters, numbers, dot, underscore, or hyphen and cannot be a reserved object key" }, 400);
}
if (!hasOwnProvider(config.providers, provider)) {
return jsonResponse({ error: "unknown provider" }, 404);
}
// Validate a supplied per-provider value before mutating anything: it must be a
// finite number, and after flooring it must still be >= 1 — a value like 0.5 would
// otherwise floor to 0 and silently fall back to the global default.
if (body.value !== undefined && (typeof body.value !== "number" || !Number.isFinite(body.value))) {
return jsonResponse({ error: "value must be a positive number" }, 400);
}
const perProviderValue = typeof body.value === "number" ? Math.floor(body.value) : undefined;
if (perProviderValue !== undefined && perProviderValue < 1) {
return jsonResponse({ error: "value must be a positive number" }, 400);
}
setProviderContextCap(config, provider, body.enabled, perProviderValue);
save(config);
reconcileLiveStateStores();
clearModelCache(provider);
const catalogRefresh = await convergeCodexCatalog();
return respond(catalogRefresh);
}
// Branch 2: set the global cap value. When `setAll` accompanies it (dashboard "apply to
// every routed provider" toggle), re-point every enabled provider; otherwise keep each
// provider's own cap value and only change the default for future toggles.
if (body.value !== undefined) {
// Same normalization as the per-provider branch: floor before validating so a value
// that floors to zero is rejected rather than silently stored.
if (typeof body.value !== "number" || !Number.isFinite(body.value)) {
return jsonResponse({ error: "value must be a positive number" }, 400);
}
const normalizedValue = Math.floor(body.value);
if (normalizedValue < 1) {
return jsonResponse({ error: "value must be a positive number" }, 400);
}
if (body.setAll !== undefined && typeof body.setAll !== "boolean") {
return jsonResponse({ error: "setAll must be a boolean" }, 400);
}
const affected = Object.keys(providerContextCaps(config));
const applyToAll = body.setAll === true;
setGlobalContextCapValue(config, normalizedValue, applyToAll);
save(config);
reconcileLiveStateStores();
if (applyToAll) {
for (const provider of affected) clearModelCache(provider);
}
const catalogRefresh = await convergeCodexCatalog();
return respond(catalogRefresh);
}
// Branch 3: enable/clear the cap for every provider at once.
if (body.setAll !== undefined) {
if (typeof body.setAll !== "boolean") {
return jsonResponse({ error: "setAll must be a boolean" }, 400);
}
const before = Object.keys(providerContextCaps(config));
const names = Object.keys(config.providers);
setAllProviderContextCaps(config, names, body.setAll);
save(config);
reconcileLiveStateStores();
for (const provider of new Set([...before, ...names])) clearModelCache(provider);
const catalogRefresh = await convergeCodexCatalog();
return respond(catalogRefresh);
}
// Unrecognized payload: reject rather than silently succeeding.
return jsonResponse({ error: "provider string and enabled boolean are required" }, 400);
}
// The standalone Vite GUI consumes these canonical registry presets through the API.
if (url.pathname === "/api/provider-presets" && req.method === "GET") {
return jsonResponse({ providers: deriveProviderPresets() });
}
return null;
}