@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
996 lines • 52.2 kB
text/typescript
import { dashboardTrustedProxySchema } from "../dashboard-trusted-proxy";
import { MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT } from "../../codex/quota-types";
import { validRemainingQuotaAccountIds } from "../../codex/account-use-remaining";
import * as z from "zod/v4";
import { isToolLoadingModelSelectors } from "../../claude/inbound-tool-loading";
import { accountPauseStateSchema } from "./account-auto-pause";
import { anthropicAccountPoolSchema } from "./anthropic-account-pool";
import { compactionRecoverySchema } from "./compaction-recovery";
import { nativeReasoningRetentionSchema } from "./native-reasoning-retention";
import { workflowBudgetSchema } from "./workflow-budget";
import { routedCatalogDefaultsSchema } from "./routed-catalog-defaults";
import { desktopCompatibilitySchema } from "./desktop-compatibility";
import { blockedModelRedirectsSchema } from "./blocked-model-redirects";
import { mainAccountHardLockFallbackSchema } from "./main-account-hard-lock-fallback";
import { fallbackPolicySchema } from "./fallback-policy";
import { subscriptionReserveSchema } from "./subscription-reserve";
import {
agentTaskRecoverySchema,
catalogAutoRefreshSchema,
clientConnectionSchema,
CODEX_ACCOUNT_PIN_PATTERN,
codexAccountPrioritiesSchema,
salvageCodexAccountAutoSwitchThresholds,
codexAuthMethodSchema,
codexPoolSchema,
codexQuotaAutoRefreshSchema,
credentialGroupsSchema,
hubConfigSchema,
providerConfigSchema,
quotaResetNotifySchema,
remoteGuiConfigSchema,
runtimeRoleSchema,
spendSchema,
chatgptDesktopSchema,
skillsConfigSchema,
telemetryConfigSchema,
configuredCodexPoolAccountIds,
apiKeyEntrySchema,
asideProfileSyncSchema,
clientIntegrationsSchema,
opencodeClientExportSchema,
omoClientExportSchema,
CODEX_ACCOUNT_NAMESPACE_ACCOUNT_ID_COLLISION_ERROR,
codexAccountNamespacesSchema,
modelPinnedEffortsSchema,
autoReviewOverrideSchema,
compactionRoutingSchema,
reasoningRetentionSchema,
memoryModelSettingSchema,
memoryModelsSchema,
modelPreferHostedToolsConfigError,
providerModelCostsConfigError,
providerRelativeSendPathConfigError,
isValidCreditPriceUsd,
} from "./leaf-validators";
import { MAX_CREDIT_PRICE_USD } from "../../usage/credit-billing";
import { isValidProviderName, hasOwnProvider } from "../provider-name";
import {
apiKeyTransportConfigError,
booleanRecordConfigError,
modelAdapterRecordConfigError,
modelDisplayNamesConfigError,
nonBlankStringArrayConfigError,
positiveIntegerConfigError,
positiveIntegerRecordConfigError,
providerBaseUrlConfigError,
providerHeadersConfigError,
providerForwardClientHeadersConfigError,
reasoningSummaryDeliveryRecordConfigError,
thinkingDisplayConfigError,
modelThinkingDisplayConfigError,
credentialPinnedProviderConfigError,
} from "../provider-validation";
import {
CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR,
codexAccountNamespaceForModel,
codexProviderNamespaceKey,
MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET,
} from "../../codex/account-namespace-match";
import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "../../codex/upstream-host-health";
import { MIN_USAGE_LEDGER_MAX_BYTES } from "../../usage/retention-contract";
// The schema boundary uses a string-only stand-in for the ingress grammar: importing the server
// parser here would cycle back through config loading and run Cursor detection during validation.
import { COMBO_NAMESPACE, comboConfigIssues, lexicalDecisionModelBase } from "../../combos/types";
import { routingProfileIssues } from "../../routing/profile";
import { agyAcpConfigIssues } from "./agy-acp-references";
import { POLICY_NAMESPACE } from "../../routing/profile-namespace";
import { providerDestinationConfigError } from "../../lib/destination-policy";
import { providerTlsProfileConfigError } from "../../lib/provider-tls-profile";
import { redactSecretString } from "../../lib/redact";
import { openRouterRoutingConfigError } from "../../providers/openrouter-routing";
import { vercelGatewayRoutingConfigError } from "../../providers/vercel-gateway-routing";
import { type OcxApiKeyEntry, type OcxProviderConfig } from "../../types";
import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import { modelAutoCompactTokenLimitsConfigError } from "../../providers/auto-compact-budget";
import { hasFastWireCapabilityConflict } from "../../providers/fastwire";
import { parseDesktopProfile } from "../../claude/desktop-profile";
import { parseDesktopModelVisibility } from "../../claude/desktop-model-visibility";
import { isInterceptBindingId, isInterceptBindingRoute } from "../../claude/intercept/model-bindings";
import { DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES, MAX_APP_OWNED_MEMORY_BUDGET_MB, MIN_APP_OWNED_MEMORY_BUDGET_MB } from "../../lib/app-owned-memory";
/** Strict write contract; file-load recovery is applied only by the enclosing schema. */
export const protocolConfigSchema = z.object({
unrepresentable: z.enum(["legacy", "reject"]).optional(),
rollout: z.object({
nativeChatCombos: z.boolean().optional(),
managedMessagesNative: z.boolean().optional(),
managedMessagesNativeOAuth: z.boolean().optional(),
directEncoders: z.boolean().optional(),
antigravityDirect: z.boolean().optional(),
geminiNativeAntigravity: z.boolean().optional(),
shadowPlan: z.boolean().optional(),
}).strict().optional(),
}).strict();
export const configSchema = z.object({
// Malformed hand edits disable only this opt-in. Candidate writes reject them.
subscriptionReserve: subscriptionReserveSchema.optional().catch(undefined),
chatgptDesktop: chatgptDesktopSchema.optional().catch(undefined),
codexNativeSteering: z.boolean().optional().catch(false),
codexNativeInjection: z.boolean().optional().catch(false),
port: z.number().int().min(0).max(65535).default(10100),
// A malformed hand edit must disable only remote-role behavior, not discard
// providers or data-plane keys. Live writes are rejected explicitly below.
runtimeRole: runtimeRoleSchema.optional().catch(undefined),
// Malformed optional remote blocks disable only remote GUI behavior. Live
// candidates are rejected explicitly by remoteGuiConfigError below.
hub: hubConfigSchema.optional().catch(undefined),
// #8338: a malformed hand edit disables only the trusted-proxy opt-in (Remember then stays direct
// HTTPS or loopback only); live writes get the exact reason from diagnostics.ts.
dashboardTrustedProxy: dashboardTrustedProxySchema.optional().catch(undefined),
remoteGui: remoteGuiConfigSchema.optional().catch(undefined),
// A malformed privacy block must never be read as "unmask": .catch(undefined) drops it and
// emailMaskingEnabled then falls back to masked, which is also what an absent block means.
privacy: z.object({ maskEmails: z.boolean().optional() }).strict().optional().catch(undefined),
skills: skillsConfigSchema.optional().catch(undefined),
// Malformed hand edits disable this opt-in exporter. Live writes reject them in diagnostics.ts.
metricsExport: z.object({ enabled: z.boolean().optional() }).strict().optional().catch(undefined),
telemetry: telemetryConfigSchema.optional().catch(undefined),
// Same contract as metricsExport: a malformed hand edit leaves recovery off; live writes reject it.
serviceHealthRecovery: z.object({ enabled: z.boolean().optional() }).strict().optional().catch(undefined),
// Kept raw on purpose: `.catch(undefined)` would turn a mistyped `enabled` into "inherit",
// which can reopen a surface the operator meant to close. src/protocols/settings.ts parses it
// and fails closed instead.
apiSurfaces: z.unknown().optional(),
// Keep malformed native policy disabled even when an enabled pool supplies defaults.
protocols: protocolConfigSchema.optional().catch(ctx => {
const raw = ctx.input;
const protocols = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
const rollout = protocols.rollout;
const fields = rollout && typeof rollout === "object" && !Array.isArray(rollout) ? rollout as Record<string, unknown> : {};
return {
unrepresentable: protocols.unrepresentable === "reject" ? "reject" as const : "legacy" as const,
rollout: {
nativeChatCombos: fields.nativeChatCombos === true,
managedMessagesNative: false,
managedMessagesNativeOAuth: false,
directEncoders: fields.directEncoders === true,
antigravityDirect: fields.antigravityDirect === true,
geminiNativeAntigravity: false,
shadowPlan: fields.shadowPlan === true,
},
};
}),
// A malformed present client block must remain diagnosable from raw config and
// fail closed through src/client/state.ts; unrelated provider state still loads.
client: clientConnectionSchema.optional().catch(undefined),
managementUsageMaxReadBytes: z.number().int().positive().default(64 * 1024 * 1024).describe(
"Deprecated compatibility limit for bounded legacy usage readers; GET /api/usage always aggregates the complete ledger",
),
// Opt-in ledger ceiling. A hand edit below the floor, or a non-safe integer, disables only
// this limit rather than failing the config: refusing to start because history retention was
// mistyped would be a worse outcome than not trimming history.
usageLedgerMaxBytes: z.number().int()
.min(MIN_USAGE_LEDGER_MAX_BYTES)
.max(Number.MAX_SAFE_INTEGER)
.optional()
.catch(undefined),
// Invalid hand edits disable only this opt-in circuit. Live writes remain strict.
upstreamHostCircuitThreshold: z.number().int()
.min(0)
.max(UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD)
.optional()
.catch(undefined),
// Opt-in outbound body ceiling. An invalid hand edit disables only this guard, matching the
// circuit threshold above: a malformed number must not make the proxy refuse traffic.
maxUpstreamBodyBytes: z.number().int()
.min(0)
.optional()
.catch(undefined),
// Opt-in outbound request compression (#7247). An unknown codec degrades to identity, matching
// the guards above: a hand-edit typo must not change what the proxy sends or refuse traffic.
upstreamRequestCompression: z.enum(["off", "gzip", "zstd"]).optional().catch(undefined),
upstreamHistorySlim: z.enum(["off", "codex"]).optional().catch(undefined),
// Opt-in inbound body ceiling (#3573). An invalid hand edit degrades to the 256 MiB default
// rather than failing the parse, matching the outbound guard above: a malformed number must
// not change what the proxy admits. The hard ceiling is NOT enforced here — because of that
// `.catch`, and because a config object can be built without this schema at all — but in
// `resolveInboundBodyLimitBytes()`, which every reader goes through.
maxInboundBodyBytes: z.number().int()
.min(0)
.optional()
.catch(undefined),
// Match the per-body load/degrade contract: malformed hand edits retain providers.
// The shared resolver clamps runtime admission to 512 MiB..2 GiB even when the
// caller bypasses this schema; omission and zero retain the 512 MiB default.
// Home-side per-body zstd advertisement on Remote Links (#3023); anything but a boolean reads as unset, which is on.
linkRequestCompression: z.boolean().optional().catch(undefined),
maxConcurrentInboundBodyBytes: z.number().int()
.min(0)
.optional()
.catch(undefined),
appOwnedMemoryBudgetMb: z.number().int()
.min(MIN_APP_OWNED_MEMORY_BUDGET_MB)
.max(MAX_APP_OWNED_MEMORY_BUDGET_MB)
.default(DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES / (1024 * 1024))
.catch(DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES / (1024 * 1024)),
// A blank hostname degrades to undefined rather than failing the parse. `getDefaultConfig()`
// carries no `hostname` key, so the backup-and-defaults repair path below cannot merge one
// away — a hand-edited `"hostname": ""` would fail twice and reset providers/apiKeys to
// defaults, which is strictly worse than the bind bug this validation exists for. Degrading
// is safe: startServer() already falls back to 127.0.0.1 for a missing hostname. Write-time
// rejection lives in validateConfigCandidate() so bad values still surface to the caller.
hostname: z.string().trim().min(1).optional().catch(undefined),
// Discriminated on `enabled` so a disabled entry cannot be forced to carry a port (#1102).
// An enabled one MAY omit it: that is the companion form, which binds 127.0.0.1 on the proxy
// port and is legal only off a loopback/wildcard bind — a relationship between two fields, so
// it is enforced in validateConfigCandidate() and again at startup, not here (#4236).
// A malformed value degrades to undefined rather than failing the whole parse: this is an
// opt-in convenience surface, and a hand-edit typo here must never reset providers/apiKeys
// through the backup-and-defaults repair path.
unauthenticatedLoopbackListener: z.union([
z.object({ enabled: z.literal(false) }),
z.object({ enabled: z.literal(true), port: z.number().int().min(1).max(65535).optional() }),
]).optional().catch(undefined),
providers: z.record(z.string(), providerConfigSchema),
// Models settings panel writes the global reviewer override; an invalid hand edit is
// stripped by load degradation so it cannot reject the providers that carry it.
autoReviewOverride: autoReviewOverrideSchema.optional(),
modelPinnedEfforts: modelPinnedEffortsSchema.optional(),
compactionRouting: compactionRoutingSchema.optional().catch(undefined),
compactionRecovery: compactionRecoverySchema.optional().catch(undefined),
// A bad hand edit disables only this block; writes validate the catch-free leaf first.
reasoningRetention: reasoningRetentionSchema.optional().catch(undefined),
nativeReasoningRetention: nativeReasoningRetentionSchema.optional().catch(undefined),
// A bad hand edit falls back to the built-in ceilings; it never turns the guard off.
workflowBudget: workflowBudgetSchema.optional().catch(undefined),
// A bad hand edit drops the whole block, so routed rows keep today's derivation (#6872).
routedCatalogDefaults: routedCatalogDefaultsSchema.optional().catch(undefined),
desktopCompatibility: desktopCompatibilitySchema.optional().catch(undefined),
// A hand-edited malformed phase disables only that phase instead of rejecting
// providers/apiKeys, matching the load-time degradation notice; the management write
// boundary (validateConfigCandidate) still refuses the bad value through the shared,
// catch-free memoryModelsSchema.
memoryModels: z
.object({
extract: memoryModelSettingSchema.optional().catch(undefined),
consolidation: memoryModelSettingSchema.optional().catch(undefined),
})
.optional()
.catch(undefined),
defaultProvider: z.string().min(1).default("openai"),
defaultModelAliases: z.boolean().optional(),
preferModelAliasIds: z.boolean().optional().catch(false),
// Catalog omission is opt-in; malformed hand edits preserve the hidden-row default.
omitDisabledNativeModels: z.boolean().optional().catch(false),
// Malformed hand edits disable this opt-in projection without rejecting providers.
cursorEffortRows: z.boolean().optional().catch(false),
// Fast selectors default on; malformed hand edits disable them without rejecting providers.
fastRows: z.boolean().default(true).catch(false),
// Ultra Fast is opt-in for the same reason and degrades the same way: a malformed hand
// edit turns the tier off rather than rejecting the config that carries it.
ultraFastTier: z.boolean().optional().catch(false),
// Default-on policy (#5694): absence and malformed hand edits both mean "on", and only an
// explicit `false` written by the settings PUT opts out.
codexMainAccountHardLock: z.boolean().optional().catch(undefined),
codexMainAccountHardLockThresholds: z.object({
short: z.number().int().min(MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT).max(100).optional().catch(undefined),
long: z.number().int().min(MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT).max(100).optional().catch(undefined),
}).optional().catch(undefined),
// A malformed fallback section disables only the reroute, never the lock's refusal
// behavior; the management write boundary still rejects the bad value.
codexMainAccountHardLockFallback: mainAccountHardLockFallbackSchema.optional().catch(undefined),
// OCX-11: a malformed section reads as absent, which keeps today's fallback behavior.
fallback: fallbackPolicySchema.optional().catch(undefined),
// #2999: a malformed hand edit falls back to auto detection rather than rejecting the config.
nativeMainRefresh: z.enum(["codex", "opencodex"]).optional().catch(undefined),
// Future versions remain opaque through passthrough-compatible whole-config saves.
// Only version 1 grants deletion authority in the rebase path.
configRebaseProvenance: z.unknown().optional(),
// A retry can be billable, so absence and malformed hand edits both stay off.
emptyCompletionRetry: z.boolean().optional().catch(false),
// Header suppression changes what Codex sees, so absence and malformed edits stay off.
dropCodexSafetyBuffering: z.boolean().optional().catch(false),
completeOnMaxOutputTokens: z.boolean().optional().catch(false),
// A malformed hand edit must not silently stop opening the browser: fall back
// to undefined, which resolves to the historical auto-open behavior.
oauthOpenBrowser: z.boolean().optional().catch(undefined),
// A malformed hand edit falls back to the historical behavior rather than
// discarding the config; diagnostics still report it as invalid.
codexAuthMethod: codexAuthMethodSchema.catch(undefined),
showCodexCredits: z.boolean().optional().catch(false),
openaiProviderTierVersion: z.union([z.literal(1), z.literal(2)]).optional(),
// Invalid hand edits must not discard an otherwise usable config.
googleAntigravityStaticCatalogVersion: z.union([z.literal(1), z.literal(2)]).optional().catch(undefined),
subagentModelsVersion: z.number().int().positive().optional().catch(undefined),
subagentModels: z.array(z.string().min(1)).optional().catch(undefined),
// A hand-edited advisory version must not cost the operator their providers; a bad
// value degrades to undefined, which simply raises the notice again.
multiAgentSurfaceAdvisoryVersion: z.number().int().nonnegative().optional().catch(undefined),
clientIntegrations: clientIntegrationsSchema.optional().catch(undefined),
// Opt-in opencode-side export timeouts; a malformed block degrades to undefined so opencode
// keeps its native waits rather than failing the parse and hiding valid providers/accounts.
opencodeClientExport: opencodeClientExportSchema.optional().catch(undefined),
omoClientExport: omoClientExportSchema.optional().catch(undefined),
// A malformed profile policy must not fall back to legacy all-profile activation.
asideProfileSync: asideProfileSyncSchema.optional().catch({ allProfiles: false }),
providerContextCaps: z.record(z.string(), z.number().int().positive()).optional(),
providerContextCapValues: z.record(z.string(), z.number().int().positive()).optional(),
contextCapValue: z.number().int().positive().optional(),
multiAgentGuidanceEnabled: z.boolean().optional(),
// Invalid optional recovery config must not discard unrelated provider/account state.
plaintextV2AgentMessages: z.boolean().optional().catch(undefined),
agentTaskRecovery: agentTaskRecoverySchema.optional().catch(undefined),
// Same rationale: a bad notify section must not cost the operator their providers.
quotaResetNotify: quotaResetNotifySchema.optional().catch(undefined),
// Same rationale: a bad auto-refresh section must not cost the operator their providers.
catalogAutoRefresh: catalogAutoRefreshSchema.optional().catch(undefined),
// Same rationale again, with the failure direction stated: a malformed spend section
// degrades to "no ceiling", which means observe-only accounting rather than an outage. That
// is the safe degrade for traffic and the dangerous one for the operator, so the write path
// rejects it and loadConfig warns -- the same pair codexPool uses below.
spend: spendSchema.optional().catch(undefined),
// These selections pre-date schema validation and used to pass through as
// unknown fields. Invalid hand edits must disable only the optional
// delegation/native-default feature, not reject the whole config and hide
// otherwise valid providers, accounts, or the configured listen port.
injectionModel: z.string().optional().catch(undefined),
injectionEffort: z.string().optional().catch(undefined),
syncCodexSubagentDefaults: z.boolean().optional().catch(undefined),
// Per-primary-model fallback chains. Values must be non-empty string arrays;
// malformed entries degrade to undefined rather than rejecting the whole config.
subagentModelFallbackByModel: z.record(
z.string(),
z.array(z.string().trim().min(1)).min(1),
).optional().catch(undefined),
// Advisory input to role auto-assign only; a malformed block falls back to price ranking.
codexRoleTiers: z.object({
fast: z.array(z.string().trim().min(1)).optional(),
standard: z.array(z.string().trim().min(1)).optional(),
frontier: z.array(z.string().trim().min(1)).optional(),
}).strict().optional().catch(undefined),
// Discard the retired source while preserving an otherwise valid Artificial Analysis key.
codexRoleCapability: z.preprocess(value => {
if (!value || typeof value !== "object" || Array.isArray(value)) return value;
const { huggingFace: _retired, ...rest } = value as Record<string, unknown>;
return rest;
}, z.object({
artificialAnalysis: z.object({ apiKey: z.string().trim().min(1).optional() }).strict().optional(),
}).strict().optional().catch(undefined)),
codexShimAutoRestore: z.boolean().optional(),
codexDesktopAuthless: z.boolean().optional().catch(undefined),
codexReserveEnabled: z.boolean().optional().catch(undefined),
// A malformed marker degrades to unmigrated, which reseeds from the persisted authless flag.
codexReserveMigration: z.number().int().positive().optional().catch(undefined),
codexClientCompaction: z.boolean().optional().catch(undefined),
// Presentation-only label for the injected provider. A malformed value degrades to undefined
// and the default label is emitted, rather than failing the parse or writing a config Codex
// would refuse to load — the provider id routing depends on is never derived from it.
codexProviderDisplayName: z.string().trim().min(1).max(128).optional().catch(undefined),
// Preserve an invalid marker: silently treating corrupt epochs as legacy would grant stale attempts authority.
accountAutoPausePolicyRevisions: z.record(z.string(), z.uuid()).nullable().optional().catch(null),
// Details are display-only; keep each usable resume revision and the separate paused-id authority.
codexAccountPauseState: z.preprocess(value => {
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
return Object.fromEntries(Object.entries(value).flatMap(([id, row]) => {
if (!row || typeof row !== "object" || Array.isArray(row) || typeof row.revision !== "string") return [];
const parsed = accountPauseStateSchema.safeParse({ [id]: row });
return [[id, parsed.success ? parsed.data[id] : { revision: row.revision }]];
}));
}, accountPauseStateSchema.optional()),
pausedCodexAccountIds: z.array(z.string().regex(/^[a-zA-Z0-9._-]{1,64}$/)).optional(),
// A malformed allow-list degrades to "no account spends credits" rather than failing the parse,
// so a hand-edited typo cannot trip the backup-and-defaults repair path; the write path rejects
// it (creditCodexAccountIdsError in diagnostics).
creditCodexAccountIds: z.array(z.string().regex(/^[a-zA-Z0-9._-]{1,64}$/)).optional().catch(undefined),
codexUseRemainingQuotaAccountIds: z.custom<string[]>(validRemainingQuotaAccountIds).optional().catch(undefined),
// A malformed policy degrades to "no policy" rather than failing the parse, so a hand-edited
// typo cannot trip the backup-and-defaults repair path and wipe providers or pool accounts.
// Silently ignoring it would be its own trap, so the write path rejects it and loadConfig warns.
codexPool: codexPoolSchema.optional().catch(undefined),
codexQuotaAutoRefresh: codexQuotaAutoRefreshSchema.optional().catch(undefined),
codexAccountNamespaces: codexAccountNamespacesSchema.optional(),
// Selection order is a preference, not a safety control like pause: a malformed
// map degrades to "no ordering" rather than failing the parse, so a hand-edited
// typo cannot trip the backup-and-defaults repair path and wipe providers or
// pool accounts. Warning emitted in loadConfig.
codexAccountPriorities: codexAccountPrioritiesSchema.optional().catch(undefined),
// A bad hand-edited entry must not retire valid overrides on the next unrelated save.
codexAccountAutoSwitchThresholds: z.unknown().optional().transform(salvageCodexAccountAutoSwitchThresholds),
// An invalid optional preference must not discard providers or credential rows.
codexAccountPriorityFailback: z.boolean().optional().catch(false),
codexPreserveSignedInAccount: z.boolean().optional().catch(false),
// Absent or invalid keeps the sliding window on. Explicit false restores consecutive-only steering.
codexFailureWindow: z.boolean().optional().catch(undefined),
codexPinnedTransientPolicy: z.enum(["hold", "detour-new-threads"]).optional().catch("hold"),
codexWsReuseAcrossTurns: z.boolean().optional().catch(false),
codexWsIncrementalUpload: z.boolean().optional().catch(false),
activeCodexAccountPinned: z.string().regex(CODEX_ACCOUNT_PIN_PATTERN).optional().catch(undefined),
// A malformed hand edit must degrade to false without discarding providers, accounts,
// or the exact selector map. Live writes remain strict.
codexAccountPickerEnabled: z.boolean().optional().catch(false),
resetCreditAutoRedeem: z.object({
enabled: z.boolean().optional(),
leadTimeMinutes: z.number().int().min(1).max(60).optional(),
}).optional().catch(undefined),
// Same degrade-to-off rule as the flags above: a hand-edited typo in an opt-in pool
// feature must never cost the operator their providers.
pool: z.object({
kernel: z.boolean().optional(),
cacheAffinity: z.boolean().optional(),
// The catch belongs on the list, not on `pool`. Left to the outer catch below, one
// malformed group failed this nested object and dropped the whole `pool` -- taking
// `kernel` and `cacheAffinity` with it, which is a live routing change the operator
// never made. Scoped here, a malformed or ambiguous group costs only the declared
// grouping: loadConfig warns, and the write path rejects it outright.
credentialGroups: credentialGroupsSchema.optional().catch(undefined),
}).optional().catch(undefined),
// Model ids excluded from the Grok Build managed block (dashboard switches).
grokExcludedModels: z.array(z.string()).optional(),
// Providers the dashboard's suggested combos leave out (Combos page).
comboSuggestionExcludedProviders: z.array(z.string().trim().min(1).max(256)).max(256)
.transform((names) => [...new Set(names)]).optional().catch(undefined),
// Invalid values degrade to undefined ("auto") instead of failing the whole
// parse: a hand-edited typo must never trip the backup-and-defaults repair
// path below and wipe providers/pool accounts. Warning emitted in loadConfig.
streamMode: z.enum(["auto", "legacy-tee", "eager-relay"]).optional().catch(undefined),
blockedModelRedirects: blockedModelRedirectsSchema.optional().catch(undefined),
// Degrade malformed hand edits locally; candidate writes reject them before parsing.
// An invalid native preference retains the legacy route instead of enabling native by default.
anthropicAccountPool: anthropicAccountPoolSchema,
// Same degrade-don't-reject rationale as the fields above: a hand-edited
// non-string must not trip the backup-and-defaults repair path. Unset then
// takes the canonical sideband path (src/server/live.ts normalizeSidebandRoot).
experimentalRealtimeWsBaseUrl: z.string().optional().catch(undefined),
// Salvage element by element, and never fail the parse. Two spellings were
// measured on this zod version and both lose data:
// `z.array(entry).catch(undefined)` -> one bad entry discards EVERY key
// `z.array(z.unknown())` -> a non-array value still raises
// invalid_type, reaching the
// backup-and-defaults repair path
// Starting from `unknown` is what makes both survivable. A key the user still
// has deployed must not be collateral damage for one bad neighbour, and on a
// remote bind an emptied array is worse than cosmetic: assertServerAuthConfig
// refuses to start without a data credential.
apiKeys: z.unknown().optional().transform(value => {
if (value === undefined) return undefined;
if (!Array.isArray(value)) return undefined;
return value
.filter(row => apiKeyEntrySchema.safeParse(row).success)
.map(row => apiKeyEntrySchema.parse(row) as OcxApiKeyEntry);
}),
}).passthrough().superRefine((config, ctx) => {
// Helper `anthropicInstance` is deliberately not refined here. A document-level issue would send
// loadConfig through salvage (which refuses pathless issues) to the backup-and-defaults path, so
// one hand-edited helper preference would hide every provider. Writes reject it explicitly in
// validateConfigCandidate, diagnostics report it from the raw file, and loadConfig drops only the
// offending key (sanitizeAnthropicSidecarInstanceForLoad).
const claudeCode = (config as { claudeCode?: unknown }).claudeCode;
if (claudeCode !== undefined && (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode))) {
ctx.addIssue({ code: "custom", path: ["claudeCode"], message: "claudeCode must be an object" });
} else if (claudeCode) {
const claude = claudeCode as { desktopProfile?: unknown; desktopModelVisibility?: unknown; desktopMode?: unknown; intercept?: unknown; appendOnlyToolLoadingModels?: unknown; chatToolDispatchModels?: unknown };
if (claude.appendOnlyToolLoadingModels !== undefined && !isToolLoadingModelSelectors(claude.appendOnlyToolLoadingModels)) {
ctx.addIssue({ code: "custom", path: ["claudeCode", "appendOnlyToolLoadingModels"], message: "appendOnlyToolLoadingModels must be up to 128 provider/model selectors (max 512 characters each), optionally ending in a single wildcard" });
}
if (claude.chatToolDispatchModels !== undefined && !isToolLoadingModelSelectors(claude.chatToolDispatchModels)) {
ctx.addIssue({ code: "custom", path: ["claudeCode", "chatToolDispatchModels"], message: "chatToolDispatchModels must be up to 128 provider/model selectors (max 512 characters each), optionally ending in a single wildcard" });
}
if (claude.desktopMode !== undefined && claude.desktopMode !== "first-party" && claude.desktopMode !== "gateway") {
ctx.addIssue({ code: "custom", path: ["claudeCode", "desktopMode"], message: "desktopMode must be \"first-party\" or \"gateway\"" });
}
if (claude.intercept !== undefined) {
const intercept = claude.intercept;
if (!intercept || typeof intercept !== "object" || Array.isArray(intercept)) {
ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept"], message: "intercept must be an object" });
} else {
const { enabled, port, picker, modelMap } = intercept as { enabled?: unknown; port?: unknown; picker?: unknown; modelMap?: unknown };
if (enabled !== undefined && typeof enabled !== "boolean") {
ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "enabled"], message: "intercept.enabled must be a boolean" });
}
if (picker !== undefined && typeof picker !== "boolean") {
ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "picker"], message: "intercept.picker must be a boolean" });
}
if (port !== undefined && (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)) {
ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "port"], message: "intercept.port must be an integer between 1 and 65535" });
}
if (modelMap !== undefined) {
if (!modelMap || typeof modelMap !== "object" || Array.isArray(modelMap)) {
ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "modelMap"], message: "intercept.modelMap must be an object of picker id to route" });
} else {
for (const [id, route] of Object.entries(modelMap as Record<string, unknown>)) {
if (!isInterceptBindingId(id)) {
ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "modelMap", id], message: "intercept.modelMap keys must be claude- picker model ids" });
} else if (!isInterceptBindingRoute(route)) {
ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "modelMap", id], message: "intercept.modelMap values must be non-empty routes without whitespace" });
}
}
}
}
}
}
if (claude.desktopProfile !== undefined) {
try {
parseDesktopProfile(claude.desktopProfile);
} catch (error) {
ctx.addIssue({
code: "custom",
path: ["claudeCode", "desktopProfile"],
message: error instanceof Error ? error.message : String(error),
});
}
}
if (claude.desktopModelVisibility !== undefined) {
try {
parseDesktopModelVisibility(claude.desktopModelVisibility);
} catch (error) {
ctx.addIssue({
code: "custom",
path: ["claudeCode", "desktopModelVisibility"],
message: error instanceof Error ? error.message : String(error),
});
}
}
}
const accountNamespaces = config.codexAccountNamespaces;
if (accountNamespaces) {
const configuredAccountIds = configuredCodexPoolAccountIds(config.codexAccounts);
const configuredProviderNamespaces = new Set([
COMBO_NAMESPACE,
OPENAI_CODEX_PROVIDER_ID,
POLICY_NAMESPACE,
...Object.keys(config.providers),
].map(codexProviderNamespaceKey));
const namespaceTargets = new Set(
Object.values(accountNamespaces)
.filter(accountId => accountId !== MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET),
);
for (const namespace of Object.keys(accountNamespaces)) {
if (configuredProviderNamespaces.has(codexProviderNamespaceKey(namespace))) {
ctx.addIssue({
code: "custom",
path: ["codexAccountNamespaces", namespace],
message: "account selectors must not collide with configured provider, combo, or routing policy namespaces",
});
}
if (configuredAccountIds.has(namespace) || namespaceTargets.has(namespace)) {
ctx.addIssue({
code: "custom",
path: ["codexAccountNamespaces", namespace],
message: CODEX_ACCOUNT_NAMESPACE_ACCOUNT_ID_COLLISION_ERROR,
});
}
}
}
for (const name of Object.keys(config.providers)) {
if (!isValidProviderName(name)) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name)],
message: "provider names must use letters, numbers, dot, underscore, or hyphen and cannot be reserved JavaScript object keys or routing namespaces (policy)",
});
}
const provider = config.providers[name];
if (hasFastWireCapabilityConflict(provider)) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "fastWire"],
message: "fastWire=null conflicts with supportsServiceTier=true",
});
}
const openRouterRoutingError = openRouterRoutingConfigError(provider);
if (openRouterRoutingError) {
ctx.addIssue({
code: "custom",
path: [
"providers",
redactSecretString(name),
openRouterRoutingError.startsWith("modelOpenRouterRouting")
? "modelOpenRouterRouting"
: "openRouterRouting",
],
message: openRouterRoutingError,
});
}
const vercelRoutingError = vercelGatewayRoutingConfigError(provider);
if (vercelRoutingError) {
ctx.addIssue({
code: "custom",
path: [
"providers",
redactSecretString(name),
vercelRoutingError.startsWith("modelVercelGatewayRouting")
? "modelVercelGatewayRouting"
: "vercelGatewayRouting",
],
message: vercelRoutingError,
});
}
if (Object.hasOwn(provider, "virtualModels")) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "virtualModels"],
message: "virtualModels is registry-only and must not be persisted",
});
}
const baseUrlError = providerBaseUrlConfigError(provider.baseUrl);
if (baseUrlError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "baseUrl"],
message: baseUrlError,
});
} else {
const destinationError = providerDestinationConfigError(name, provider);
if (destinationError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "baseUrl"],
message: destinationError,
});
}
}
for (const field of ["responsesPath", "chatCompletionsPath"] as const) {
const sendPathError = providerRelativeSendPathConfigError(field, provider[field]);
if (sendPathError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), field],
message: sendPathError,
});
}
}
const tlsProfileError = providerTlsProfileConfigError(name, provider);
if (tlsProfileError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "tlsProfile"],
message: tlsProfileError,
});
}
const headersError = providerHeadersConfigError((provider as { headers?: unknown }).headers);
if (headersError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "headers"],
message: headersError,
});
}
const forwardClientHeadersError = providerForwardClientHeadersConfigError(
(provider as { forwardClientHeaders?: unknown }).forwardClientHeaders,
);
if (forwardClientHeadersError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "forwardClientHeaders"],
message: forwardClientHeadersError,
});
}
const modelCostsError = providerModelCostsConfigError((provider as { modelCosts?: unknown }).modelCosts);
if (modelCostsError) {
ctx.addIssue({
code: "custom",
// The provider key is caller-controlled and can be token-shaped; redact it
// before schemaDiagnosticsError serializes the path (ocx config validate/import).
path: ["providers", redactSecretString(name), "modelCosts"],
message: modelCostsError,
});
}
const modelDisplayNamesError = modelDisplayNamesConfigError(
(provider as { modelDisplayNames?: unknown }).modelDisplayNames,
);
if (modelDisplayNamesError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelDisplayNames"],
message: modelDisplayNamesError,
});
}
const apiKeyTransportError = apiKeyTransportConfigError(provider as OcxProviderConfig);
if (apiKeyTransportError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "apiKeyTransport"],
message: apiKeyTransportError,
});
}
const modelAdaptersError = modelAdapterRecordConfigError(
(provider as { modelAdapters?: unknown }).modelAdapters,
"modelAdapters",
name,
provider,
);
if (modelAdaptersError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelAdapters"],
message: modelAdaptersError,
});
}
const credentialPinError = credentialPinnedProviderConfigError(name, provider);
if (credentialPinError) {
ctx.addIssue({ code: "custom", path: ["providers", redactSecretString(name)], message: credentialPinError });
}
const preferHostedToolsError = modelPreferHostedToolsConfigError(
(provider as { modelPreferHostedTools?: unknown }).modelPreferHostedTools,
"modelPreferHostedTools",
name,
provider,
);
if (preferHostedToolsError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelPreferHostedTools"],
message: preferHostedToolsError,
});
}
const maxInputError = positiveIntegerRecordConfigError(
(provider as { modelMaxInputTokens?: unknown }).modelMaxInputTokens,
"modelMaxInputTokens",
);
if (maxInputError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelMaxInputTokens"],
message: maxInputError,
});
}
const autoCompactError = modelAutoCompactTokenLimitsConfigError(
(provider as { modelAutoCompactTokenLimits?: unknown }).modelAutoCompactTokenLimits,
{ requireNativeIds: name === OPENAI_CODEX_PROVIDER_ID },
);
if (autoCompactError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelAutoCompactTokenLimits"],
message: autoCompactError,
});
}
const reasoningSummariesError = booleanRecordConfigError(
(provider as { modelSupportsReasoningSummaries?: unknown }).modelSupportsReasoningSummaries,
"modelSupportsReasoningSummaries",
);
if (reasoningSummariesError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelSupportsReasoningSummaries"],
message: reasoningSummariesError,
});
}
const suppressSyntheticMaxError = booleanRecordConfigError(
(provider as { modelSuppressSyntheticMax?: unknown }).modelSuppressSyntheticMax,
"modelSuppressSyntheticMax",
);
if (suppressSyntheticMaxError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelSuppressSyntheticMax"],
message: suppressSyntheticMaxError,
});
}
const verbositySupportError = booleanRecordConfigError(
(provider as { modelSupportsVerbosity?: unknown }).modelSupportsVerbosity,
"modelSupportsVerbosity",
);
if (verbositySupportError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelSupportsVerbosity"],
message: verbositySupportError,
});
}
const serviceTierModelsError = booleanRecordConfigError(
(provider as { modelSupportsServiceTier?: unknown }).modelSupportsServiceTier,
"modelSupportsServiceTier",
);
if (serviceTierModelsError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelSupportsServiceTier"],
message: serviceTierModelsError,
});
}
const reasoningSummaryDeliveryError = reasoningSummaryDeliveryRecordConfigError(
(provider as { modelReasoningSummaryDelivery?: unknown }).modelReasoningSummaryDelivery,
(provider as { modelSupportsReasoningSummaries?: unknown }).modelSupportsReasoningSummaries,
);
if (reasoningSummaryDeliveryError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelReasoningSummaryDelivery"],
message: reasoningSummaryDeliveryError,
});
}
const thinkingDisplayError = thinkingDisplayConfigError(
(provider as { thinkingDisplay?: unknown }).thinkingDisplay,
);
if (thinkingDisplayError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "thinkingDisplay"],
message: thinkingDisplayError,
});
}
const modelThinkingDisplayError = modelThinkingDisplayConfigError(
(provider as { modelThinkingDisplay?: unknown }).modelThinkingDisplay,
);
if (modelThinkingDisplayError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelThinkingDisplay"],
message: modelThinkingDisplayError,
});
}
const minMaxOutputError = positiveIntegerConfigError(
(provider as { minMaxOutputTokens?: unknown }).minMaxOutputTokens,
"minMaxOutputTokens",
);
if (minMaxOutputError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "minMaxOutputTokens"],
message: minMaxOutputError,
});
}
const creditPrice = (provider as { creditPriceUsd?: unknown }).creditPriceUsd;
if (creditPrice !== undefined && !isValidCreditPriceUsd(creditPrice)) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "creditPriceUsd"],
message: `creditPriceUsd must be a finite number between 0 and ${MAX_CREDIT_PRICE_USD}`,
});
}
const defaultMaxOutputError = positiveIntegerConfigError(
(provider as { defaultMaxOutputTokens?: unknown }).defaultMaxOutputTokens,
"defaultMaxOutputTokens",
);
if (defaultMaxOutputError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "defaultMaxOutputTokens"],
message: defaultMaxOutputError,
});
}
const maxOutputError = positiveIntegerRecordConfigError(
(provider as { modelMaxOutputTokens?: unknown }).modelMaxOutputTokens,
"modelMaxOutputTokens",
);
if (maxOutputError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "modelMaxOutputTokens"],
message: maxOutputError,
});
}
const structuredOutputOptOutError = nonBlankStringArrayConfigError(
(provider as { noStructuredOutputModels?: unknown }).noStructuredOutputModels,
"noStructuredOutputModels",
);
if (structuredOutputOptOutError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "noStructuredOutputModels"],
message: structuredOutputOptOutError,
});
}
const jsonSchemaOptOutError = nonBlankStringArrayConfigError(
(provider as { noJsonSchemaModels?: unknown }).noJsonSchemaModels,
"noJsonSchemaModels",
);
if (jsonSchemaOptOutError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "noJsonSchemaModels"],
message: jsonSchemaOptOutError,
});
}
const retainModelsError = nonBlankStringArrayConfigError(
(provider as { retainModels?: unknown }).retainModels,
"retainModels",
);
if (retainModelsError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "retainModels"],
message: retainModelsError,
});
}
const toolReasoningOptOutError = nonBlankStringArrayConfigError(
(provider as { omitReasoningEffortWithToolsModels?: unknown }).omitReasoningEffortWithToolsModels,
"omitReasoningEffortWithToolsModels",
);
if (toolReasoningOptOutError) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "omitReasoningEffortWithToolsModels"],
message: toolReasoningOptOutError,
});
}
if (Object.hasOwn(provider, "codexAccountMode") && provider.codexAccountMode !== undefined) {
// Persisted account mode is valid ONLY on the canonical built-in `openai` forward provider.
// Old openai-multi rows stay parseable (they never carry a mode) so startup can migrate them.
const canonicalOpenAiShape = name === "openai"
&& provider.adapter === "openai-responses"
&& (provider as { authMode?: unknown }).authMode === "forward"
&& typeof provider.baseUrl === "string"
&& provider.baseUrl.replace(/\/+$/, "") === "https://chatgpt.com/backend-api/codex";
if (!canonicalOpenAiShape) {
ctx.addIssue({
code: "custom",
path: ["providers", redactSecretString(name), "codexAccountMode"],
message: "codexAccountMode is valid only on the canonical built-in openai provider",
});
}
}
}
if (!hasOwnProvider(config.providers, config.defaultProvider)) {
ctx.addIssue({
code: "custom",
path: ["defaultProvider"],
message: "defaultProvider must exist in providers",
});
}
const combos = (config as { combos?: unknown }).combos;
if (combos !== undefined) {
if (!combos || typeof combos !== "object" || Array.isArray(combos)) {
ctx.addIssue({ code: "custom", path: ["combos"], message: "combos must be an object" });
} else {
for (const [id, raw] of Object.entries(combos as Record<string, unknown>)) {
const alias = raw && typeof raw === "object" && !Array.isArray(raw)
? (raw as { alias?: unknown }).alias
: undefined;
if (typeof alias === "string" && codexAccountNamespaceForModel(accountNamespaces, alias.trim())) {
ctx.addIssue({
code: "custom",
path: ["combos", id, "alias"],
message: CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR,
});
}
// Pass the full map so cross-combo rules (alias uniqueness) apply at load time
// too, not just via the management API; each combo is excluded from its own check.
for (const issue of comboConfigIssues(id, raw, config.providers, {
combos: combos as Record<string, import("../../types").OcxComboConfig>,
excludeComboId: id,
normalizeDecisionModel: model => lexicalDecisionModelBase(model, config.cursorEffortRows === true),
})) {
ctx.addIssue({
code: "custom",
path: ["combos", id, ...issue.path],
message: issue.message,
});
}
}
}
}
for (const issue of agyAcpConfigIssues(config as Parameters<typeof agyAcpConfigIssues>[0])) {
// Preserve non-provider identifiers for load-time salvage; diagnostics mask them at serialization.
const path = issue.path[0] === "providers"
? issue.path.map(segment => typeof segment === "string" ? redactSecretString(segment) : segment)
: issue.path;
ctx.addIssue({ code: "custom", path, message: issue.message });
}
const routingProfiles = (config as { routingProfiles?: unknown }).routingProfiles;
if (routingProfiles !== undefined) {
if (!routingProfiles || typeof routingProfiles !== "object" || Array.isArray(routingProfiles)) {
ctx.addIssue({ code: "custom", path: ["routingProfiles"], message: "routingProfiles must be an object" });
} else {
for (const [id, raw] of Object.entries(routingProfiles as Record<string, unknown>)) {
for (const issue of routingProfileIssues(id, raw, {
providers: config.providers,
combos: combos as Record<string, import("../../types").OcxComboConfig> | undefined,
routingProfiles: routingProfiles as Record<string, import("../../types").OcxRoutingProfileConfig>,
codexAccountNamespaces: accountNamespaces,
}, { excludeProfileId: id })) {
ctx.addIssue({
code: "custom",
path: ["routingProfiles", id, ...issue.path],
message: issue.message,
});
}
}
}
}
});