@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/providers/model-rename-startup.ts

@@ -1,10 +1,47 @@
-import { saveConfig } from "../config";
+import { mutatePersistedConfig } from "../config";
 import { projectModelRenames } from "./model-rename-migration";
 import type { OcxConfig } from "../types";
 
 export interface ModelRenameStartupDeps {
   project: typeof projectModelRenames;
-  save: (config: OcxConfig) => void;
+  /** Injected writer for tests and callers that own their own persistence. */
+  save?: (config: OcxConfig) => void;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Recursive key-by-key adopt: descend into a changed container, replace only changed leaves. */
+function adoptRecord(live: Record<string, unknown>, next: Record<string, unknown>): void {
+  for (const key of Object.keys(live)) {
+    if (!(key in next)) delete live[key];
+  }
+  for (const [key, value] of Object.entries(next)) {
+    const current = live[key];
+    if (JSON.stringify(current) === JSON.stringify(value)) continue;
+    if (isPlainObject(current) && isPlainObject(value)) {
+      adoptRecord(current, value);
+      continue;
+    }
+    live[key] = value;
+  }
+}
+
+/**
+ * Copy `source` onto `target` in place, touching only the keys that actually differ.
+ *
+ * A clear-and-reassign preserves the top-level object identity while silently detaching every
+ * nested sub-object a caller still holds a live reference to. The renames rewrite one provider
+ * row at a time, so every sibling row — and the `providers` container itself — must survive
+ * with its identity intact.
+ */
+function adoptConfig(target: OcxConfig, source: OcxConfig): void {
+  if (target === source) return;
+  adoptRecord(
+    target as unknown as Record<string, unknown>,
+    structuredClone(source) as unknown as Record<string, unknown>,
+  );
 }
 
 /**
@@ -15,14 +52,41 @@ export interface ModelRenameStartupDeps {
  * recoverable from the config alone. This one only rewrites model ids that the
  * registry itself no longer seeds, and the pre-migration value is a string this
  * file still names, so the change is reversible by hand.
+ *
+ * Persistence failure is not fatal. This runs inside `startServer`, so a missing, malformed or
+ * contended config degrades to a warning plus the in-memory projection rather than taking the
+ * boot path down.
  */
 export function runModelRenameStartupMigration(
   config: OcxConfig,
-  deps: ModelRenameStartupDeps = { project: projectModelRenames, save: saveConfig },
+  deps: ModelRenameStartupDeps = { project: projectModelRenames },
 ): OcxConfig {
-  const projection = deps.project(config);
-  for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
-  if (!projection.changed) return projection.config;
-  deps.save(projection.config);
-  return projection.config;
+  const projection = deps.project(structuredClone(config));
+  if (!projection.changed) {
+    for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+    return config;
+  }
+  if (deps.save) {
+    deps.save(projection.config);
+    adoptConfig(config, projection.config);
+    for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+    return config;
+  }
+  const outcome = mutatePersistedConfig(fresh => {
+    const next = deps.project(fresh);
+    if (next.changed) adoptConfig(fresh, next.config);
+    return { changed: next.changed, value: next };
+  });
+  if (outcome.status === "unavailable") {
+    console.warn(
+      `[model-rename-migration] persistence unavailable (${outcome.reason}); applying the renames `
+      + "in memory for this run only.",
+    );
+    adoptConfig(config, projection.config);
+    for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+    return config;
+  }
+  adoptConfig(config, outcome.value.config);
+  for (const warning of outcome.value.warnings) console.warn(`[model-rename-migration] ${warning}`);
+  return config;
 }

package/src/providers/openai-sidecar.ts

@@ -7,10 +7,11 @@ import {
   resolveCodexAuthContext,
   type CodexAccountSelectionAdmission,
   type CodexAuthContext,
+  type CodexAuthPolicyConfig,
 } from "../codex/auth-context";
 import { recordCodexUpstreamOutcome, type CodexUpstreamOutcome } from "../codex/routing";
 import { extractAccountId } from "../oauth/chatgpt";
-import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "../server/auth-cors";
+import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "../server/auth-cors";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import {
   CODEX_FORWARD_BASE_URL,
@@ -78,6 +79,8 @@ export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiFor
 
 function directSidecarHeaders(
   incomingHeaders: Headers,
+  config: CodexAuthPolicyConfig,
+  admission?: Pick<DataPlaneAdmission, "source">,
 ): Headers | undefined {
   const bearer = incomingHeaders.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
   if (!bearer) return undefined;
@@ -89,7 +92,7 @@ function directSidecarHeaders(
   // intentional ChatGPT-auth operation instead of silently reclassifying any JWT-shaped
   // provider credential as a Codex bearer.
   if (!requestedAccountId || requestedAccountId !== derivedAccountId) return undefined;
-  const selected = headersForCodexAuthContext(incomingHeaders, { kind: "main", accountId: null });
+  const selected = headersForCodexAuthContext(incomingHeaders, { kind: "main", accountId: null }, config, undefined, admission);
   return selected;
 }
 
@@ -99,10 +102,13 @@ export async function resolveFirstUsableOpenAiSidecar(
   config: OcxConfig,
   options: {
     exactAccount?: ExactOpenAiSidecarAccount;
+    admission?: Pick<DataPlaneAdmission, "source">;
+    codexAuthPolicy?: CodexAuthPolicyConfig;
     beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
   } = {},
 ): Promise<ResolvedOpenAiForwardSidecar | undefined> {
   const { exactAccount } = options;
+  const policy = options.codexAuthPolicy ?? config;
   let callerBearerMayBeForwarded = true;
   try {
     validateForwardAdmissionCredential(incomingHeaders, config);
@@ -116,10 +122,13 @@ export async function resolveFirstUsableOpenAiSidecar(
       // credential directly even when the provider is globally Direct, and never
       // consult Pool active state, affinity, probes, or alternates.
       const authContext = await resolveCodexAuthContext(incomingHeaders, config, "pool", {
+        codexAuthPolicy: policy,
         accountId: exactAccount.accountId,
         modelId: exactAccount.modelId,
+        admission: options.admission,
         beginCodexAccountSelection: options.beginCodexAccountSelection,
       });
+      const selectedHeaders = headersForCodexAuthContext(incomingHeaders, authContext, policy, exactAccount.modelId, options.admission);
       if ((authContext.kind !== "pool" && authContext.kind !== "main-pool")
         || !isCodexAuthContextUsable(authContext, config)) {
         // Exact selection is fail-closed. A generation/runtime-state race must not fall through
@@ -129,7 +138,7 @@ export async function resolveFirstUsableOpenAiSidecar(
       return {
         ...candidate,
         authContext,
-        headers: headersForCodexAuthContext(incomingHeaders, authContext),
+        headers: selectedHeaders,
         recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
           config,
           authContext.accountId,
@@ -149,7 +158,7 @@ export async function resolveFirstUsableOpenAiSidecar(
     }
     if (candidate.accountMode === "direct") {
       if (!callerBearerMayBeForwarded || !hasCallerCodexBearer(incomingHeaders)) continue;
-      const headers = directSidecarHeaders(incomingHeaders);
+      const headers = directSidecarHeaders(incomingHeaders, policy, options.admission);
       if (!headers) continue;
       return {
         ...candidate,
@@ -158,13 +167,16 @@ export async function resolveFirstUsableOpenAiSidecar(
       };
     }
     const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode, {
+      codexAuthPolicy: policy,
+      admission: options.admission,
       beginCodexAccountSelection: options.beginCodexAccountSelection,
     });
+    const selectedHeaders = headersForCodexAuthContext(incomingHeaders, authContext, policy, undefined, options.admission);
     if (!isCodexAuthContextUsable(authContext, config)) continue;
     return {
       ...candidate,
       authContext,
-      headers: headersForCodexAuthContext(incomingHeaders, authContext),
+      headers: selectedHeaders,
       ...(authContext.kind === "pool" || authContext.kind === "main-pool"
         ? {
           recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(

package/src/providers/openai-tiers-destination.ts

@@ -0,0 +1,102 @@
+import type { OcxProviderConfig } from "../types";
+import { openaiResponsesUrl } from "../adapters/openai-responses-url";
+
+export const OPENAI_CODEX_PROVIDER_ID = "openai";
+export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
+export const OPENAI_API_PROVIDER_ID = "openai-apikey";
+export const LEGACY_CHATGPT_PROVIDER_ID = "chatgpt";
+
+export const CODEX_FORWARD_BASE_URL = "https://chatgpt.com/backend-api/codex";
+
+function normalizedBaseUrl(value: string): string | undefined {
+  try {
+    const url = new URL(value.trim());
+    if (url.username || url.password || url.search || url.hash) return undefined;
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${path}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): boolean {
+  return provider.adapter === "openai-responses"
+    && provider.authMode === "forward"
+    && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
+}
+
+const OPENAI_API_ORIGIN = "https://api.openai.com";
+const OPENAI_API_BASE_URL = `${OPENAI_API_ORIGIN}/v1`;
+const OPENAI_API_RESPONSES_URL = `${OPENAI_API_BASE_URL}/responses`;
+
+/**
+ * The Responses endpoint the adapter would actually POST key-auth traffic to, normalized.
+ *
+ * Mirrors the adapter's own construction (`src/adapters/openai-responses.ts`): a configured
+ * `responsesPath` is appended to the base verbatim, and only the default branch runs the
+ * `/v1/responses` suffix normalization. Classifying on the base URL alone would call
+ * `baseUrl: "https://api.openai.com"` with `responsesPath: "/other"` official even though that
+ * request never reaches the official Responses endpoint.
+ */
+function resolvedResponsesEndpoint(provider: OcxProviderConfig): string | undefined {
+  try {
+    const raw = provider.responsesPath === undefined
+      ? openaiResponsesUrl(provider.baseUrl)
+      : `${provider.baseUrl.replace(/\/$/, "")}${provider.responsesPath}`;
+    return normalizedBaseUrl(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function isOfficialOpenAiResponsesDestination(provider: OcxProviderConfig): boolean {
+  // Exact normalized URL keeps lookalike/suffix hosts out of this set: `api.openai.com.evil.test`
+  // resolves to its own origin, never to the official one.
+  return resolvedResponsesEndpoint(provider) === OPENAI_API_RESPONSES_URL;
+}
+
+/**
+ * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
+ * backend can, and so can the official OpenAI API — but an arbitrary gateway that
+ * merely speaks the Responses wire cannot, and calling it there fails compaction
+ * with an unhelpful error instead of falling back to a routed summary (#422).
+ */
+export function supportsNativeResponsesCompactEndpoint(
+  providerName: string,
+  provider: OcxProviderConfig,
+): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return providerName === OPENAI_API_PROVIDER_ID
+    && provider.adapter === "openai-responses"
+    && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
+}
+
+/**
+ * Whether this destination is an OpenAI-operated Responses backend — the canonical ChatGPT Codex
+ * surface or the official OpenAI API.
+ *
+ * Deliberately not keyed on `authMode === "forward"`: a noncanonical forward provider does not
+ * receive the caller's credentials (see the forward-header gate in the Responses adapter), so
+ * forward auth says nothing about which backend is on the other end.
+ */
+export function isOpenAiOperatedResponsesDestination(provider: OcxProviderConfig): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return provider.adapter === "openai-responses"
+    && isOfficialOpenAiResponsesDestination(provider);
+}
+
+/**
+ * Whether this destination can decode a native (non-`ocx1:`) compaction blob.
+ *
+ * Only the backend that minted a blob can decode it. `authMode: "forward"` alone is not a signal:
+ * the adapter forwards caller credentials only to the canonical ChatGPT Codex surface, while a
+ * noncanonical forward provider receives no caller credentials and may point at any backend.
+ *
+ * Relay only to an OpenAI-operated destination or a destination whose operator explicitly opts in.
+ * Keyed by destination rather than provider id: a blob's issuer is the URL that produced it, not the
+ * local config key a replay travels under.
+ */
+export function destinationDecodesNativeCompactionBlob(provider: OcxProviderConfig): boolean {
+  return isOpenAiOperatedResponsesDestination(provider)
+    || provider.decodesNativeCompactionBlobs === true;
+}

package/src/providers/openai-tiers.ts

@@ -2,13 +2,9 @@ import type { CodexAccountMode, OcxConfig, OcxProviderConfig, ProviderCostOverla
 import { OPENAI_PROVIDER_TIER_VERSION } from "../types";
 import { openaiResponsesUrl } from "../adapters/openai-responses-url";
 import { MAX_COST4_RATE } from "../usage/expected-prices";
+import { OPENAI_CODEX_PROVIDER_ID, LEGACY_OPENAI_MULTI_PROVIDER_ID, LEGACY_CHATGPT_PROVIDER_ID, CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "./openai-tiers-destination";
+export { OPENAI_CODEX_PROVIDER_ID, LEGACY_OPENAI_MULTI_PROVIDER_ID, OPENAI_API_PROVIDER_ID, LEGACY_CHATGPT_PROVIDER_ID, CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider, supportsNativeResponsesCompactEndpoint, isOpenAiOperatedResponsesDestination, destinationDecodesNativeCompactionBlob } from "./openai-tiers-destination";
 
-export const OPENAI_CODEX_PROVIDER_ID = "openai";
-export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
-export const OPENAI_API_PROVIDER_ID = "openai-apikey";
-export const LEGACY_CHATGPT_PROVIDER_ID = "chatgpt";
-
-export const CODEX_FORWARD_BASE_URL = "https://chatgpt.com/backend-api/codex";
 const LEGACY_OPENAI_MULTI_PREFIX = `${LEGACY_OPENAI_MULTI_PROVIDER_ID}/`;
 
 function canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfig {
@@ -20,99 +16,6 @@ function canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfi
   };
 }
 
-function normalizedBaseUrl(value: string): string | undefined {
-  try {
-    const url = new URL(value.trim());
-    if (url.username || url.password || url.search || url.hash) return undefined;
-    const path = url.pathname.replace(/\/+$/, "");
-    return `${url.origin}${path}`;
-  } catch {
-    return undefined;
-  }
-}
-
-export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): boolean {
-  return provider.adapter === "openai-responses"
-    && provider.authMode === "forward"
-    && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
-}
-
-const OPENAI_API_ORIGIN = "https://api.openai.com";
-const OPENAI_API_BASE_URL = `${OPENAI_API_ORIGIN}/v1`;
-const OPENAI_API_RESPONSES_URL = `${OPENAI_API_BASE_URL}/responses`;
-
-/**
- * The Responses endpoint the adapter would actually POST key-auth traffic to, normalized.
- *
- * Mirrors the adapter's own construction (`src/adapters/openai-responses.ts`): a configured
- * `responsesPath` is appended to the base verbatim, and only the default branch runs the
- * `/v1/responses` suffix normalization. Classifying on the base URL alone would call
- * `baseUrl: "https://api.openai.com"` with `responsesPath: "/other"` official even though that
- * request never reaches the official Responses endpoint.
- */
-function resolvedResponsesEndpoint(provider: OcxProviderConfig): string | undefined {
-  try {
-    const raw = provider.responsesPath === undefined
-      ? openaiResponsesUrl(provider.baseUrl)
-      : `${provider.baseUrl.replace(/\/$/, "")}${provider.responsesPath}`;
-    return normalizedBaseUrl(raw);
-  } catch {
-    return undefined;
-  }
-}
-
-function isOfficialOpenAiResponsesDestination(provider: OcxProviderConfig): boolean {
-  // Exact normalized URL keeps lookalike/suffix hosts out of this set: `api.openai.com.evil.test`
-  // resolves to its own origin, never to the official one.
-  return resolvedResponsesEndpoint(provider) === OPENAI_API_RESPONSES_URL;
-}
-
-/**
- * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
- * backend can, and so can the official OpenAI API — but an arbitrary gateway that
- * merely speaks the Responses wire cannot, and calling it there fails compaction
- * with an unhelpful error instead of falling back to a routed summary (#422).
- */
-export function supportsNativeResponsesCompactEndpoint(
-  providerName: string,
-  provider: OcxProviderConfig,
-): boolean {
-  if (isCanonicalOpenAiForwardProvider(provider)) return true;
-  return providerName === OPENAI_API_PROVIDER_ID
-    && provider.adapter === "openai-responses"
-    && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
-}
-
-/**
- * Whether this destination is an OpenAI-operated Responses backend — the canonical ChatGPT Codex
- * surface or the official OpenAI API.
- *
- * Deliberately not keyed on `authMode === "forward"`: a noncanonical forward provider does not
- * receive the caller's credentials (see the forward-header gate in the Responses adapter), so
- * forward auth says nothing about which backend is on the other end.
- */
-export function isOpenAiOperatedResponsesDestination(provider: OcxProviderConfig): boolean {
-  if (isCanonicalOpenAiForwardProvider(provider)) return true;
-  return provider.adapter === "openai-responses"
-    && isOfficialOpenAiResponsesDestination(provider);
-}
-
-/**
- * Whether this destination can decode a native (non-`ocx1:`) compaction blob.
- *
- * Only the backend that minted a blob can decode it. `authMode: "forward"` alone is not a signal:
- * the adapter forwards caller credentials only to the canonical ChatGPT Codex surface, while a
- * noncanonical forward provider receives no caller credentials and may point at any backend.
- *
- * Relay only to an OpenAI-operated destination or a destination whose operator explicitly opts in.
- * Keyed by destination rather than provider id: a blob's issuer is the URL that produced it, not the
- * local config key a replay travels under.
- */
-export function destinationDecodesNativeCompactionBlob(provider: OcxProviderConfig): boolean {
-  return isOpenAiOperatedResponsesDestination(provider)
-    || provider.decodesNativeCompactionBlobs === true;
-}
-
 export interface OpenAiTierMigrationProjection {
   config: OcxConfig;
   changed: boolean;

package/src/providers/opencode-go-transport.ts

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import type { OcxProviderConfig } from "../types";
+import { registryEntryForProviderDestination } from "./registry";
+
+export const OPENCODE_GO_SESSION_HEADER = "x-opencode-session";
+
+function hasHeaderCaseInsensitive(
+  headers: Record<string, string> | undefined,
+  name: string,
+): boolean {
+  const target = name.toLowerCase();
+  return Object.keys(headers ?? {}).some(key => key.toLowerCase() === target);
+}
+
+/** Derive a provider-scoped opaque value without exposing Codex task or subagent ids. */
+export function deriveOpenCodeGoSessionId(sessionLane: string): string {
+  const digest = createHash("sha256")
+    .update("opencodex/opencode-go/session/v1\0")
+    .update(sessionLane)
+    .digest("hex")
+    .slice(0, 32);
+  return `ocx_${digest}`;
+}
+
+/** Add per-conversation Go affinity only to the canonical fixed-key destination. */
+export function resolveOpenCodeGoTransport<T extends OcxProviderConfig>(
+  provider: T,
+  sessionLane: string | undefined,
+): T {
+  if (registryEntryForProviderDestination(provider)?.id !== "opencode-go") return provider;
+  if (!sessionLane) return provider;
+  if (hasHeaderCaseInsensitive(provider.headers, OPENCODE_GO_SESSION_HEADER)) return provider;
+
+  return {
+    ...provider,
+    headers: {
+      ...(provider.headers ?? {}),
+      [OPENCODE_GO_SESSION_HEADER]: deriveOpenCodeGoSessionId(sessionLane),
+    },
+  };
+}

package/src/providers/quota-key-accounts.ts

@@ -0,0 +1,141 @@
+/** Isolated, process-local API-key quota rows. Never publishes provider/routing caches. */
+import { createHash } from "node:crypto";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { apiKeyPoolEntryId } from "./api-keys";
+import { resolveProviderApiKey } from "./key-store";
+import type { ProviderQuota } from "./quota-types";
+import { ACCOUNT_QUOTA_TTL_MS } from "./quota-wire";
+
+const MAX_ENTRIES = 256;
+const LAST_GOOD_MS = 30 * 60_000;
+type Entry = { ts: number; quota: ProviderQuota | null; unavailable?: true };
+export type KeyQuotaProbeOutcome =
+  | { kind: "quota"; quota: ProviderQuota }
+  | { kind: "empty" | "terminal" | "unavailable" };
+export interface ProviderApiKeyQuota {
+  keyId: string;
+  quota: ProviderQuota | null;
+  unavailable?: true;
+  /** Server-only, non-enumerable; call immediately before the safe DTO join. */
+  isCurrent: () => boolean;
+}
+const cache = new Map<string, Entry>();
+const flights = new Map<string, Promise<Entry>>();
+let epoch = 0;
+
+export function clearProviderApiKeyQuotaCache(): void {
+  epoch += 1;
+  cache.clear();
+  flights.clear();
+}
+
+/** Four workers per roster, not a process-wide network limit. */
+export async function mapQuotaRoster<T, R>(rows: readonly T[], read: (row: T) => Promise<R>): Promise<R[]> {
+  const out = new Array<R>(rows.length);
+  let cursor = 0;
+  await Promise.all(Array.from({ length: Math.min(4, rows.length) }, async () => {
+    while (cursor < rows.length) {
+      const index = cursor++;
+      out[index] = await read(rows[index]!);
+    }
+  }));
+  return out;
+}
+
+function roster(provider: OcxProviderConfig) {
+  return provider.apiKeyPool?.length ? provider.apiKeyPool
+    : provider.apiKey ? [{ id: apiKeyPoolEntryId(provider.apiKey), key: provider.apiKey }] : [];
+}
+
+function identity(name: string, provider: OcxProviderConfig, id: string, key: string): string {
+  return createHash("sha256").update(JSON.stringify([
+    "quota-key", name, provider.adapter, provider.baseUrl, provider.authMode ?? "key",
+    provider.disabled === true, id, key,
+  ])).digest("hex");
+}
+
+function remember(key: string, entry: Entry): void {
+  cache.delete(key);
+  for (const [id, row] of cache) if (Date.now() - row.ts >= LAST_GOOD_MS) cache.delete(id);
+  while (cache.size >= MAX_ENTRIES) cache.delete(cache.keys().next().value!);
+  cache.set(key, entry);
+}
+
+async function readEntry(
+  key: string,
+  force: boolean,
+  isCurrent: () => boolean,
+  probe: () => Promise<KeyQuotaProbeOutcome>,
+): Promise<Entry> {
+  const previous = cache.get(key);
+  if (!force && previous && Date.now() - previous.ts < ACCOUNT_QUOTA_TTL_MS
+    && (!previous.quota || Date.now() - previous.quota.updatedAt < LAST_GOOD_MS)) {
+    cache.delete(key);
+    cache.set(key, previous);
+    return previous;
+  }
+  const running = flights.get(key);
+  if (running) return running;
+  const lastGood = previous?.quota && Date.now() - previous.quota.updatedAt < LAST_GOOD_MS
+    ? previous.quota : null;
+  if (flights.size >= MAX_ENTRIES) return { ts: Date.now(), quota: lastGood, unavailable: true };
+  const flight = (async (): Promise<Entry> => {
+    let result: KeyQuotaProbeOutcome;
+    try { result = await probe(); } catch { result = { kind: "unavailable" }; }
+    const entry: Entry = result.kind === "quota"
+      ? { ts: Date.now(), quota: result.quota }
+      : result.kind === "empty"
+        ? { ts: Date.now(), quota: null }
+        : {
+            ts: Date.now(),
+            quota: result.kind !== "terminal" && lastGood && Date.now() - lastGood.updatedAt < LAST_GOOD_MS ? lastGood : null,
+            unavailable: true,
+          };
+    if (isCurrent()) remember(key, entry);
+    return entry;
+  })().finally(() => { if (flights.get(key) === flight) flights.delete(key); });
+  flights.set(key, flight);
+  return flight;
+}
+
+export async function readProviderApiKeyQuotas(
+  config: OcxConfig,
+  name: string,
+  force: boolean,
+  probe: (provider: OcxProviderConfig, config: OcxConfig) => Promise<KeyQuotaProbeOutcome>,
+): Promise<ProviderApiKeyQuota[]> {
+  const liveProvider = config.providers[name];
+  if (!liveProvider) return [];
+  const providerSnapshot = { ...liveProvider };
+  const rows = roster(liveProvider).map(row => ({ ...row }));
+  const generation = epoch;
+  return mapQuotaRoster(rows, async row => {
+    let resolved: string | undefined;
+    try { resolved = resolveProviderApiKey(row.key)?.trim(); } catch { /* unavailable */ }
+    const key = resolved ? identity(name, providerSnapshot, row.id, resolved) : null;
+    const isCurrent = () => {
+      if (epoch !== generation || !key) return false;
+      const current = config.providers[name];
+      if (!current) return false;
+      const entry = roster(current).find(candidate => candidate.id === row.id);
+      if (!entry) return false;
+      try {
+        const currentKey = resolveProviderApiKey(entry.key)?.trim();
+        return !!currentKey && identity(name, current, row.id, currentKey) === key;
+      } catch { return false; }
+    };
+    const entry = key && resolved && isCurrent()
+      ? await readEntry(key, force, isCurrent, () => {
+          const isolatedProvider = { ...providerSnapshot, apiKey: resolved, apiKeyPool: undefined };
+          const isolatedConfig = { ...config, providers: { [name]: isolatedProvider } };
+          return probe(isolatedProvider, isolatedConfig);
+        })
+      : { ts: Date.now(), quota: null, unavailable: true as const };
+    const result = {
+      keyId: row.id,
+      quota: isCurrent() ? entry.quota : null,
+      ...(!isCurrent() || entry.unavailable ? { unavailable: true as const } : {}),
+    };
+    return Object.defineProperty(result, "isCurrent", { value: isCurrent }) as ProviderApiKeyQuota;
+  });
+}

package/src/providers/quota-types.ts

@@ -34,3 +34,12 @@ export interface ProviderQuota {
   creditsUsd?: ProviderQuotaCreditsUsd;
   updatedAt: number;
 }
+
+export type AccountQuotaMode = "probe" | "passive" | "unsupported";
+
+/** Additive management-row fields; cheap lists emit only quotaMode. */
+export interface AccountQuotaFields {
+  quotaMode?: AccountQuotaMode;
+  quota?: ProviderQuota | null;
+  quotaUnavailable?: boolean;
+}