@bitkyc08/opencodex 2.23.0-preview.20260816 → 2.24.0

package/src/codex/routing.ts

@@ -127,7 +127,8 @@ let lastReconciledGeneration = 0;
 let liveHealthAccountIds = new Set<string>();
 
 export type CodexUpstreamOutcome = number | "connect_error" | "timeout" | "connect_neutral";
-export type CodexUpstreamOutcomeClass = "success" | "credential" | "quota" | "transient" | "caller" | "neutral" | "unknown";
+export type CodexUpstreamOutcomeClass = "success" | "credential"
+  | "workspace" | "quota" | "transient" | "caller" | "neutral" | "unknown";
 export type CodexCooldownSource = "retry-after" | "reset-derived" | "default";
 /**
  * Native Codex quota groups known to be independent upstream. Keep the mapping
@@ -193,6 +194,12 @@ export type CodexUpstreamOutcomeMeta = {
   now?: number;
   /** (provider, host) ledger key for account-neutral reachability failures (#914). */
   hostKey?: string;
+  /**
+   * Upstream denial evidence for a 403. A workspace/entitlement denial means the CREDENTIAL
+   * is fine and the account simply cannot reach this workspace, so it must not be quarantined
+   * for reauthentication (#1789). Absent evidence keeps the historical credential handling.
+   */
+  denial?: "workspace" | "entitlement";
   /** Stable transport code recorded alongside a neutral host failure. */
   lastFailureCode?: string;
   /** Native model selected for this request; used only for confirmed scoped quotas. */
