@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,205 lines • 65.6 kB
text/typescript
import { isSubagentModelEntry, rawSubagentModelForce } from "./subagent-models";
import { chmodSync, existsSync } from "node:fs";
import { join } from "node:path";
import { compactionRecoveryConfigError } from "./schema/compaction-recovery";
import { nativeReasoningRetentionConfigError } from "./schema/native-reasoning-retention";
import { workflowBudgetConfigError } from "./schema/workflow-budget";
import { routedCatalogDefaultsConfigError } from "./schema/routed-catalog-defaults";
import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
import { mainAccountHardLockFallbackError } from "./schema/main-account-hard-lock-fallback";
import { fallbackPolicyError } from "./schema/fallback-policy";
import { subscriptionReserveConfigError } from "./schema/subscription-reserve";
import { anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
import { agyAcpProviderFieldIssues, agyAcpUnattendedTargetIssues } from "./schema/agy-acp-references";
import {
modelPinnedEffortsConfigError,
pinnedReasoningEffortConfigError,
autoReviewOverrideConfigError,
autoReviewModelOverridesConfigError,
autoReviewModelTargetConfigError,
modelCapabilitiesConfigError,
providerInputModalitiesConfigError,
sanitizeModelCapabilitiesForLoad,
modelDisplayNamesConfigError,
} from "./provider-validation";
import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "../codex/upstream-host-health";
import { hardenSecretPath } from "../lib/windows-secret-acl";
import { isPassiveRead } from "../lib/passive-read";
import { redactSecretString } from "../lib/redact";
import { isValidProviderName } from "./provider-name";
import { MODEL_ALIAS_PATTERN } from "../providers/default-aliases";
import { aliasTemplateError } from "../providers/alias-template";
import { MODEL_DISCOVERY_MAX_MODELS } from "../providers/model-discovery-limits";
import { getProviderRegistryEntry, providerMatchesRegistryTransport, registryModelServiceTierCapabilityApplies } from "../providers/registry";
import { providerFastSwitchOff } from "../providers/fast-opt-in";
import { isCodexReasoningEffort } from "../reasoning-effort";
import { refreshConfigDerivedRegistries } from "./derived-registries";
import { type OcxClaudeCodeConfig, type OcxConfig } from "../types";
import {
agentTaskRecoverySchema,
asideProfileSyncSchema,
catalogAutoRefreshSchema,
clientConnectionSchema,
isUsableApiKeySecret,
managementIngressSchema,
codexAuthMethodSchema,
codexPoolSchema,
codexAccountAutoSwitchThresholdsSchema,
providerModelCostsConfigError,
credentialGroupsSchema,
hubConfigSchema,
quotaResetNotifySchema,
remoteGuiConfigSchema,
retryOn429PolicySchema,
retryOnResetPolicySchema,
transientRetryOn5xxPolicySchema,
runtimeRoleSchema,
spendSchema,
telemetryConfigSchema,
chatgptDesktopConfigIssue,
isValidCreditPriceUsd,
} from "./schema/leaf-validators";
import { hasWarnedInheritedFastWireConflict, markWarnedInheritedFastWireConflict } from "./warn-memo";
export function hardenExistingSecret(path: string): void {
if (existsSync(path) && !isPassiveRead()) {
if (process.platform === "win32") {
// Preserve the ACL helper's metadata observation across reads. Windows chmod does
// not establish a private DACL and can invalidate that observation before every load.
hardenSecretPath(path, { required: false });
} else {
try { chmodSync(path, 0o600); } catch { /* best-effort */ }
}
}
}
/** Load only: discard invalid optional pins without rewriting the file or losing providers. */
export function sanitizeReasoningPinsForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
const root = parsed as Record<string, unknown>;
let degraded = false;
const sanitizeMap = (owner: Record<string, unknown>, field: string) => {
const value = owner[field];
if (value === undefined) return;
if (!value || typeof value !== "object" || Array.isArray(value)
|| ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
delete owner[field];
degraded = true;
return;
}
const counts = new Map<string, number>();
for (const key of Object.keys(value)) counts.set(key.trim(), (counts.get(key.trim()) ?? 0) + 1);
const valid: Record<string, string> = Object.create(null);
for (const [key, effort] of Object.entries(value)) {
if (counts.get(key.trim()) !== 1 || modelPinnedEffortsConfigError({ [key]: effort }) !== null) {
degraded = true;
continue;
}
valid[key.trim()] = effort as string;
}
if (Object.keys(valid).length) owner[field] = valid;
else delete owner[field];
};
sanitizeMap(root, "modelPinnedEfforts");
if (root.providers && typeof root.providers === "object" && !Array.isArray(root.providers)) {
for (const value of Object.values(root.providers)) {
if (!value || typeof value !== "object" || Array.isArray(value)) continue;
const provider = value as Record<string, unknown>;
if (pinnedReasoningEffortConfigError(provider.pinnedReasoningEffort)) {
delete provider.pinnedReasoningEffort;
degraded = true;
}
sanitizeMap(provider, "modelPinnedReasoningEfforts");
}
}
// Never include a provider/model name or value: malformed pins can contain secrets.
if (degraded) warn("config.json contains invalid optional reasoning pins — ignoring invalid fields or entries");
}
/**
* The schema's `.catch(undefined)` silently degrades an invalid persisted
* `streamMode` to "auto"; surface that once so a hand-edited typo (e.g.
* "legacy_tee") is discoverable instead of silently changing stream shape.
*/
export function warnDegradedStreamMode(rawParsed: unknown, validated: OcxConfig): void {
if (!rawParsed || typeof rawParsed !== "object") return;
const raw = (rawParsed as Record<string, unknown>).streamMode;
if (raw !== undefined && validated.streamMode === undefined) {
console.warn(`⚠️ config.json streamMode ${JSON.stringify(raw)} is invalid (expected "auto", "legacy-tee", or "eager-relay") — falling back to "auto"`);
}
}
export function warnDegradedCompactionRouting(rawParsed: unknown, validated: OcxConfig): void {
if (!rawParsed || typeof rawParsed !== "object") return;
const raw = (rawParsed as Record<string, unknown>).compactionRouting;
if (raw !== undefined && validated.compactionRouting === undefined) {
console.warn("⚠️ config.json compactionRouting is invalid (expected { model, reasoningEffort?, triggers? } with a nonblank model, a declared effort, and triggers drawn without repetition from \"manual\" and \"auto\") — compaction keeps the conversation model");
}
}
/**
* Top-level opt-in blocks whose hand-edited form degrades to "off" instead of failing the whole
* schema. Grouped behind one entry point because `src/config.ts` sits at its file-size cap, and
* the ratchet only ever moves down: a per-block call there costs a line the file does not have.
*/
export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxConfig): void {
const codexAuthWarning = malformedCodexAuthMethodWarning(rawParsed);
if (codexAuthWarning) console.warn(`⚠️ config.json ${codexAuthWarning}`);
if (nativeReasoningRetentionConfigError(rawParsed)) console.warn("⚠️ invalid nativeReasoningRetention disabled; model and account switch allowances remain off");
if (workflowBudgetConfigError(rawParsed)) console.warn("⚠️ invalid workflowBudget ignored; the built-in workflow ceilings stay in force");
if (routedCatalogDefaultsConfigError(rawParsed)) console.warn("⚠️ invalid routedCatalogDefaults ignored; routed catalog rows keep their derived values");
const retentionWarning = degradedReasoningRetentionWarning(rawParsed, validated);
if (retentionWarning) console.warn(retentionWarning);
if (compactionRecoveryConfigError(rawParsed)) console.warn("⚠️ invalid compactionRecovery disabled; the original compaction failure is preserved");
if (desktopCompatibilityConfigError(rawParsed)) console.warn("Invalid desktopCompatibility startup preference ignored; no desktop compatibility service will start automatically.");
if (blockedModelRedirectsError(rawParsed)) console.warn("⚠️ invalid blockedModelRedirects ignored; provider routing remains available");
if (mainAccountHardLockFallbackError(rawParsed)) console.warn("⚠️ invalid codexMainAccountHardLockFallback ignored; the main-account hard lock still refuses while blocked");
if (fallbackPolicyError(rawParsed)) console.warn("⚠️ invalid fallback leaves ignored; those scopes keep today's fallback behavior");
if (subscriptionReserveConfigError(rawParsed)) console.warn("⚠️ invalid subscriptionReserve disabled; Claude subscription routing remains available");
const chatgptDesktop = chatgptDesktopConfigIssue(rawParsed);
if (chatgptDesktop) console.warn(`⚠️ config.json ${chatgptDesktop} — the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);
warnDegradedStreamMode(rawParsed, validated);
warnDegradedCompactionRouting(rawParsed, validated);
warnDegradedMemoryModels(rawParsed, validated);
warnDegradedTelemetry(rawParsed);
// The schema replaces a malformed policy with { allProfiles: false }, which silently turns every Aside profile off (#6757).
const asidePolicy = rawParsed && typeof rawParsed === "object" ? (rawParsed as Record<string, unknown>).asideProfileSync : undefined;
if (asidePolicy !== undefined && !asideProfileSyncSchema.safeParse(asidePolicy).success) {
console.warn("⚠️ config.json asideProfileSync is invalid — Aside profile sync falls back to all profiles off; fix the block or inspect `ocx integration client status --client aside`");
}
}
export function degradedReasoningRetentionWarning(rawParsed: unknown, validated: OcxConfig): string | null {
if (rawConfigRecord(rawParsed)?.reasoningRetention === undefined || validated.reasoningRetention !== undefined) return null;
return "config.json reasoningRetention is invalid — reasoning retention is disabled";
}
/**
* A malformed `memoryModels` phase disables that phase rather than failing the whole schema, so
* say so once: silently keeping whatever route the phase already had — which may be the shadow
* intercept rather than Codex's own model — is the outcome a typo must not produce quietly.
*/
export function warnDegradedMemoryModels(rawParsed: unknown, validated: OcxConfig): void {
if (!rawParsed || typeof rawParsed !== "object") return;
const raw = (rawParsed as Record<string, unknown>).memoryModels;
if (raw === undefined) return;
if (validated.memoryModels === undefined || raw === null || typeof raw !== "object" || Array.isArray(raw)) {
console.warn("\u26a0\ufe0f config.json memoryModels is invalid (expected { extract?: { model, reasoningEffort? }, consolidation?: { model, reasoningEffort? } } with a nonblank model and a declared effort per phase) \u2014 the memory pipeline keeps its existing route, which may include shadow-call interception");
return;
}
// A misspelled phase key is stripped by the permissive load schema, so without this warning it
// disappears silently and the next settings save persists the sanitized map without it.
for (const key of Object.keys(raw as Record<string, unknown>)) {
if (key === "extract" || key === "consolidation") continue;
// Redact and JSON-escape the key name: a malformed hand-edit can place a secret in a property
// name, and a control character in one must not be able to forge a log line.
console.warn("\u26a0\ufe0f config.json memoryModels." + JSON.stringify(redactSecretString(key)) + " is not a recognized phase \u2014 ignoring it");
}
for (const phase of ["extract", "consolidation"] as const) {
if ((raw as Record<string, unknown>)[phase] !== undefined && validated.memoryModels[phase] === undefined) {
console.warn("\u26a0\ufe0f config.json memoryModels." + phase + " is invalid (expected { model, reasoningEffort? } with a nonblank model) \u2014 that phase keeps its existing route, which may include shadow-call interception");
}
}
}
/** Repair ACP-specific provider fields and unattended selectors on disk reads. */
export function sanitizeAgyAcpForLoad(
parsed: unknown,
warn: (message: string) => void = message => console.warn(`⚠️ config.json ${message}`),
): void {
const root = rawConfigRecord(parsed);
if (!root) return;
const report = (issue: ReturnType<typeof agyAcpProviderFieldIssues>[number], repair: string): void => {
const path = issue.path.map(segment => typeof segment === "string"
? redactSecretString(segment).replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g,
ch => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"))
: segment).join(".");
warn(path + ": " + issue.message + " " + repair);
};
// Fallback issues are indexed into their original arrays. Remove later entries first.
for (const issue of agyAcpUnattendedTargetIssues(root).reverse()) {
const [section, field, index] = issue.path;
if (section === "memoryModels" && typeof field === "string") {
const memory = rawConfigRecord(root.memoryModels);
if (memory) delete memory[field];
} else if (section === "injectionModel") {
root.syncCodexSubagentDefaults = false;
} else if (section === "compactionRouting") {
const compaction = rawConfigRecord(root.compactionRouting);
if (compaction && Array.isArray(compaction.triggers)) {
const remaining = compaction.triggers.filter(trigger => trigger !== "auto");
if (remaining.length) compaction.triggers = remaining;
else delete root.compactionRouting;
}
} else if (section === "shadowCallIntercept") {
const shadow = rawConfigRecord(root.shadowCallIntercept);
if (shadow) shadow.enabled = false;
} else if (section === "subagentModelFallback" && Array.isArray(root.subagentModelFallback) && typeof field === "number") {
root.subagentModelFallback.splice(field, 1);
} else if (section === "subagentModelFallbackByModel" && typeof field === "string" && typeof index === "number") {
const byModel = rawConfigRecord(root.subagentModelFallbackByModel);
const fallback = byModel?.[field];
if (byModel && Array.isArray(fallback)) {
fallback.splice(index, 1);
if (fallback.length === 0) delete byModel[field];
}
}
const repair = section === "injectionModel" ? "Disabling managed subagent default sync on load."
: section === "compactionRouting" ? "Ignoring the automatic compaction trigger on load."
: "Ignoring this target on load.";
report(issue, repair);
}
const providers = rawConfigRecord(root.providers);
// Apply indexed removals from the end so earlier model entries retain their indices.
for (const issue of agyAcpProviderFieldIssues(root).reverse()) {
const [, name, field, entry] = issue.path;
if (typeof name !== "string" || typeof field !== "string") continue;
const provider = rawConfigRecord(providers?.[name]);
if (!provider) continue;
const value = provider[field];
if (field === "models" && Array.isArray(value) && typeof entry === "number") value.splice(entry, 1);
else if (field === "modelAliases" && typeof entry === "string") {
const aliases = rawConfigRecord(value);
if (aliases) delete aliases[entry];
} else delete provider[field];
report(issue, "Ignoring this provider setting on load.");
}
}
/**
* Load-time degradation for helper `anthropicInstance` (loadConfig only). A malformed id, or one
* that conflicts with its block's backend or model, drops just that key with a warning, so the
* helper inherits the request's pool and every provider/key survives. Validated writes still
* reject the value and file diagnostics still report it from the raw document.
*
* Each location is checked in isolation, global blocks first, so a Claude override is judged
* against the already-degraded global block it inherits from. An override that owns no
* `anthropicInstance` of its own is left untouched: the conflicting key lives in the global
* block, which is valid on its own, and the inherited value is still a well-formed instance.
*/
export function sanitizeAnthropicSidecarInstanceForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
const asRecord = (value: unknown): Record<string, unknown> | undefined =>
value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
const root = asRecord(parsed);
if (!root) return;
for (const scope of ["global", "claude"] as const) {
const owner = scope === "global" ? root : asRecord(root.claudeCode);
for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
const sidecar = asRecord(owner?.[field]);
if (!sidecar || !Object.hasOwn(sidecar, "anthropicInstance")) continue;
const probe = scope === "global"
? { [field]: sidecar }
: { [field]: root[field], claudeCode: { [field]: sidecar } };
const error = anthropicSidecarConfigError(probe);
if (!error) continue;
delete sidecar.anthropicInstance;
// The message names a static path and reason only; the hand-edited value is never echoed.
warn(`⚠️ config.json ${error} — ignoring that anthropicInstance; the helper inherits the request's Anthropic pool`);
}
}
}
/**
* Load-time degradation for `retryOn429` (loadConfig only): one hand-edited invalid optional
* field (e.g. `attempts: 0` or a string) must not trip the whole provider schema and hide every
* provider/key behind a default config. Invalid fields are dropped with a warning; the management
* write boundary still rejects invalid policies explicitly.
*/
export function sanitizeRetryOn429ForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
if (!parsed || typeof parsed !== "object") return;
const root = parsed as Record<string, unknown>;
const providers = root.providers;
if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
for (const [name, provider] of Object.entries(providers as Record<string, unknown>)) {
// This sanitizer runs BEFORE schema validation, so the provider name is untrusted: redact
// secret-shaped names and JSON-escape control characters before it reaches any warning.
const safeProviderName = JSON.stringify(redactSecretString(name));
if (!provider || typeof provider !== "object" || Array.isArray(provider)) continue;
const p = provider as Record<string, unknown>;
if (p.cacheAffinity !== undefined && !["auto", "session", "turn", "off"].includes(p.cacheAffinity as string)) {
delete p.cacheAffinity;
warn(`⚠️ config.json providers.${safeProviderName}.cacheAffinity is invalid — ignoring the field`);
}
const policy = p.retryOn429;
if (policy === undefined) continue;
if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
delete p.retryOn429;
// Never serialize the value: an accidental `retryOn429: "sk-..."` would leak the secret.
warn(`⚠️ config.json providers.${safeProviderName}.retryOn429 (${typeof policy}) is invalid — ignoring the policy`);
continue;
}
const policyRecord = policy as Record<string, unknown>;
// An explicitly present but invalid master switch must not silently default to ENABLED:
// drop the whole policy so a hand-edit that tried to disable retries stays disabled.
if ("enabled" in policyRecord && typeof policyRecord.enabled !== "boolean") {
delete p.retryOn429;
warn(`⚠️ config.json providers.${safeProviderName}.retryOn429.enabled (${typeof policyRecord.enabled}) is invalid — ignoring the whole policy`);
continue;
}
// Field checks derive from the shared policy schema so the bounds cannot drift
// between the load-time sanitizer, the config schema, and the write boundary.
const policyShape = retryOn429PolicySchema.shape;
const hadPolicyEntries = Object.keys(policyRecord).length > 0;
const cleaned: Record<string, unknown> = {};
for (const [key, fieldSchema] of Object.entries(policyShape)) {
const value = policyRecord[key];
if (value === undefined) continue;
if (fieldSchema.safeParse(value).success) cleaned[key] = value;
// Log only the received type, never the value (provider config can hold secrets).
else warn(`⚠️ config.json providers.${safeProviderName}.retryOn429.${key} (${typeof value}) is invalid — ignoring the field`);
}
const knownKeys = new Set(Object.keys(policyShape));
for (const key of Object.keys(policyRecord)) {
if (!knownKeys.has(key)) {
// Redact the field NAME before logging: a malformed hand-edit can place a secret in a
// property name (`retryOn429: { "sk-...": true }`). Ordinary typos (e.g. `attempt`)
// stay readable, secret-shaped names become [REDACTED]. JSON-escape afterwards so a
// control-character property name (newline/ANSI) can never forge a log line.
warn(`⚠️ config.json providers.${safeProviderName}.retryOn429.${JSON.stringify(redactSecretString(key))} is not a recognized field — ignoring it`);
}
}
if (hadPolicyEntries && Object.keys(cleaned).length === 0) {
// Every supplied field was invalid: drop the whole policy. Persisting `{}` here would
// opt IN to retries with defaults, which is the opposite of what a malformed
// disable-oriented edit (`retryOn429: { enabled: "false" }`, `attempts: 0`) asked for.
delete p.retryOn429;
warn(`⚠️ config.json providers.${safeProviderName}.retryOn429 has no valid fields left — removing the policy (an empty policy would enable retries with defaults)`);
} else {
// Preserve an intentionally empty `retryOn429: {}` (presence = opt-in with defaults).
p.retryOn429 = cleaned;
}
}
}
/**
* Management write-boundary validation for `retryOn429` (fail closed). Unlike the
* lenient load-time sanitizer, invalid values and unknown keys are rejected outright so
* a POST/PATCH cannot persist a policy the proxy would then silently degrade. Reuses the
* shared policy schema. Never echoes values, and secret-shaped unknown field names are
* redacted (a malformed write can place a secret in a property name).
*/
export function retryOn429PolicyConfigError(policy: unknown): string | null {
return strictPolicyConfigError("retryOn429", retryOn429PolicySchema, policy);
}
/**
* Management write-boundary validation for `retryOnReset`, with the same fail-closed contract
* as `retryOn429PolicyConfigError`: the load-time schema degrades a malformed block to
* "absent", so this is the one place a bad value is refused instead of silently dropped.
*/
export function retryOnResetPolicyConfigError(policy: unknown): string | null {
return strictPolicyConfigError("retryOnReset", retryOnResetPolicySchema, policy);
}
/**
* Management write-boundary validation for `transientRetryOn5xx`, with the same fail-closed
* contract as the other retry policies.
*
* The load-time schema does not degrade a malformed block: `transientRetryOn5xxPolicySchema` has
* no `.catch`, so a bad value fails the whole config parse and the loader substitutes the default
* config, taking every provider with it. That makes this check the only place a malformed ladder
* can be refused without losing the file, and PATCH never runs the schema — only POST does,
* through `validateConfigCandidate`.
*/
export function transientRetryOn5xxPolicyConfigError(policy: unknown): string | null {
return strictPolicyConfigError("transientRetryOn5xx", transientRetryOn5xxPolicySchema, policy);
}
/**
* The shared body of both. Written once because the two differ only in the field name they
* report, and a second hand-copied formatter is a second place for the redaction to be
* forgotten.
*/
function strictPolicyConfigError(
field: string,
schema: {
safeParse: (value: unknown) => { success: true } | {
success: false;
error: { issues: Array<{ code: string; message: string; path: PropertyKey[]; keys?: string[] }> };
};
},
policy: unknown,
): string | null {
if (policy === undefined) return null;
const result = schema.safeParse(policy);
if (result.success) return null;
const first = result.error.issues[0];
if (!first) return `${field} is invalid`;
if (first.code === "unrecognized_keys" && first.keys) {
const names = first.keys.map(key => JSON.stringify(redactSecretString(key))).join(", ");
return `${field} has unrecognized field${first.keys.length > 1 ? "s" : ""}: ${names}`;
}
if (first.path.length === 0) return `${field} is invalid (${first.message})`;
return `${field}.${String(first.path[first.path.length - 1])} is invalid (${first.message})`;
}
export function sanitizeCapabilityDeclarationsForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
if (!parsed || typeof parsed !== "object") return;
const providers = (parsed as Record<string, unknown>).providers;
if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
for (const [name, value] of Object.entries(providers)) {
if (!value || typeof value !== "object" || Array.isArray(value)) continue;
const provider = value as Record<string, unknown>;
if (providerInputModalitiesConfigError(provider.inputModalities) !== null) {
warn(`config.json provider ${JSON.stringify(redactSecretString(name))} has malformed inputModalities; restricting input modalities to text`);
provider.inputModalities = ["text"];
}
if (provider.modelCapabilities === undefined) continue;
if (modelCapabilitiesConfigError(provider.modelCapabilities) !== null) {
warn(`config.json provider ${JSON.stringify(redactSecretString(name))} has malformed modelCapabilities; retaining valid axes and restricting malformed input modalities to text`);
const repaired = sanitizeModelCapabilitiesForLoad(provider.modelCapabilities);
if (repaired) provider.modelCapabilities = repaired;
else delete provider.modelCapabilities;
}
}
}
/**
* Load-time degradation for `providers.<name>.modelCosts`, mirroring
* {@link sanitizeRetryOn429ForLoad}. A hand-edited malformed display-price row
* must not fail the whole config parse — that would back up config.json and
* fall back to defaults, dropping otherwise valid providers and the default
* route for a typo in a non-runtime display field. Invalid rows are dropped
* with a warning; strict rejection stays at the management/write boundary
* (providerManagementConfigError).
*/
export function sanitizeModelCostsForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
if (!parsed || typeof parsed !== "object") return;
const root = parsed as Record<string, unknown>;
const providers = root.providers;
if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
for (const [name, provider] of Object.entries(providers as Record<string, unknown>)) {
// Runs before schema validation, so the provider name is untrusted: redact
// secret-shaped names and JSON-escape control characters for the warning.
const safeProviderName = JSON.stringify(redactSecretString(name));
if (!provider || typeof provider !== "object" || Array.isArray(provider)) continue;
const p = provider as Record<string, unknown>;
const costs = p.modelCosts;
if (costs === undefined) continue;
if (!costs || typeof costs !== "object" || Array.isArray(costs)) {
delete p.modelCosts;
warn(`⚠️ config.json providers.${safeProviderName}.modelCosts (${typeof costs}) is invalid — ignoring the overlay`);
continue;
}
const costsRecord = costs as Record<string, unknown>;
const hadEntries = Object.keys(costsRecord).length > 0;
let kept = 0;
for (const [modelId, entry] of Object.entries(costsRecord)) {
// Reuse the shared per-row shape contract so the load-time sanitizer
// cannot drift from the schema and the write boundary.
if (providerModelCostsConfigError({ [modelId]: entry }) === null) {
kept++;
continue;
}
delete costsRecord[modelId];
// Redact the model id: a hand-edit can place a secret in a key name.
warn(`⚠️ config.json providers.${safeProviderName}.modelCosts.${JSON.stringify(redactSecretString(modelId))} is invalid — ignoring the row`);
}
if (hadEntries && kept === 0) {
delete p.modelCosts;
warn(`⚠️ config.json providers.${safeProviderName}.modelCosts has no valid rows left — removing the overlay`);
}
}
}
/**
* Load-time degradation for `providers.<name>.creditPriceUsd`, mirroring
* {@link sanitizeModelCostsForLoad}: an invalid hand-edited price is dropped with a warning
* instead of failing the parse and falling back to defaults. The schema still rejects it on writes.
*/
export function sanitizeCreditPriceForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
if (!parsed || typeof parsed !== "object") return;
const providers = (parsed as Record<string, unknown>).providers;
if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
for (const provider of Object.values(providers as Record<string, unknown>)) {
if (!provider || typeof provider !== "object" || Array.isArray(provider)) continue;
const p = provider as Record<string, unknown>;
if (p.creditPriceUsd === undefined || isValidCreditPriceUsd(p.creditPriceUsd)) continue;
delete p.creditPriceUsd;
warn("⚠️ config.json provider has an invalid creditPriceUsd — ignoring the credit price");
}
}
/**
* Load-time degradation for provider-scoped auto-review selectors. A malformed
* hand edit must not fail the whole config parse; the management boundary stays
* strict and rejects the same shapes before they can be written.
*/
export function sanitizeAutoReviewForLoad(parsed: unknown, warn: (message: string) => void = console.warn): void {
if (!parsed || typeof parsed !== "object") return;
const root = parsed as Record<string, unknown>;
if (root.autoReviewOverride !== undefined
&& autoReviewOverrideConfigError(root.autoReviewOverride) !== null) {
warn("⚠️ config.json autoReviewOverride is invalid — ignoring the override");
delete root.autoReviewOverride;
}
const providers = root.providers;
if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
for (const [name, providerValue] of Object.entries(providers as Record<string, unknown>)) {
if (!providerValue || typeof providerValue !== "object" || Array.isArray(providerValue)) continue;
const provider = providerValue as Record<string, unknown>;
const safeProviderName = JSON.stringify(redactSecretString(name));
if (name === "openai") {
delete provider.autoReviewModel;
delete provider.autoReviewModelOverrides;
continue;
}
if (provider.autoReviewModel !== undefined
&& autoReviewModelTargetConfigError(provider.autoReviewModel, "autoReviewModel", true) !== null) {
warn(`⚠️ config.json providers.${safeProviderName}.autoReviewModel is invalid — ignoring the selector`);
delete provider.autoReviewModel;
}
if (provider.autoReviewModelOverrides !== undefined) {
const overridesError = autoReviewModelOverridesConfigError(
provider.autoReviewModelOverrides,
"autoReviewModelOverrides",
true,
);
if (overridesError) {
warn(`⚠️ config.json providers.${safeProviderName}.autoReviewModelOverrides is invalid — ignoring the map`);
delete provider.autoReviewModelOverrides;
}
}
}
}
/**
* Companion to {@link warnDegradedStreamMode} for a blank persisted `hostname`. The bind
* falls back to loopback, which is the safe direction but not what the file asked for —
* say so once instead of silently ignoring the field.
*/
export function warnDegradedHostname(rawParsed: unknown, validated: OcxConfig): void {
if (!rawParsed || typeof rawParsed !== "object") return;
const raw = (rawParsed as Record<string, unknown>).hostname;
if (raw !== undefined && validated.hostname === undefined) {
console.warn(`⚠️ config.json hostname ${JSON.stringify(raw)} is not a usable bind address — falling back to 127.0.0.1`);
}
}
export function degradedListenerWarnings(rawParsed: unknown, validated: OcxConfig): string[] {
const raw = rawConfigRecord(rawParsed);
if (!raw) return [];
const warnings: string[] = [];
if (raw.unauthenticatedLoopbackListener !== undefined && validated.unauthenticatedLoopbackListener === undefined) {
warnings.push("unauthenticatedLoopbackListener ignored: invalid listener configuration; repair config.json before enabling the listener");
}
const hub = rawConfigRecord(raw.hub);
if (hub?.managementIngress !== undefined && !managementIngressSchema.safeParse(hub.managementIngress).success) {
warnings.push("hub.managementIngress ignored: invalid management listener configuration; repair config.json before enabling the listener");
}
return warnings;
}
export function warnDegradedListeners(rawParsed: unknown, validated: OcxConfig): void {
for (const warning of degradedListenerWarnings(rawParsed, validated)) {
console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
}
/**
* Companion to {@link warnDegradedStreamMode} for a malformed selection-order map.
* Priority is a preference, so the schema drops the whole map rather than failing
* the parse — say so once, otherwise the pool silently reverts to flat ordering.
*/
export function degradedCodexAccountPriorityWarnings(rawParsed: unknown, validated: OcxConfig): string[] {
const record = rawConfigRecord(rawParsed);
const warnings: string[] = [];
// The pin degrades silently otherwise, which reads as the manual selection simply
// not having survived the restart.
if (record?.activeCodexAccountPinned !== undefined && validated.activeCodexAccountPinned === undefined) {
warnings.push("activeCodexAccountPinned is not a valid account id — the manually selected account is no longer pinned");
}
const raw = record?.codexAccountPriorities;
if (raw !== undefined && validated.codexAccountPriorities === undefined) {
warnings.push("codexAccountPriorities is invalid (expected account ids mapped to integers between -100 and 100) — account selection order is disabled");
}
const rawThresholds = record?.codexAccountAutoSwitchThresholds;
if (rawThresholds !== undefined && !codexAccountAutoSwitchThresholdsSchema.safeParse(rawThresholds).success) {
warnings.push(validated.codexAccountAutoSwitchThresholds === undefined
? "codexAccountAutoSwitchThresholds is invalid (expected account ids mapped to integers between 0 and 100) — per-account usage thresholds are disabled"
: "codexAccountAutoSwitchThresholds contains invalid entries (expected account ids mapped to integers between 0 and 100) — invalid entries were ignored");
}
return warnings;
}
export function warnDegradedCodexAccountPriorities(rawParsed: unknown, validated: OcxConfig): void {
for (const warning of degradedCodexAccountPriorityWarnings(rawParsed, validated)) {
console.warn(`⚠️ config.json ${warning}`);
}
}
export function degradedCodexQuotaAutoRefreshWarning(rawParsed: unknown, validated: OcxConfig): string | null {
const raw = rawConfigRecord(rawParsed)?.codexQuotaAutoRefresh;
if (raw === undefined || validated.codexQuotaAutoRefresh !== undefined) return null;
return "codexQuotaAutoRefresh is invalid — automatic quota-window activation is disabled";
}
export function warnDegradedCodexQuotaAutoRefresh(rawParsed: unknown, validated: OcxConfig): void {
const warning = degradedCodexQuotaAutoRefreshWarning(rawParsed, validated);
if (warning) console.warn(`⚠️ config.json ${warning}`);
}
/**
* Companion to the degrade warnings above, for a malformed or ambiguous declared
* grouping. The list now degrades on its own so the rest of `pool` survives, which is
* also why it needs a voice: nothing else about the config looks different afterwards,
* and silently ungrouped credentials read as capacity the pool does not have.
*/
export function degradedCredentialGroupsWarning(rawParsed: unknown): string | null {
const pool = rawConfigRecord(rawConfigRecord(rawParsed)?.pool);
if (!pool || pool.credentialGroups === undefined) return null;
const parsed = credentialGroupsSchema.safeParse(pool.credentialGroups);
if (parsed.success) return null;
// Every issue message is redacted before it is joined. The custom messages now name
// group/member positions instead of the offending strings; the redaction stays as a
// second layer for any schema default message that still embeds a value.
const details = parsed.error.issues.map(issue => redactSecretString(issue.message)).join("; ");
return `pool.credentialGroups is invalid (${details}) — declared quota grouping is disabled; other pool settings were preserved`;
}
export function warnDegradedCredentialGroups(rawParsed: unknown): void {
const warning = degradedCredentialGroupsWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}`);
}
/**
* The apiKeys schema salvages entry by entry rather than failing the parse, so a
* dropped key is otherwise invisible — and it will not be re-saved by the next
* mutation. Say so out loud. Compares the raw array against the validated one,
* the same shape as the degrade warnings above.
*/
/**
* Give every salvaged key a stable, targetable id.
*
* Pure and deterministic on purpose. Two earlier spellings were wrong: minting a
* UUID inside the schema transform handed out a different id on every parse, and
* repairing-then-writing during `loadConfig` put a file write on the read path,
* where it could clobber a concurrent legitimate save with a stale snapshot.
*
* So the replacement id is derived from the entry's position, which is already
* how the file orders these rows: same file in, same ids out, no I/O and no
* randomness. It is not derived from the secret — a public identifier should
* never be a function of key material.
*/
export function normalizeApiKeyIds(config: OcxConfig): OcxConfig {
const keys = config.apiKeys;
if (!keys?.length) return config;
// Reserve every explicit id BEFORE synthesizing any, or a synthetic
// `salvaged-1` assigned to row 1 would push a row that legitimately owns that
// id onto `salvaged-2`. An id the user already has is the one thing this
// repair must never take away.
const reserved = new Set<string>();
for (const entry of keys) {
if (entry.id) reserved.add(entry.id);
}
const taken = new Set<string>(reserved);
const kept = new Set<string>();
keys.forEach((entry, index) => {
// The first row holding an explicit id keeps it; later collisions are the
// ones that move.
if (entry.id && !kept.has(entry.id)) {
kept.add(entry.id);
return;
}
let candidate = `salvaged-${index + 1}`;
let suffix = 1;
while (taken.has(candidate)) candidate = `salvaged-${index + 1}-${++suffix}`;
entry.id = candidate;
taken.add(candidate);
kept.add(candidate);
});
return config;
}
export function warnDegradedApiKeys(rawParsed: unknown, validated: OcxConfig): void {
if (!rawParsed || typeof rawParsed !== "object") return;
const raw = (rawParsed as Record<string, unknown>).apiKeys;
if (raw === undefined) return;
if (!Array.isArray(raw)) {
console.warn(`⚠️ config.json apiKeys is not an array — ignoring it; generate a new key from the API tab`);
return;
}
const dropped = raw.length - (validated.apiKeys?.length ?? 0);
if (dropped > 0) {
console.warn(`⚠️ config.json apiKeys: skipped ${dropped} malformed entr${dropped === 1 ? "y" : "ies"} — the remaining keys still work`);
}
// Same-length repairs are invisible to the count above, and they are the ones
// that show up as a blank name or an unknown date in the dashboard. Say so.
const repaired = raw.filter(row => {
if (!row || typeof row !== "object") return false;
const entry = row as Record<string, unknown>;
// Must match the schema exactly: a row whose key is unusable was DROPPED, and
// saying "the key still works" about it would be a lie.
if (!isUsableApiKeySecret(entry.key)) return false;
return typeof entry.id !== "string" || !entry.id
|| typeof entry.name !== "string"
|| typeof entry.createdAt !== "string";
}).length;
if (repaired > 0) {
console.warn(`⚠️ config.json apiKeys: repaired metadata on ${repaired} entr${repaired === 1 ? "y" : "ies"} — the key still works, but its name or date may read as unknown`);
}
// A duplicate id is repaired too, and it is not visible in either count above.
const ids = raw.filter(row => row && typeof row === "object" && isUsableApiKeySecret((row as Record<string, unknown>).key))
.map(row => (row as Record<string, unknown>).id)
.filter((id): id is string => typeof id === "string" && !!id);
const duplicates = ids.length - new Set(ids).size;
if (duplicates > 0) {
console.warn(`⚠️ config.json apiKeys: ${duplicates} entr${duplicates === 1 ? "y" : "ies"} shared an id — reassigned so each key can be renamed and revoked on its own`);
}
}
export const CLAUDE_SUBAGENT_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
export function isClaudeSubagentEffort(value: unknown): value is NonNullable<OcxClaudeCodeConfig["subagentEffort"]> {
return typeof value === "string" && CLAUDE_SUBAGENT_EFFORTS.includes(value as typeof CLAUDE_SUBAGENT_EFFORTS[number]);
}
export function rawClaudeSubagentEffort(rawParsed: unknown): unknown {
const raw = rawConfigRecord(rawParsed);
const claudeCode = raw?.claudeCode;
if (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode)) return undefined;
return (claudeCode as Record<string, unknown>).subagentEffort;
}
export function normalizePersistedClaudeCode(claudeCode: unknown): OcxConfig["claudeCode"] {
if (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode)) {
return claudeCode as OcxConfig["claudeCode"];
}
const normalized = { ...claudeCode } as Record<string, unknown>;
if (Object.hasOwn(normalized, "subagentModelForce") && !isSubagentModelEntry(normalized.subagentModelForce)) delete normalized.subagentModelForce;
// A malformed hand edit must not arm CLI interception or discard the whole config.
if (Object.hasOwn(normalized, "cliFirstParty") && typeof normalized.cliFirstParty !== "boolean") {
delete normalized.cliFirstParty;
}
if (Object.hasOwn(normalized, "subagentEffort") && !isClaudeSubagentEffort(normalized.subagentEffort)) {
delete normalized.subagentEffort;
}
// A hand-authored config never passes through the management validator, so coerce here too.
// A malformed classifierFallbacks (a bare string, or an array with non-string entries) would
// otherwise reach the resolver unchecked.
if (Object.hasOwn(normalized, "classifierModel")) {
const value = typeof normalized.classifierModel === "string" ? normalized.classifierModel.trim() : "";
if (value.length > 0) normalized.classifierModel = value;
else delete normalized.classifierModel;
}
if (Object.hasOwn(normalized, "classifierFallbacks")) {
const raw = normalized.classifierFallbacks;
const kept = Array.isArray(raw)
? raw.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0).map(entry => entry.trim())
: [];
if (kept.length > 0) normalized.classifierFallbacks = kept;
else delete normalized.classifierFallbacks;
}
const desktopProfile = normalized.desktopProfile;
if (desktopProfile && typeof desktopProfile === "object" && !Array.isArray(desktopProfile)) {
const profile = { ...desktopProfile } as Record<string, unknown>;
if (typeof profile.appliedFingerprint !== "string") delete profile.appliedFingerprint;
if (typeof profile.appliedAt !== "string") delete profile.appliedAt;
normalized.desktopProfile = profile;
}
return normalized as OcxConfig["claudeCode"];
}
export function normalizeClaudeSubagentEffort(config: OcxConfig, _rawParsed: unknown): OcxConfig {
// Unconditional. This used to short-circuit when `subagentEffort` was absent or already valid,
// which meant a config whose ONLY defect was elsewhere in `claudeCode` was never normalized.
// The specialized subagentEffort WARNING is a separate concern and stays exactly as it is.
if (!config.claudeCode) return config;
return { ...config, claudeCode: normalizePersistedClaudeCode(config.claudeCode) };
}
export function warnDegradedClaudeSubagentEffort(rawParsed: unknown): void {
const force = rawSubagentModelForce(rawParsed);
if (force !== undefined && !isSubagentModelEntry(force)) console.warn("⚠️ config.json claudeCode.subagentModelForce is invalid — ignoring it. Other settings were preserved.");
const rawEffort = rawClaudeSubagentEffort(rawParsed);
if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) {
console.warn(`⚠️ config.json claudeCode.subagentEffort is invalid (expected ${CLAUDE_SUBAGENT_EFFORTS.join(", ")}) — ignoring it. Other settings were preserved.`);
}
}
export function malformedUpstreamHostCircuitThresholdWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "upstreamHostCircuitThreshold")) return null;
const threshold = raw.upstreamHostCircuitThreshold;
if (threshold === undefined) return null;
if (typeof threshold === "number"
&& Number.isInteger(threshold)
&& threshold >= 0
&& threshold <= UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD) return null;
return `upstreamHostCircuitThreshold ignored: expected an integer from 0 to ${UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD}`;
}
export function warnDegradedUpstreamHostCircuitThreshold(rawParsed: unknown): void {
const warning = malformedUpstreamHostCircuitThresholdWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
export function malformedPlaintextV2AgentMessagesWarning(value: unknown): string | null {
const raw = rawConfigRecord(value);
if (!raw || raw.plaintextV2AgentMessages === undefined || typeof raw.plaintextV2AgentMessages === "boolean") return null;
return "plaintextV2AgentMessages ignored: expected a boolean";
}
export function warnDegradedPlaintextV2AgentMessages(value: unknown): void {
const warning = malformedPlaintextV2AgentMessagesWarning(value);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
export function malformedAgentTaskRecoveryWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "agentTaskRecovery")) return null;
const result = agentTaskRecoverySchema.safeParse(raw.agentTaskRecovery);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `agentTaskRecovery${field ? `.${field}` : ""} ignored: invalid experimental recovery configuration`;
}
export function warnDegradedAgentTaskRecovery(rawParsed: unknown): void {
const warning = malformedAgentTaskRecoveryWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
export function malformedRuntimeRoleWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "runtimeRole") || raw.runtimeRole === undefined) return null;
if (runtimeRoleSchema.safeParse(raw.runtimeRole).success) return null;
return 'runtimeRole ignored: expected "standalone", "hub", or "client"; falling back to "standalone"';
}
export function warnDegradedRuntimeRole(rawParsed: unknown): void {
const warning = malformedRuntimeRoleWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
export function malformedOptionalRemoteBlockWarning(
rawParsed: unknown,
key: "hub" | "remoteGui",
): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, key) || raw[key] === undefined) return null;
const schema = key === "hub" ? hubConfigSchema : remoteGuiConfigSchema;
const result = schema.safeParse(raw[key]);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `${key}${field ? `.${field}` : ""} ignored: invalid remote GUI configuration`;
}
export function malformedClientConnectionWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "client") || raw.client === undefined) return null;
const result = clientConnectionSchema.safeParse(raw.client);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `client${field ? `.${field}` : ""} invalid: remote client mode is disabled until config.json is repaired`;
}
export function warnDegradedOptionalRemoteBlocks(rawParsed: unknown): void {
for (const key of ["hub", "remoteGui"] as const) {
const warning = malformedOptionalRemoteBlockWarning(rawParsed, key);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
}
export function malformedQuotaResetNotifyWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "quotaResetNotify")) return null;
const result = quotaResetNotifySchema.safeParse(raw.quotaResetNotify);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `quotaResetNotify${field ? `.${field}` : ""} ignored: invalid quota-reset notification configuration`;
}
export function malformedCatalogAutoRefreshWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "catalogAutoRefresh")) return null;
const result = catalogAutoRefreshSchema.safeParse(raw.catalogAutoRefresh);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `catalogAutoRefresh${field ? `.${field}` : ""} ignored: invalid catalog auto-refresh configuration`;
}
/**
* The same silent-in-the-wrong-direction failure, and the most expensive instance of it here:
* a dropped spend section means the ceilings are not enforced, and an unenforced ceiling is
* indistinguishable from one nothing has reached. The operator finds out from the bill.
*/
export function malformedSpendWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "spend")) return null;
const result = spendSchema.safeParse(raw.spend);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `spend${field ? `.${field}` : ""} ignored: invalid spend ceiling configuration, so no token ceiling is enforced`;
}
/**
* Same silent-in-the-wrong-direction failure as the notification block: a dropped pool policy means
* the accounts the operator meant to exclude keep taking traffic, and the only visible symptom is
* traffic going somewhere it was supposed to stop going.
*/
export function malformedCodexPoolWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "codexPool")) return null;
const result = codexPoolSchema.safeParse(raw.codexPool);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `codexPool${field ? `.${field}` : ""} ignored: invalid Codex pool selection policy`;
}
export function malformedTelemetryWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "telemetry") || raw.telemetry === undefined) return null;
const result = telemetryConfigSchema.safeParse(raw.telemetry);
if (result.success) return null;
const field = result.error.issues[0]?.path.join(".");
return `telemetry${field ? `.${field}` : ""} ignored: invalid telemetry consent configuration`;
}
export function warnDegradedTelemetry(rawParsed: unknown): void {
const warning = malformedTelemetryWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
/**
* Warn once per load that the section was dropped.
*
* This matters more than a usual degradation notice: the failure is SILENT in the direction
* that hurts. A dropped section means notifications are off, so the operator sees nothing —
* which is exactly what they would see if the feature were working and no reset had happened.
*/
export function warnDegradedQuotaResetNotify(rawParsed: unknown): void {
const warning = malformedQuotaResetNotifyWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
/**
* Warn once per load that the section was dropped.
*
* Same silent-in-the-wrong-direction failure as the notification block: a dropped section
* means the scheduler never starts, so the operator sees a stale catalog — which is exactly
* what they would see if the feature were working and no new models had shipped.
*/
export function warnDegradedCatalogAutoRefresh(rawParsed: unknown): void {
const warning = malformedCatalogAutoRefreshWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
/**
* Warn once per load that the pool policy was dropped.
*
* `.catch(undefined)` turns a malformed policy into a SUCCESSFUL parse, so without this the proxy
* starts, rotates onto the accounts the operator meant to exclude, and prints nothing. The visible
* symptom would be traffic going exactly where it was told not to go.
*/
export function warnDegradedCodexPool(rawParsed: unknown): void {
const warning = malformedCodexPoolWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
type NativeSubagentPersistedField = "injectionModel" | "injectionEffort" | "syncCodexSubagentDefaults";
export function rawConfigRecord(rawParsed: unknown): Record<string, unknown> | null {
return rawParsed !== null && typeof rawParsed === "object" && !Array.isArray(rawParsed)
? rawParsed as Record<string, unknown>
: null;
}
export function malformedNativeSubagentFields(rawParsed: unknown): NativeSubagentPersistedField[] {
const raw = rawConfigRecord(rawParsed);
if (!raw) return [];
const malformed: NativeSubagentPersistedField[] = [];
if (Object.hasOwn(raw, "injectionModel") && typeof raw.injectionModel !== "string") {
malformed.push("injectionModel");
}
if (Object.hasOwn(raw, "injectionEffort") && typeof raw.injectionEffort !== "string") {
malformed.push("injectionEffort");
}
if (Object.hasOwn(raw, "syncCodexSubagentDefaults") && typeof raw.syncCodexSubagentDefaults !== "boolean") {
malformed.push("syncCodexSubagentDefaults");
}
return malformed;
}
export function malformedNativeSubagentFieldWarning(field: NativeSubagentPersistedField): string {
const expected = field === "syncCodexSubagentDefaults" ? "a boolean" : "a string";
return `${field} ignored: expected ${expected}`;
}
export const MALFORMED_CODEX_AUTH_METHOD_WARNING = 'codexAuthMethod ignored: using "auto" for Codex pool logins. Expected "auto", "device-only", or omission.';
export function malformedCodexAuthMethodWarning(rawParsed: unknown): string | null {
if (codexAuthMethodSchema.safeParse(rawConfigRecord(rawParsed)?.codexAuthMethod).success) return null;
return MALFORMED_CODEX_AUTH_METHOD_WARNING;
}
export function malformedCodexAccountPickerWarning(rawParsed: unknown): string | null {
const raw = rawConfigRecord(rawParsed);
if (!raw || !Object.hasOwn(raw, "codexAccountPickerEnabled")) return null;
if (typeof raw.codexAccountPickerEnabled === "boolean") return null;
return "codexAccountPickerEnabled ignored: expected a boolean";
}
export function warnDegradedCodexAccountPicker(rawParsed: unknown): void {
const warning = malformedCodexAccountPickerWarning(rawParsed);
if (warning) console.warn(`⚠️ config.json ${warning}. Other settings were preserved.`);
}
export function nativeSubagentSyncDisabledReason(config: OcxConfig, rawParsed?: unknown): string | null {
if (config.syncCodexSubagentDefaults !== true) return null;
const malformed = malformedNativeSubagentFields(rawParsed);
if (malformed.includes("injectionModel")) return "injectionModel must be a string";
if (!config.injectionModel?.trim()) return "a nonblank injectionModel is required";
if (malformed.includes("injectionEffort")) return "injectionEffort must be a string or omitted";
if (config.injectionEffort !== undefined && !isCodexReasoningEffort(config.injectionEffort)) {
return "injectionEffort must be a supported Codex reasoning effort";
}
return null;
}
export function normalizeNativeSubagentSync(config: OcxConfig, rawParsed?: unknown): OcxConfig {
if (!nativeSubagentSyncDisabledReason(config, rawParsed)) return config;
const normalized = { ...config };
delete normalized.syncCodexSubagentDefaults;
return normalized;
}
export function warnDegradedNativeSubagentConfig(rawParsed: unknown, config: OcxConfig): void {
for (const field of malformedNativeSubagentFields(rawParsed)) {
console.warn(`⚠️ config.json ${malformedNativeSubagentFieldWarning(field)}. Other settings were preserved.`);
}
const reason = nativeSubagentSyncDisabledReason(config, rawParsed);
if (reason) {
console.warn(`⚠️ config.json syncCodexSubagentDefaults was disabled: ${reason}. Other settings were preserved.`);
}
}
/**
* Registry metadata can gain service-tier capability after a config was written. An explicit
* `fastWire: null` remains authoritative on load and on whole-document writes; rejecting either
* would discard or lock access to unrelated providers and API keys. Direct contradictions within
* one provider row remain schema errors through the outer config refinement, where the dynamic
* provider name can be redacted before it reaches diagnostics.
*/
export function inheritedFastWireConflictProviderNames(
config: Pick<OcxConfig, "providers">,
): string[] {
const conflicts: string[] = [];
for (const [name, provider] of Object.entries(config.providers)) {
if (provider.fastWire !== null || provider.supportsServiceTier === false) continue;
if (providerFastSwitchOff(name, provider)) continue;
const registry = providerMatchesRegistryTransport(name, provider)
? getProviderRegistryEntry(name)
: undefined;
if (!registry) continue;
const effectiveProviderCapability = provider.supportsServiceTier ?? registry.supportsServiceTier;
const effectiveModelCapabilities = {
...(registryModelServiceTierCapabilityApplies(registry, provider)
? registry.modelSupportsServiceTier ?? {}
: {}),
...(provider.modelSupportsServiceTier ?? {}),
};
if (
effectiveProviderCapability === true
|| Object.values(effectiveModelCapabilities).some(value => value === true)
) {
conflicts.push(name);
}
}
return conflicts;
}
export function inheritedFastWireConflictWarning(name: string): string {
return `providers.${redactSecretString(name)}.fastWire=null overrides service-tier capability inherited from the matching registry entry`;
}
export function warnInheritedFastWireConflicts(configPath: string, config: OcxConfig): void {
const names = inheritedFastWireConflictProviderNames(config);
if (names.length === 0 || hasWarnedInheritedFastWireConflict(configPath)) return;
markWarnedInheritedFastWireConflict(configPath);
console.warn(
`⚠️ config.json ${names.map(inheritedFastWireConflictWarning).join("; ")}. `
+ "The persisted providers and API keys were preserved.",
);
}
/** Hand-edited alias mistakes disable only the bad alias; providers and routing survive. */
export function sanitizeAliasesForLoad(raw: unknown, warn: (message: string) => void = console.warn): void {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
const root = raw as Record<string, unknown>;
if (!root.providers || typeof root.providers !== "object" || Array.isArray(root.providers)) return;
const providers = root.providers as Record<string, Record<string, unknown>>;
const providerNames = new Set(Object.keys(providers).map(name => name.toLowerCase()));
const claimedProviders = new Set<string>();
const comboAliases = new Set(Object.values((root.combos as Record<string, { alias?: unknown }> | undefined) ?? {})
.map(combo => typeof combo?.alias === "string" ? combo.alias.toLowerCase() : "").filter(Boolean));
const accountNamespaces = new Set(Object.keys((root.codexAccountNamespaces as Record<string, unknown> | undefined) ?? {}).map(name => name.toLowerCase()));
for (const [providerName, provider] of Object.entries(providers)) {
// #7705: a hand-edited template that would not validate loses only itself, not the config.
if (provider.aliasTemplate !== undefined
&& (typeof provider.aliasTemplate !== "string" || aliasTemplateError(provider.aliasTemplate) !== null)) {
warn(`Ignoring invalid alias template for provider ${providerName} in config.json`);
delete provider.aliasTemplate;
}
const alias = provider.alias;
if (typeof alias !== "string" || !isValidProviderName(alias)
|| providerNames.has(alias.toLowerCase()) || claimedProviders.has(alias.toLowerCase())
|| comboAliases.has(alias.toLowerCase()) || accountNamespaces.has(alias.toLowerCase())) {
if (alias !== undefined) warn("Ignoring invalid or colliding provider alias in config.json");
delete provider.alias;
} else claimedProviders.add(alias.toLowerCase());
if (!provider.modelAliases || typeof provider.modelAliases !== "object" || Array.isArray(provider.modelAliases)) {
if (provider.modelAliases !== undefined) delete provider.modelAliases;
continue;
}
const aliases = provider.modelAliases as Record<string, unknown>;
const nativeIds = new Set((Array.isArray(provider.models) ? provider.models : []).filter((id): id is string => typeof id === "string").map(id => id.toLowerCase()));
const claimed = new Set<string>();
for (const [id, value] of Object.entries(aliases)) {
const lower = typeof value === "string" ? value.toLowerCase() : "";
if (typeof value !== "string" || !MODEL_ALIAS_PATTERN.test(value) || claimed.has(lower)
|| nativeIds.has(lower) || comboAliases.has(lower) || /^(?:gpt-|o1-|o3-|o4-|codex-)/i.test(value)) {
warn(`Ignoring invalid or colliding model alias for ${id} in config.json`);
delete aliases[id];
} else claimed.add(lower);
}
}
}
/** Hand-edited display-name mistakes disable only the bad label. */
export function sanitizeModelDisplayNamesForLoad(raw: unknown, warn: (message: string) => void = console.warn): void {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
const root = raw as Record<string, unknown>;
if (!root.providers || typeof root.providers !== "object" || Array.isArray(root.providers)) return;
for (const [providerName, providerValue] of Object.entries(root.providers as Record<string, unknown>)) {
if (!providerValue || typeof providerValue !== "object" || Array.isArray(providerValue)) continue;
const provider = providerValue as Record<string, unknown>;
const value = provider.modelDisplayNames;
if (value === undefined) continue;
const providerLabel = JSON.stringify(redactSecretString(providerName));
if (!value || typeof value !== "object" || Array.isArray(value)
|| Object.entries(value).length > MODEL_DISCOVERY_MAX_MODELS) {
warn(`Ignoring invalid modelDisplayNames map for provider ${providerLabel} in config.json`);
delete provider.modelDisplayNames;
continue;
}
const labels = value as Record<string, unknown>;
for (const [modelId, rawDisplayName] of Object.entries(labels)) {
const displayName = typeof rawDisplayName === "string" ? rawDisplayName.trim() : rawDisplayName;
if (modelDisplayNamesConfigError({ [modelId]: displayName })) {
const safeModelId = JSON.stringify(redactSecretString(modelId));
warn(`Ignoring invalid modelDisplayNames entry ${safeModelId} for provider ${providerLabel} in config.json`);
delete labels[modelId];
} else {
labels[modelId] = displayName;
}
}
if (Object.keys(labels).length === 0) delete provider.modelDisplayNames;
}
}
/** Refresh the user cost-overlay registry from `config` and return it unchanged. */
export function withRefreshedCostOverlays(config: OcxConfig): OcxConfig {
refreshConfigDerivedRegistries(config);
return config;
}