@bitkyc08/opencodex 2.35.0 → 2.36.0-preview.20260830

package/src/oauth/generic-account-failover.ts

@@ -16,6 +16,7 @@
  */
 import { getAccountSet } from "./store";
 import { getValidAccessSnapshotForAccount, type OAuthAccessSnapshot } from "./index";
+import { exhaustedCooldownMs, hasHeadroomEvidence, rankAccountsByHeadroom } from "./account-quota-rank";
 import { parseRetryAfterMs } from "../combos/failover";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 import type { OcxConfig, OcxProviderConfig } from "../types";
@@ -60,12 +61,29 @@ interface PresenceEntry {
   readAt: number;
 }
 
+/**
+ * Ordered roster plus the active id, for the pre-dispatch preference.
+ *
+ * Same reasoning as the presence cache: `getAccountSet` reads through `loadAuthStore`,
+ * which chmods and re-parses the whole credential file on every call. Selection needs the
+ * ORDER and the active id, which the presence count cannot supply, so it gets its own
+ * TTL-bounded row. Ids and an active pointer only — never a credential.
+ */
+interface RosterEntry {
+  ids: string[];
+  activeId: string | null;
+  readAt: number;
+}
+
 /** Process-local, like the Anthropic pool's: a restart is allowed to forget a cooldown. */
 const health = new Map<string, AccountHealth>();
 
 /** Provider -> recent eligible-account count. TTL-bounded; never holds credential material. */
 const presence = new Map<string, PresenceEntry>();
 