@@ -327,7 +334,10 @@ export function computeCodexUsageScore(quota: {
   return values.length > 0 ? Math.max(...values) : CODEX_UNKNOWN_USAGE_SCORE;
 }
 
-export function classifyCodexUpstreamOutcome(outcome: CodexUpstreamOutcome): CodexUpstreamOutcomeClass {
+export function classifyCodexUpstreamOutcome(
+  outcome: CodexUpstreamOutcome,
+  denial?: "workspace" | "entitlement",
+): CodexUpstreamOutcomeClass {
   if (outcome === "connect_neutral") return "neutral";
   if (outcome === "connect_error" || outcome === "timeout") return "transient";
   if (!Number.isFinite(outcome)) return "unknown";
@@ -337,6 +347,11 @@ export function classifyCodexUpstreamOutcome(outcome: CodexUpstreamOutcome): Cod
   // and says nothing about the credential. Relayed as the neutral class so a
   // stray 3xx cannot increment an account's transient streak.
   if (outcome >= 300 && outcome < 400) return "neutral";
+  // 401 is always a credential problem. A 403 is only a credential problem when nothing
+  // tells us otherwise: a workspace/entitlement denial (#1789) means the credential is valid
+  // and the account simply lacks access here, so quarantining it for reauth is wrong advice.
+  // Absent denial evidence the historical mapping stands, so the change fails safe.
+  if (outcome === 403 && denial !== undefined) return "workspace";
   if (outcome === 401 || outcome === 403) return "credential";
   // 402 Payment Required is treated as quota exhaustion for pool cooldown/failover
   // (same-request alternate retry records this outcome for the depleted account).
@@ -1596,7 +1611,7 @@ export function recordCodexUpstreamOutcome(
   const writerGeneration = meta.writerGeneration ?? captureConfigGeneration();
   if (writerGeneration < lastReconciledGeneration && !liveHealthAccountIds.has(accountId)) return;
   const now = meta.now ?? Date.now();
-  const outcomeClass = classifyCodexUpstreamOutcome(outcome);
+  const outcomeClass = classifyCodexUpstreamOutcome(outcome, meta.denial);
   const quotaScope = codexQuotaScopeForModel(meta.modelId);
   if (outcomeClass === "success") {
     const scopedProbe = meta.probeQuotaScope
@@ -1676,6 +1691,18 @@ export function recordCodexUpstreamOutcome(
   }
 
   const lastFailureStatus = typeof outcome === "number" ? outcome : 0;
+  if (outcomeClass === "workspace") {
+    // The credential is valid; this account just cannot reach this workspace (#1789).
+    // Record the failure so routing stops preferring it, but do not mark it for
+    // reauthentication and do not sweep its thread affinities: telling the user to
+    // re-login is wrong advice that cannot fix a workspace grant.
+    upstreamHealth.set(accountId, {
+      consecutiveFailures: (upstreamHealth.get(accountId)?.consecutiveFailures ?? 0) + 1,
+      lastFailureStatus,
+      lastFailureAt: now,
+    });
+    return;
+  }
   if (outcomeClass === "credential") {
     // 401/403 quarantines the account for reauth. That supersedes quota state
     // entirely: a cooldown (and any probe lease) on an unusable account is moot.

package/src/combos/failover.ts

@@ -121,6 +121,26 @@ export function comboFailureDecision(
   if (isCyberPolicyCode(options?.code)) return "stop";
   const error = classifyError(status, "upstream_error", message);
   if (isCyberPolicyCode(error.code)) return "stop";
+  // A local input-admission refusal (#1524) says "this candidate cannot fit the request",
+  // not "the request is impossible": the next candidate may have a larger context window.
+  //
+  // This MUST be tested before the generic stop list below. Our own refusal message says
+  // "context window" -- that is what it refuses on -- and the classifier remaps that phrase,
+  // so checking the stop list first swallowed the signal and ended the chain. An UPSTREAM
+  // `context_length_exceeded` carries no admission code and still falls through to stop.
+  //
+  // Matched on the STRUCTURED code only, which classifyError now preserves for our own
+  // refusal. A raw substring test would additionally let any upstream override a terminal
+  // verdict by echoing the token in prose we do not control.
+  //
+  // Precise about what this is NOT: an upstream can still SET this code deliberately, since
+  // both extractors read the upstream error object. That is bounded rather than dangerous --
+  // an upstream already controls other hop signals (429, 5xx), and traversal is finite: policy
+  // tries each candidate once via `tried`, and combo excludes each attempted target. So this is
+  // structured-code-only, not provably local.
+  if (options?.code === "input_admission_refused" || error.code === "input_admission_refused") {
+    return "hop";
+  }
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }

package/src/config.ts

@@ -60,6 +60,7 @@ import {
   OPENAI_PROVIDER_TIER_VERSION,
   pinnedWireAdapter,
   REASONING_SUMMARY_DELIVERY_VALUES,
+  UPSTREAM_HTTP_VERSION_VALUES,
   type OcxClaudeCodeConfig,
   type OcxConfig,
   type OcxApiKeyEntry,
@@ -734,6 +735,12 @@ const providerConfigSchema = z.object({
   modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
   preserveResponsesReasoningContent: z.boolean().optional(),
   allowPrivateNetwork: z.boolean().optional(),
+  // The management API accepts `null` as "clear this", so a config written before the POST
+  // canonicalization below can hold one on disk. Rejecting it here would send the operator
+  // through invalid-config recovery for a value the API told them was fine.
+  upstreamHttpVersion: z.enum(UPSTREAM_HTTP_VERSION_VALUES)
+    .nullish()
+    .transform(value => value ?? undefined),
   noStructuredOutputModels: z.array(z.string().min(1))
     .transform(normalizeNonBlankStringArray)
     .optional(),
@@ -906,6 +913,20 @@ export function apiKeyTransportConfigError(
   return null;
 }
 
+/**
+ * Shared runtime boundary for the per-provider upstream HTTP-version pin (#1668). Used by
+ * the management write path (providerManagementConfigError / PATCH) so it can never disagree
+ * with the strict zod load schema: a value that survives POST/PATCH is always loadable, and
+ * a value the loader rejects is rejected at write time too.
+ */
+export function upstreamHttpVersionConfigError(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || !(UPSTREAM_HTTP_VERSION_VALUES as readonly string[]).includes(value)) {
+    return 'upstreamHttpVersion must be one of "auto", "http1.1", "h1", "http2", "h2", or null to clear';
+  }
+  return null;
+}
+
 export function positiveIntegerRecordConfigError(value: unknown, field: string): string | null {
   if (value === undefined) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
@@ -1997,12 +2018,30 @@ function normalizePersistedClaudeCode(claudeCode: unknown): OcxConfig["claudeCod
   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;
+  }
   return normalized as OcxConfig["claudeCode"];
 }
 
-function normalizeClaudeSubagentEffort(config: OcxConfig, rawParsed: unknown): OcxConfig {
-  const rawEffort = rawClaudeSubagentEffort(rawParsed);
-  if (rawEffort === undefined || isClaudeSubagentEffort(rawEffort)) return config;
+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) };
 }
 
@@ -2172,6 +2211,26 @@ export function loadConfig(): OcxConfig {
       warnDegradedAgentTaskRecovery(parsed);
       return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
     }
+    // Still failing, but if every complaint is about one or more named entries
+    // in an independent section, drop exactly those and keep the rest. Falling
+    // back to defaults here would silently retire the operator's providers,
+    // keys and prices over a mistake in one routing profile.
+    const salvaged = salvageConfigCandidate(merged, retryResult.error);
+    if (salvaged) {
+      {
+        warnDroppedConfigSections(configPath, salvaged.dropped, salvaged.issues);
+        const config = normalizeApiKeyIds(salvaged.parsed);
+        warnDegradedHostname(parsed, config);
+        warnDegradedApiKeys(parsed, config);
+        warnDegradedCodexAccountPriorities(parsed, config);
+        warnDegradedClaudeSubagentEffort(parsed);
+        warnDegradedNativeSubagentConfig(parsed, config);
+        warnDegradedCodexAccountPicker(parsed);
+        warnDegradedUpstreamHostCircuitThreshold(parsed);
+        warnDegradedAgentTaskRecovery(parsed);
+        return withRefreshedCostOverlays(normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, parsed), parsed));
+      }
+    }
     // Merge couldn't fix it — truly broken config
     warnAndBackupInvalidConfig(configPath, result.error);
     return getDefaultConfig();
@@ -2450,11 +2509,31 @@ function configDiagnosticsFromRaw(raw: string): ConfigDiagnostics {
       return validFileConfigDiagnostics(normalizeApiKeyIds(result.data as OcxConfig), parsed);
     }
 
-    const retryResult = configSchema.safeParse(mergeConfigDefaults(parsed));
+    const merged = mergeConfigDefaults(parsed);
+    const retryResult = configSchema.safeParse(merged);
     if (retryResult.success) {
       return validFileConfigDiagnostics(normalizeApiKeyIds(retryResult.data as OcxConfig), parsed);
     }
 
+    // #1785: one invalid routing profile must not make diagnostics report the built-in
+    // defaults AS the config, because a later config write persists those defaults over the
+    // operator's providers, keys and prices.
+    //
+    // The failure is still reported. `source` stays "fallback" and `error` keeps the real
+    // schema message -- diagnostics is the surface that tells callers the file is invalid,
+    // and every consumer that must refuse an invalid config (provider reload, catalog sync,
+    // cost reconcile, codex admission) gates on exactly those two fields. Only `config`
+    // changes: it carries the salvaged document instead of factory defaults, so a caller
+    // that ignores the error and writes it back preserves what the operator configured.
+    const salvaged = salvageConfigCandidate(merged, retryResult.error);
+    if (salvaged) {
+      return {
+        config: normalizeApiKeyIds(salvaged.parsed),
+        source: "fallback",
+        error: schemaDiagnosticsError(result.error),
+      };
+    }
+
     return { config: getDefaultConfig(), source: "fallback", error: schemaDiagnosticsError(result.error) };
   } catch {
     return { config: getDefaultConfig(), source: "fallback", error: "invalid_json" };
@@ -3428,6 +3507,194 @@ function warnConfigRepaired(configPath: string, error: z.ZodError): void {
   console.error(`opencodex config at ${configPath}: repaired missing field(s) [${fields}] with defaults. Your providers and accounts are preserved.`);
 }
 
+/**
+ * Sections whose entries are independent of one another, so one bad entry is
+ * safe to drop without changing what the rest mean.
+ *
+ * Both are validated entry-by-entry in the `superRefine` above, which raises
+ * every finding as a *document*-level issue. That is what made a single routing
+ * candidate naming a disabled provider discard the operator's whole config —
+ * all eleven providers, every API key, and the entire `modelCosts` table —
+ * while the proxy carried on serving from built-in defaults and reporting
+ * healthy.
+ */
+const SALVAGEABLE_CONFIG_SECTIONS = ["routingProfiles", "combos"] as const;
+
+/**
+ * Drop just the named entries a parse failure blamed, so the rest of the
+ * document survives.
+ *
+ * Returns `null` when the failure was not confined to those sections — the
+ * caller then keeps its existing behaviour rather than guessing.
+ *
+ * The whole entry goes, not the individual offending candidate. A routing
+ * profile that quietly loses one candidate still routes, just not where the
+ * operator said it should, and a policy that silently changed shape is a worse
+ * outcome than one that is plainly absent. Absent is also the loud option: a
+ * dry-run against it answers `unknown_profile`, which — paired with the warning
+ * this emits — points at the real mistake.
+ */
+function dropInvalidConfigSections(
+  parsed: unknown,
+  error: z.ZodError,
+): { candidate: Record<string, unknown>; dropped: string[] } | null {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+
+  const doomed = new Map<string, Set<string>>();
+  for (const issue of error.issues) {
+    if (isUnsalvageableIssue(issue)) return null;
+    const [section, id] = issue.path;
+    if (typeof section !== "string" || typeof id !== "string") return null;
+    if (!(SALVAGEABLE_CONFIG_SECTIONS as readonly string[]).includes(section)) return null;
+    // A complaint about the container itself ("combos must be an object") is
+    // not about one entry, so there is nothing selective to drop.
+    if (issue.path.length < 2) return null;
+    let ids = doomed.get(section);
+    if (!ids) doomed.set(section, ids = new Set());
+    ids.add(id);
+  }
+  if (doomed.size === 0) return null;
+
+  const candidate: Record<string, unknown> = { ...(parsed as Record<string, unknown>) };
+  const dropped: string[] = [];
+  for (const [section, ids] of doomed) {
+    const current = candidate[section];
+    if (!current || typeof current !== "object" || Array.isArray(current)) return null;
+    const kept: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(current as Record<string, unknown>)) {
+      if (ids.has(key)) dropped.push(`${section}.${key}`);
+      else kept[key] = value;
+    }
+    candidate[section] = kept;
+  }
+  return dropped.length > 0 ? { candidate, dropped } : null;
+}
+
+/**
+ * Salvage until the document parses, not just once.
+ *
+ * One pass is not enough because the sections depend on each other: routing
+ * profiles are validated against the combo map, so dropping an invalid combo can
+ * expose a profile that referenced it. A single-pass salvage sees that second
+ * failure and gives up, discarding the whole config -- the exact outcome this
+ * code exists to prevent.
+ *
+ * `rawDocument` is the operator's document before defaults were merged in. When
+ * supplied, the same entries are deleted from it too, so a diagnostics caller can
+ * still tell an absent optional setting from one we injected.
+ */
+
+/**
+ * Findings that must never be salvaged away.
+ *
+ * Salvage removes the entry a finding blamed, which is right for an ordinary
+ * validation mistake and wrong for a namespace collision: the collision is a
+ * *relationship* between a combo/profile and a Codex account selector, and it is
+ * reported on the combo. Dropping that combo makes the document parse and quietly
+ * admits the account selector the schema just refused, turning a hard admission
+ * boundary into a config that loads. Refuse the whole document instead.
+ */
+const UNSALVAGEABLE_ISSUE_MESSAGES: readonly string[] = [
+  CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR,
+];
+
+function isUnsalvageableIssue(issue: z.ZodIssue): boolean {
+  return UNSALVAGEABLE_ISSUE_MESSAGES.some(message => issue.message.includes(message));
+}
+function salvageConfigCandidate(
+  merged: unknown,
+  initialError: z.ZodError,
+  rawDocument?: unknown,
+): {
+  candidate: Record<string, unknown>;
+  rawCandidate: unknown;
+  parsed: OcxConfig;
+  dropped: string[];
+  issues: z.ZodIssue[];
+} | null {
+  let candidate: unknown = merged;
+  let rawCandidate: unknown = rawDocument;
+  let error = initialError;
+  const dropped: string[] = [];
+  const issues: z.ZodIssue[] = [];
+  // Bounded by construction: every pass must remove at least one entry, and there
+  // are only so many entries to remove.
+  const budget = countSalvageableEntries(merged) + 1;
+  for (let pass = 0; pass < budget; pass++) {
+    const step = dropInvalidConfigSections(candidate, error);
+    if (!step || step.dropped.length === 0) return null;
+    dropped.push(...step.dropped);
+    issues.push(...error.issues);
+    candidate = step.candidate;
+    rawCandidate = deleteEntryPaths(rawCandidate, step.dropped);
+    const result = configSchema.safeParse(candidate);
+    if (result.success) {
+      return { candidate: step.candidate, rawCandidate, parsed: result.data as OcxConfig, dropped, issues };
+    }
+    error = result.error;
+  }
+  return null;
+}
+
+function countSalvageableEntries(document: unknown): number {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return 0;
+  let total = 0;
+  for (const section of SALVAGEABLE_CONFIG_SECTIONS) {
+    const value = (document as Record<string, unknown>)[section];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      total += Object.keys(value as Record<string, unknown>).length;
+    }
+  }
+  return total;
+}
+
+/** Delete `section.id` entries from a copy of the raw document. */
+function deleteEntryPaths(document: unknown, entryPaths: readonly string[]): unknown {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return document;
+  const next: Record<string, unknown> = { ...(document as Record<string, unknown>) };
+  for (const entryPath of entryPaths) {
+    const separator = entryPath.indexOf(".");
+    if (separator <= 0) continue;
+    const section = entryPath.slice(0, separator);
+    const id = entryPath.slice(separator + 1);
+    const container = next[section];
+    if (!container || typeof container !== "object" || Array.isArray(container)) continue;
+    const kept: Record<string, unknown> = { ...(container as Record<string, unknown>) };
+    delete kept[id];
+    next[section] = kept;
+  }
+  return next;
+}
+
+/**
+ * Entry ids are operator-chosen and can be token-shaped, so nothing dynamic reaches
+ * the log unredacted. Static section names stay readable -- they are the part that
+ * tells the operator where to look.
+ */
+function redactEntryPath(entryPath: string): string {
+  const separator = entryPath.indexOf(".");
+  if (separator <= 0) return redactSecretString(entryPath);
+  return entryPath.slice(0, separator) + "." + redactSecretString(entryPath.slice(separator + 1));
+}
+
+function redactIssuePath(path: readonly PropertyKey[]): string {
+  return path
+    .map((segment, index) => (index === 0 && typeof segment === "string" ? segment : redactSecretString(String(segment))))
+    .join(".");
+}
+
+function warnDroppedConfigSections(configPath: string, dropped: string[], issues: readonly z.ZodIssue[]): void {
+  if (warnedConfigFallbacks.has(configPath)) return;
+  warnedConfigFallbacks.add(configPath);
+  const reasons = issues
+    .map(issue => `${redactIssuePath(issue.path)}: ${redactSecretString(issue.message)}`)
+    .join("; ");
+  console.error(
+    `opencodex config at ${configPath}: dropped [${dropped.map(redactEntryPath).join(", ")}] and loaded the rest — ${reasons}. `
+    + "Everything else in your config, including providers and modelCosts, is preserved.",
+  );
+}
+
 export function readPidFileValue(): number | null {
   try {
     return parsePidFile(readFileSync(getPidPath(), "utf-8"));