+/** Provider -> recently read roster. TTL-bounded; never holds credential material. */
+const roster = new Map<string, RosterEntry>();
+
 const healthKey = (provider: string, accountId: string) => `${provider}\u0000${accountId}`;
 
 function isCooled(provider: string, accountId: string, now: number): boolean {
@@ -100,6 +118,24 @@ function eligibleAccountCount(providerName: string, now: number): number {
   return eligible;
 }
 
+/**
+ * Roster ids and the active pointer, read at most once per TTL window.
+ *
+ * `needsReauth` accounts are excluded for the same reason the presence count excludes
+ * them: a revoked credential cannot serve the request we are about to send.
+ */
+function cachedRoster(providerName: string, now: number): { ids: string[]; activeId: string | null } {
+  const cached = roster.get(providerName);
+  if (cached && now >= cached.readAt && now - cached.readAt < PRESENCE_CACHE_TTL_MS) {
+    return { ids: cached.ids, activeId: cached.activeId };
+  }
+  const set = getAccountSet(providerName);
+  const ids = set ? set.accounts.filter(a => a.needsReauth !== true).map(a => a.id) : [];
+  const activeId = set?.activeAccountId ?? null;
+  roster.set(providerName, { ids, activeId, readAt: now });
+  return { ids, activeId };
+}
+
 /**
  * Presence IS consent (#2568d).
  *
@@ -167,7 +203,11 @@ export function rotateGenericOAuthAccountOn429(
   if (!set || set.accounts.length < 2) return null;
 
   const parsed = parseRetryAfterMs(retryAfterHeader, now);
-  const cooldownMs = Math.min(parsed ?? DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS);
+  // An account whose allowance is provably spent gets a reset-aligned cooldown instead of
+  // the default minute: retrying it every 60s until the window rolls over is pure waste.
+  // A Retry-After from upstream still wins — it is the server's own instruction.
+  const exhausted = parsed === null ? exhaustedCooldownMs(providerName, failedAccountId, now) : null;
+  const cooldownMs = exhausted ?? Math.min(parsed ?? DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS);
   health.set(healthKey(providerName, failedAccountId), {
     cooldownUntil: now + cooldownMs,
     cooldownSource: parsed ? "retry-after" : "default",
@@ -179,15 +219,19 @@ export function rotateGenericOAuthAccountOn429(
   // A rotation means the roster in use just changed; do not answer the next activation question
   // from a count read before the failure.
   presence.delete(providerName);
+  // Same for the selection roster: the next request must not pick from a pre-failure read.
+  roster.delete(providerName);
   // Deterministic: start after the failed account so repeated 429s walk the roster instead of
-  // hammering whichever id happens to sort first.
+  // hammering whichever id happens to sort first. The ring is built BEFORE ranking — ranking
+  // the store's own order would change which account a quota-less provider rotates to.
   const order = set.accounts.map(account => account.id);
   const start = order.indexOf(failedAccountId);
-  for (let i = 1; i <= order.length; i++) {
-    const candidate = order[(start + i) % order.length]!;
-    if (candidate !== failedAccountId && eligible.includes(candidate)) return candidate;
-  }
-  return null;
+  const ring = start >= 0 ? [...order.slice(start + 1), ...order.slice(0, start)] : order;
+  const candidates = ring.filter(id => id !== failedAccountId && eligible.includes(id));
+  if (candidates.length === 0) return null;
+  // With no quota evidence this returns the ring untouched, so providers without
+  // per-account quota keep exactly the traversal they have today.
+  return rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
 }
 
 /**
@@ -204,6 +248,61 @@ export async function failoverAccountSnapshot(
   return getValidAccessSnapshotForAccount(providerName, accountId);
 }
 
+/**
+ * Which account should serve the FIRST attempt of a request.
+ *
+ * Rotation only ever ran after a 429, so a turn still opened on whichever account happened
+ * to be active — including one a previous probe already measured as spent. That costs a
+ * full upstream round trip and one of three rotations to rediscover what the cache knew.
+ *
+ * Returns null whenever the ordinary active-account path should be used unchanged: no
+ * quorum, rotation disabled, a single account, or no quota evidence to act on. This is a
+ * preference, never a gate — a cooled or unmeasured account is still perfectly usable, so
+ * an empty answer means "carry on", not "refuse".
+ */
+export function preferredInitialAccount(
+  config: OcxConfig,
+  providerName: string,
+  now = Date.now(),
+): string | null {
+  if (!isGenericOAuthFailoverEnabled(config, providerName)) return null;
+  // This runs on the initial resolution of EVERY request, and `loadAuthStore` has no
+  // cache: each call chmods the config dir, chmods the secret, reads the whole file and
+  // normalizes it (store.ts:136-151). So the store is consulted at most ONCE here, behind
+  // the same TTL the presence check uses, and never at all for a single-account provider.
+  const { ids: order, activeId: active } = cachedRoster(providerName, now);
+  if (order.length < 2) return null;
+
+  // Evidence is required BEFORE eligibility narrows the field. Without this, a provider
+  // with no quota data at all could still be redirected: cool the active account with a
+  // 429 and the eligible list collapses to one candidate, which any ranking returns
+  // unchanged — an answer that looks ranked but was never measured. The no-op guarantee
+  // for quota-less providers has to be checked on the full roster.
+  if (!hasHeadroomEvidence(providerName, order)) return null;
+
+  // Cooldowns are respected here, unlike in the presence count: this picks the account to
+  // send to right now, and one inside its 429 window is the single candidate we hold
+  // positive evidence against.
+  const eligible = order.filter(id => !isCooled(providerName, id, now));
+  if (eligible.length === 0) return null;
+
+  // Start the ring at the active account so an unranked outcome reproduces today's choice.
+  const start = active ? order.indexOf(active) : -1;
+  const ring = start >= 0 ? [...order.slice(start), ...order.slice(0, start)] : order;
+  const candidates = ring.filter(id => eligible.includes(id));
+  if (candidates.length === 0) return null;
+
+  const best = rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
+  // Nothing to do when the ranking agrees with the account we would have used anyway.
+  //
+  // The roster may be up to PRESENCE_CACHE_TTL_MS old, so this answer is a PREFERENCE the
+  // caller must be able to abandon: it resolves the account with `requireUsableAccount`,
+  // which rejects a removed or reauth-flagged account inside the store read it was already
+  // performing, and falls back to the active account. Validating here instead would mean a
+  // second uncached read of the credential file on every redirected request.
+  return best && best !== active ? best : null;
+}
+
 /** Earliest remaining cooldown, for a client-facing Retry-After when every account is cooled. */
 export function genericFailoverRetryAfterSeconds(providerName: string, now = Date.now()): number | null {
   const set = getAccountSet(providerName);
@@ -217,14 +316,22 @@ export function genericFailoverRetryAfterSeconds(providerName: string, now = Dat
   return earliest === null ? null : Math.max(1, Math.ceil((earliest - now) / 1000));
 }
 
+/** Test seam and manual-recovery hook. */
+export function forgetGenericFailoverRoster(providerName: string): void {
+  roster.delete(providerName);
+  presence.delete(providerName);
+}
+
 /** Test seam and manual-recovery hook. */
 export function clearGenericFailoverHealth(providerName?: string): void {
   if (!providerName) {
     health.clear();
     presence.clear();
+    roster.clear();
     return;
   }
   presence.delete(providerName);
+  roster.delete(providerName);
   for (const key of [...health.keys()]) {
     if (key.startsWith(`${providerName}\u0000`)) health.delete(key);
   }

package/src/oauth/index.ts

@@ -4,7 +4,7 @@ import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
 import { loadConfig, resolveEnvValue, saveConfig } from "../config";
 import { maskEmail } from "../lib/privacy";
 import { KiroTokenRefreshError, environmentKiroRoutingMetadata, loginKiro, refreshKiroToken, settleKiroLoginTransaction } from "./kiro";
-import { getAccountCredential, getAccountSet, removeAccount, saveAccountCredential, saveCredential, setActiveAccount, getCredential, credentialGeneration, createOAuthRefreshIntentLock, mergeAccountCredential, markAccountNeedsReauthIfGeneration, readOAuthRefreshIntent, writeOAuthRefreshIntent, markOAuthRefreshIntentStaleOwner, clearOAuthRefreshIntent, normalizeAuthStoreBuffer, OAuthMutationBusyError } from "./store";
+import { getAccountCredential, getAccountCredentialWithStatus, getAccountSet, removeAccount, saveAccountCredential, saveCredential, setActiveAccount, getCredential, credentialGeneration, createOAuthRefreshIntentLock, mergeAccountCredential, markAccountNeedsReauthIfGeneration, readOAuthRefreshIntent, writeOAuthRefreshIntent, markOAuthRefreshIntentStaleOwner, clearOAuthRefreshIntent, normalizeAuthStoreBuffer, OAuthMutationBusyError } from "./store";
 import { loginXai, refreshXaiToken, XAI_LOCAL_CLI_DETACH_WARNING, XaiTokenRequestError } from "./xai";
 import { ANTHROPIC_OAUTH_BETA, AnthropicTokenError, loginAnthropic, refreshAnthropicToken } from "./anthropic";
 import { loginKimi, refreshKimiToken } from "./kimi";
@@ -62,10 +62,9 @@ export interface OAuthAccessSnapshot {
   /**
    * Allowlisted GitHub Copilot API origin belonging to THIS account.
    *
-   * Copilot pins its bearer to an account-scoped regional host, and the initial route already
-   * pairs the two (`core.ts` resolves transport with `getOAuthCredentialApiBaseUrl`). Account
-   * failover must carry the pairing across the rotation; without it, account B's token is sent to
-   * account A's origin (#2568d).
+   * Copilot pins its bearer to an account-scoped regional host. Initial routing, 401 refresh, and
+   * account failover must resolve transport from this same snapshot; rereading the active account
+   * can pair account A's token with account B's origin during a concurrent switch (#2568d).
    */
   apiBaseUrl?: string;
 }
@@ -437,11 +436,18 @@ async function resolveAccessSnapshotForAccount(
   provider: string,
   accountId: string,
   rejectedGeneration?: string,
+  requireUsableAccount = false,
 ): Promise<OAuthAccessSnapshot> {
   const def = OAUTH_PROVIDERS[provider];
   if (!def) throw new UnsupportedOAuthProviderError(provider);
-  const cred = getAccountCredential(provider, accountId);
-  if (!cred) throw new OAuthLoginRequiredError(provider);
+  // One store read answers both questions. A caller that opts in gets the account REJECTED
+  // when it needs reauthentication, which a bare credential read cannot detect: a revoked
+  // account keeps a readable credential, so resolution would otherwise succeed and the
+  // request would dispatch on an account already known to need a fresh login.
+  const row = getAccountCredentialWithStatus(provider, accountId);
+  if (!row) throw new OAuthLoginRequiredError(provider);
+  if (requireUsableAccount && row.needsReauth) throw new OAuthLoginRequiredError(provider);
+  const cred = row.credential;
   const current = accessSnapshot(provider, accountId, cred);
   if (rejectedGeneration !== undefined && current.generation !== rejectedGeneration) return current;
   if (rejectedGeneration === undefined && cred.expires > Date.now() + REFRESH_SKEW_MS) return current;
@@ -530,8 +536,9 @@ export async function getValidAccessTokenForAccount(provider: string, accountId:
 export async function getValidAccessSnapshotForAccount(
   provider: string,
   accountId: string,
+  opts: { requireUsableAccount?: boolean } = {},
 ): Promise<OAuthAccessSnapshot> {
-  return resolveAccessSnapshotForAccount(provider, accountId);
+  return resolveAccessSnapshotForAccount(provider, accountId, undefined, opts.requireUsableAccount === true);
 }
 
 /** Terminal refresh failures (revoked/rotated-away grants) — retrying cannot succeed. */

package/src/oauth/store.ts

@@ -641,6 +641,22 @@ export function getAccountCredential(provider: string, accountId: string): OAuth
   return loadAuthStore()[provider]?.accounts.find(a => a.id === accountId)?.credential ?? null;
 }
 
+/**
+ * Credential plus the account's reauth flag, from ONE store read.
+ *
+ * A caller that checks `needsReauth` separately pays a second `loadAuthStore`, which
+ * chmods and re-parses the whole credential file. Returning both together lets an
+ * account-scoped resolver reject a revoked account without that extra read.
+ */
+export function getAccountCredentialWithStatus(
+  provider: string,
+  accountId: string,
+): { credential: OAuthCredentials; needsReauth: boolean } | null {
+  const account = loadAuthStore()[provider]?.accounts.find(a => a.id === accountId);
+  if (!account?.credential) return null;
+  return { credential: account.credential, needsReauth: account.needsReauth === true };
+}
+
 /** Persist a refreshed credential for a SPECIFIC account without touching activeAccountId. */
 export async function saveAccountCredential(
   provider: string,

package/src/providers/account-quota-disk.ts

@@ -0,0 +1,79 @@
+/**
+ * Last-known per-account provider quota, kept across restarts.
+ *
+ * The in-memory cache is process-local, so a restart forgets every measurement and the
+ * pool opens the next turn with no idea which account has room — exactly the state
+ * pre-dispatch selection exists to avoid. Codex solved this for its own pool with a small
+ * disk snapshot (`codex/quota.ts`), and this is the same shape for provider accounts.
+ *
+ * What is written is percentages and reset timestamps. No token, no email, no account
+ * label — the account id is the store's own opaque id, which is already what keys the
+ * in-memory cache.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile, getConfigDir } from "../config";
+import type { ProviderQuota } from "./quota-types";
+
+const FILENAME = "provider-account-quota-cache.json";
+
+/**
+ * Older than this and the snapshot is discarded on load.
+ *
+ * Six hours matches the Codex cache. A stale bar is still better than none for ORDERING —
+ * it decides which account to try first, and a wrong guess costs one 429 that rotation
+ * already handles — but a day-old reading of a monthly window has drifted far enough that
+ * it should not outrank a fresh probe.
+ */
+const DISK_MAX_AGE_MS = 6 * 60 * 60_000;
+const PERSIST_DEBOUNCE_MS = 250;
+
+type DiskFile = {
+  version: 1;
+  /** provider\u0000accountId -> quota, the same key the in-memory cache uses. */
+  rows: Record<string, ProviderQuota>;
+};
+
+let persistTimer: ReturnType<typeof setTimeout> | null = null;
+
+/** Read the snapshot. Returns an empty map for a missing, corrupt or stale file. */
+export function readPersistedAccountQuotas(now = Date.now()): Map<string, ProviderQuota> {
+  const rows = new Map<string, ProviderQuota>();
+  try {
+    const path = join(getConfigDir(), FILENAME);
+    if (!existsSync(path)) return rows;
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as DiskFile;
+    if (!parsed || parsed.version !== 1 || !parsed.rows || typeof parsed.rows !== "object") return rows;
+    for (const [key, quota] of Object.entries(parsed.rows)) {
+      if (!quota || typeof quota !== "object" || typeof quota.updatedAt !== "number") continue;
+      if (now - quota.updatedAt > DISK_MAX_AGE_MS) continue;
+      rows.set(key, quota);
+    }
+  } catch {
+    // A corrupt cache must never block routing or the dashboard.
+  }
+  return rows;
+}
+
+/** Write the snapshot, debounced. Best-effort: a failed write is not an error. */
+export function schedulePersistAccountQuotas(rows: () => Iterable<[string, ProviderQuota]>): void {
+  if (persistTimer) clearTimeout(persistTimer);
+  persistTimer = setTimeout(() => {
+    persistTimer = null;
+    try {
+      const out: Record<string, ProviderQuota> = {};
+      for (const [key, quota] of rows()) out[key] = quota;
+      const body: DiskFile = { version: 1, rows: out };
+      atomicWriteFile(join(getConfigDir(), FILENAME), `${JSON.stringify(body)}\n`);
+    } catch {
+      // Best-effort persistence only.
+    }
+  }, PERSIST_DEBOUNCE_MS);
+}
+
+/** Test seam: drop any pending write so a suite cannot leak one into the next file. */
+export function cancelPendingAccountQuotaPersist(): void {
+  if (!persistTimer) return;
+  clearTimeout(persistTimer);
+  persistTimer = null;
+}

package/src/providers/command-code-efforts.ts

@@ -73,6 +73,30 @@ const COMMAND_CODE_MODEL_EFFORTS = {
     efforts: ["low", "high", "max"],
     profileUrl: "https://commandcode.ai/models/glm-5-3",
   },
+  /*
+   * GLM-5.3-Flash (#2883). Reported as advertising NO efforts at all: the live
+   * route is `z-ai/glm-5.3-flash`, which shares neither vendor prefix nor model
+   * id with `zai-org/GLM-5.3` above, so `modelRecordValue` cannot bridge them
+   * (exact / colon-family / case-folded only — by design; a substring match here
+   * would merge two genuinely different models across two vendor namespaces).
+   *
+   * PROVENANCE: unlike the #2647 rows above, this ladder is MEASURED, not
+   * reported. commandcode.ai renders the profile client-side, but the delivered
+   * HTML ships a serialized React payload whose string table can be read
+   * directly: in the 2026-08-29 fetch of /models/glm-5-3-flash (HTTP 200,
+   * 228749 bytes) the indices resolve as 224=low, 225=medium, 226=high,
+   * 227=xhigh, 569=max, and this model's array is [224,226,569].
+   *
+   * The index map was cross-validated against every row in this table that the
+   * same page carries: deepseek-v4-pro and -flash [226,569], gpt-5.6-luna
+   * [224,225,226,227,569], gemini-3.7-flash [224,225,226], GLM-5.2 [226,569],
+   * GLM-5.3 [224,226,569] — six for six against the values already committed
+   * here. No authenticated upstream generate probe was performed.
+   */
+  "z-ai/glm-5.3-flash": {
+    efforts: ["low", "high", "max"],
+    profileUrl: "https://commandcode.ai/models/glm-5-3-flash",
+  },
   // Muse Spark: CLI currently prints "has no adjustable reasoning effort" and
   // blocks --effort locally, but the upstream /alpha/generate endpoint accepts
   // reasoning_effort low..max for meta/muse-spark-1.2-contributor (verified

package/src/providers/derive.ts

@@ -254,6 +254,9 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.requiresAdjacentResponsesToolResults !== undefined
       ? { requiresAdjacentResponsesToolResults: entry.requiresAdjacentResponsesToolResults }
       : {}),
+    ...(entry.annotateEmptyToolOutputs !== undefined
+      ? { annotateEmptyToolOutputs: entry.annotateEmptyToolOutputs }
+      : {}),
     ...(entry.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...entry.autoToolChoiceOnlyModels] } : {}),
     ...(entry.preserveReasoningContentModels ? { preserveReasoningContentModels: [...entry.preserveReasoningContentModels] } : {}),
     ...(entry.requiresReasoningPlaceholderModels ? { requiresReasoningPlaceholderModels: [...entry.requiresReasoningPlaceholderModels] } : {}),
@@ -501,6 +504,9 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (prov.requiresAdjacentResponsesToolResults === undefined && seed.requiresAdjacentResponsesToolResults !== undefined) {
     prov.requiresAdjacentResponsesToolResults = seed.requiresAdjacentResponsesToolResults;
   }
+  if (prov.annotateEmptyToolOutputs === undefined && seed.annotateEmptyToolOutputs !== undefined) {
+    prov.annotateEmptyToolOutputs = seed.annotateEmptyToolOutputs;
+  }
   // Registry-only metadata (never seeded into saved config): backfill straight from
   // the entry so an explicit user value stays distinguishable from the default.
   if (prov.fastWire === undefined && entry.fastWire !== undefined) {

package/src/providers/key-failover.ts

@@ -9,7 +9,7 @@
  * Modelled after src/codex/routing.ts cooldown logic but scoped to plain API-key pools.
  */
 import { saveConfigPreservingClaudeCode } from "../config";
-import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy } from "../types";
+import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy, TransientRetryPolicy } from "../types";
 import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 
@@ -34,6 +34,15 @@ const DEFAULT_RATE_LIMIT_RETRY = {
   respectRetryAfter: true,
 } as const satisfies Required<RateLimitRetryPolicy>;
 
+/**
+ * Default transient-5xx retry used when a provider opts in with a bare
+ * `transientRetryOn5xx: {}`. `attempts` is a TOTAL send budget, not extra retries.
+ */
+const DEFAULT_TRANSIENT_RETRY = {
+  enabled: true,
+  attempts: 3,
+} as const satisfies Required<TransientRetryPolicy>;
+
 /** Map<`${providerName}\0${keyId}`, KeyCooldown> */
 const keyCooldowns = new Map<string, KeyCooldown>();
 
@@ -114,6 +123,29 @@ export function rateLimitRetryPolicyFor(
   };
 }
 
+/**
+ * Normalize a provider's `transientRetryOn5xx` policy, or return null when it is absent,
+ * explicitly disabled, not key-auth, or not the `openai-chat` adapter.
+ *
+ * The adapter gate is part of the accepted scope, not incidental: this first version covers
+ * key-auth `openai-chat` only, and without an explicit check any generic key-auth adapter
+ * could opt in. Auth mode follows the same fail-closed rule as `rateLimitRetryPolicyFor` —
+ * explicit `key` or the documented omitted default, never OAuth, forward, local, or an
+ * unknown value.
+ */
+export function transientRetryPolicyFor(
+  provider: Pick<OcxProviderConfig, "transientRetryOn5xx" | "authMode" | "adapter">,
+): Required<TransientRetryPolicy> | null {
+  const policy = provider.transientRetryOn5xx;
+  if (!policy || policy.enabled === false) return null;
+  if (provider.adapter !== "openai-chat") return null;
+  if (provider.authMode !== undefined && provider.authMode !== "key") return null;
+  return {
+    enabled: policy.enabled ?? DEFAULT_TRANSIENT_RETRY.enabled,
+    attempts: policy.attempts ?? DEFAULT_TRANSIENT_RETRY.attempts,
+  };
+}
+
 /**
  * Wait before the next same-target replay: upstream Retry-After (seconds or HTTP-date) when
  * `respectRetryAfter` is on and the header parses, capped at `maxIntervalMs`; otherwise the