@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/providers/quota/antigravity.ts

@@ -0,0 +1,295 @@
+import { antigravityUserAgent } from "../../adapters/client-fingerprint";
+import { DestinationDnsResolutionError } from "../../lib/destination-policy";
+import { PinnedHttpError } from "../../lib/pinned-http";
+import { ProviderOutboundPolicyError, providerOutboundPost, providerRedirectError, type ProviderOutboundDependencies } from "../../lib/provider-outbound";
+import { getValidAccessToken } from "../../oauth";
+import { getAccountCredential, getCredential } from "../../oauth/store";
+import { asRecord, normalizePercent, normalizeResetAt, readQuotaJson, REQUEST_TIMEOUT_MS, toFiniteNumber } from "../quota-wire";
+import { report, type ProviderQuotaReport } from "./report-cache";
+import { quotaCredentialIdentity } from "./account-cache";
+import type { ProviderQuota, ProviderQuotaWindow, QuotaFailureCode } from "../quota-types";
+
+export function antigravityQuotaDiagnosticIdentity(accountId: string, credential = getAccountCredential("google-antigravity", accountId)): string | undefined {
+  return credential ? quotaCredentialIdentity("google-antigravity", accountId, credential, {
+    adapter: "google", baseUrl: ANTIGRAVITY_ACCOUNT_QUOTA_BASE, authMode: "oauth",
+  }) : undefined;
+}
+
+
+function quotaInfoEntries(modelInfo: Record<string, unknown>): Record<string, unknown>[] {
+  const entries: Record<string, unknown>[] = [];
+  const add = (value: unknown, tier?: string) => {
+    const rec = asRecord(value);
+    if (!rec) return;
+    entries.push(tier ? { ...rec, tier } : rec);
+  };
+  const addArray = (value: unknown) => {
+    if (!Array.isArray(value)) return;
+    for (const entry of value) add(entry);
+  };
+
+  if (Array.isArray(modelInfo.quotaInfo)) addArray(modelInfo.quotaInfo);
+  else add(modelInfo.quotaInfo);
+  addArray(modelInfo.quotaInfos);
+
+  const byTier = asRecord(modelInfo.quotaInfoByTier);
+  if (byTier) {
+    for (const [tier, value] of Object.entries(byTier)) {
+      if (Array.isArray(value)) {
+        for (const entry of value) add(entry, tier);
+      } else {
+        add(value, tier);
+      }
+    }
+  }
+  return entries;
+}
+
+function classifyAntigravityFamily(modelId: string, modelInfo: Record<string, unknown>, quotaInfo: Record<string, unknown>): "Gem" | "Cla" | null {
+  const displayName = typeof modelInfo.displayName === "string" ? modelInfo.displayName : "";
+  const tier = typeof quotaInfo.tier === "string" ? quotaInfo.tier : "";
+  const haystack = `${modelId} ${displayName} ${tier}`.toLowerCase();
+  if (haystack.includes("gemini")) return "Gem";
+  if (haystack.includes("claude") || haystack.includes("opus") || haystack.includes("sonnet") || haystack.includes("gpt-oss") || haystack.includes("gpt_oss")) return "Cla";
+  return null;
+}
+
+function antigravityUsedPercent(quotaInfo: Record<string, unknown>): number | undefined {
+  const target = asRecord(quotaInfo.remaining) ?? quotaInfo;
+  const remaining = normalizePercent(toFiniteNumber(target.remainingFraction) !== undefined
+    ? toFiniteNumber(target.remainingFraction)! * 100
+    : toFiniteNumber(target.remainingPercentage) !== undefined
+      ? toFiniteNumber(target.remainingPercentage)! * 100
+      : undefined);
+  if (remaining === undefined) return undefined;
+  return normalizePercent(100 - remaining);
+}
+
+/** Gem/Cla windows from a `fetchAvailableModels` body; shared by the provider and account probes. */
+function antigravityWindowsFromModels(body: Record<string, unknown> | null): ProviderQuotaWindow[] {
+  const models = asRecord(body?.models);
+  if (!models) return [];
+
+  const windows = new Map<string, ProviderQuotaWindow>();
+  for (const [modelId, rawModelInfo] of Object.entries(models)) {
+    const modelInfo = asRecord(rawModelInfo);
+    if (!modelInfo) continue;
+    for (const quotaInfo of quotaInfoEntries(modelInfo)) {
+      const label = classifyAntigravityFamily(modelId, modelInfo, quotaInfo);
+      if (!label || windows.has(label)) continue;
+      const percent = antigravityUsedPercent(quotaInfo);
+      if (percent === undefined) continue;
+      windows.set(label, {
+        label,
+        percent,
+        ...(normalizeResetAt(quotaInfo.resetTime) !== undefined ? { resetAt: normalizeResetAt(quotaInfo.resetTime) } : {}),
+      });
+    }
+  }
+
+  const customWindows = ["Gem", "Cla"].flatMap(label => {
+    const window = windows.get(label);
+    return window ? [window] : [];
+  });
+  return customWindows;
+}
+
+/**
+ * Parse Google Antigravity quota from `v1internal:retrieveUserQuotaSummary`.
+ * Groups contain Gemini models and Claude/3P models, each with 5h and weekly limit buckets.
+ */
+function parseAntigravityQuotaSummary(body: Record<string, unknown> | null): ProviderQuota | null {
+  const groups = Array.isArray(body?.groups) ? (body.groups as unknown[]) : [];
+  if (groups.length === 0) return null;
+
+  const customWindowsMap = new Map<string, ProviderQuotaWindow>();
+
+  for (const rawGroup of groups) {
+    const group = asRecord(rawGroup);
+    if (!group) continue;
+    const groupName = `${typeof group.displayName === "string" ? group.displayName : ""} ${typeof group.description === "string" ? group.description : ""}`.toLowerCase();
+    const isGemini = groupName.includes("gemini");
+    const isClaude = groupName.includes("claude") || groupName.includes("3p") || groupName.includes("gpt");
+
+    const buckets = Array.isArray(group.buckets) ? (group.buckets as unknown[]) : [];
+    for (const rawBucket of buckets) {
+      const bucket = asRecord(rawBucket);
+      if (!bucket) continue;
+      const windowStr = `${typeof bucket.window === "string" ? bucket.window : ""} ${typeof bucket.bucketId === "string" ? bucket.bucketId : ""} ${typeof bucket.displayName === "string" ? bucket.displayName : ""}`.toLowerCase();
+      const percent = antigravityUsedPercent(bucket);
+      if (percent === undefined) continue;
+      const resetAt = normalizeResetAt(bucket.resetTime);
+
+      const isWeekly = windowStr.includes("week");
+      const is5h = windowStr.includes("5h") || windowStr.includes("five");
+
+      if (isGemini) {
+        const label = is5h ? "Gem" : isWeekly ? "Gem (Weekly)" : "";
+        if (label && !customWindowsMap.has(label)) {
+          customWindowsMap.set(label, { label, percent, ...(resetAt !== undefined ? { resetAt } : {}) });
+        }
+      } else if (isClaude) {
+        const label = is5h ? "Cla" : isWeekly ? "Cla (Weekly)" : "";
+        if (label && !customWindowsMap.has(label)) {
+          customWindowsMap.set(label, { label, percent, ...(resetAt !== undefined ? { resetAt } : {}) });
+        }
+      } else {
+        const baseLabel = typeof group.displayName === "string" ? group.displayName : "Other";
+        const label = isWeekly ? `${baseLabel} (Weekly)` : baseLabel;
+        if (!customWindowsMap.has(label)) {
+          customWindowsMap.set(label, { label, percent, ...(resetAt !== undefined ? { resetAt } : {}) });
+        }
+      }
+    }
+  }
+
+  const PREFERRED_ORDER = ["Gem", "Gem (Weekly)", "Cla", "Cla (Weekly)"];
+  const customWindows = Array.from(customWindowsMap.values()).sort((a, b) => {
+    const ia = PREFERRED_ORDER.indexOf(a.label);
+    const ib = PREFERRED_ORDER.indexOf(b.label);
+    if (ia !== -1 && ib !== -1) return ia - ib;
+    if (ia !== -1) return -1;
+    if (ib !== -1) return 1;
+    return a.label.localeCompare(b.label);
+  });
+
+  if (customWindows.length === 0) {
+    return null;
+  }
+
+  return {
+    customWindows,
+    updatedAt: Date.now(),
+  };
+}
+
+const ANTIGRAVITY_ACCOUNT_QUOTA_BASE = "https://daily-cloudcode-pa.googleapis.com";
+const ANTIGRAVITY_QUOTA_SUMMARY_URL = `${ANTIGRAVITY_ACCOUNT_QUOTA_BASE}/v1internal:retrieveUserQuotaSummary`;
+const ANTIGRAVITY_QUOTA_MODELS_URL = `${ANTIGRAVITY_ACCOUNT_QUOTA_BASE}/v1internal:fetchAvailableModels`;
+
+/** Only these fixed accounting destinations may use transparent Fake-IP DNS. */
+export function isCanonicalAntigravityQuotaUrl(name: string, url: string): boolean {
+  return name === "google-antigravity"
+    && (url === ANTIGRAVITY_QUOTA_SUMMARY_URL || url === ANTIGRAVITY_QUOTA_MODELS_URL);
+}
+
+let antigravityOutboundDependencies: ProviderOutboundDependencies = {
+  isCanonicalUrl: isCanonicalAntigravityQuotaUrl,
+};
+
+/** Test seam: inject resolver/pinned transport for provider and per-account probes. */
+export function setAntigravityAccountQuotaTransportForTests(dependencies: ProviderOutboundDependencies | null): void {
+  antigravityOutboundDependencies = { ...dependencies, isCanonicalUrl: isCanonicalAntigravityQuotaUrl };
+}
+
+/**
+ * Per-account Antigravity quota (#1082). Always probes Google's own Cloud Code Assist host
+ * through the pinned provider-outbound transport: a configured `baseUrl` is a routing choice
+ * for requests, not a second source of Google's accounting for a stored credential, and fixing
+ * the destination keeps the `provider\0accountId` cache identity exact across config changes.
+ * A redirect or non-2xx yields null (unavailable), never a partial row.
+ */
+type AntigravityQuotaProbeResult =
+  | { kind: "available"; quota: ProviderQuota; source: "google-antigravity:retrieveUserQuotaSummary" | "google-antigravity:fetchAvailableModels" }
+  | { kind: "unavailable"; failure: QuotaFailureCode; legacy: { kind: "null" } | { kind: "throw"; error: unknown } };
+
+function quotaTransportFailure(error: unknown): QuotaFailureCode {
+  if (error instanceof ProviderOutboundPolicyError) return "destination_blocked";
+  if (error instanceof DestinationDnsResolutionError) return "dns_failed";
+  if (error instanceof PinnedHttpError) return error.code === "output_byte_limit" ? "response_unusable" : "timeout";
+  if (error instanceof DOMException && error.name === "TimeoutError") return "timeout";
+  return "transport_error";
+}
+
+function quotaHttpFailure(status: number): QuotaFailureCode {
+  if (status >= 300 && status < 400) return "redirect_blocked";
+  if (status === 401 || status === 403) return "access_denied";
+  if (status === 429) return "rate_limited";
+  return "upstream_error";
+}
+
+function unavailableAntigravityQuota(failure: QuotaFailureCode): AntigravityQuotaProbeResult {
+  return { kind: "unavailable", failure, legacy: { kind: "null" } };
+}
+
+/**
+ * Prefer a summary network-policy diagnosis over a vaguer fallback. A blocked
+ * destination is an actionable local-network fact, while "upstream_error" tells
+ * the operator to go look at Google. A successful models probe still clears
+ * the first failure completely.
+ */
+function antigravityUnavailableFailure(
+  summaryFailure: QuotaFailureCode | undefined,
+  fallbackFailure: QuotaFailureCode,
+): QuotaFailureCode {
+  if (
+    (summaryFailure === "destination_blocked" || summaryFailure === "dns_failed")
+    && fallbackFailure !== "destination_blocked"
+    && fallbackFailure !== "dns_failed"
+  ) {
+    return summaryFailure;
+  }
+  return fallbackFailure;
+}
+
+export async function probeAntigravityUsageQuota(accessToken: string, projectId: string): Promise<AntigravityQuotaProbeResult> {
+  const fetchQuota = (url: string) => providerOutboundPost("google-antigravity", { baseUrl: ANTIGRAVITY_ACCOUNT_QUOTA_BASE }, url, {
+    headers: {
+      Accept: "application/json", "Content-Type": "application/json",
+      "User-Agent": antigravityUserAgent(), Authorization: `Bearer ${accessToken}`,
+    },
+    body: JSON.stringify({ project: projectId }), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  }, antigravityOutboundDependencies);
+  let summaryFailure: QuotaFailureCode | undefined;
+  try {
+    const response = await fetchQuota(ANTIGRAVITY_QUOTA_SUMMARY_URL);
+    if (await providerRedirectError(response, ANTIGRAVITY_QUOTA_SUMMARY_URL)) return unavailableAntigravityQuota("redirect_blocked");
+    if (response.status === 401 || response.status === 403) return unavailableAntigravityQuota("access_denied");
+    if (response.ok) {
+      const quota = parseAntigravityQuotaSummary(asRecord(await readQuotaJson(response)));
+      if (quota) return { kind: "available", quota, source: "google-antigravity:retrieveUserQuotaSummary" };
+    }
+  } catch (error) {
+    // Existing behavior: summary transport/parse failure may recover through the models probe.
+    summaryFailure = quotaTransportFailure(error);
+  }
+  try {
+    const response = await fetchQuota(ANTIGRAVITY_QUOTA_MODELS_URL);
+    if (await providerRedirectError(response, ANTIGRAVITY_QUOTA_MODELS_URL)) {
+      return unavailableAntigravityQuota(antigravityUnavailableFailure(summaryFailure, "redirect_blocked"));
+    }
+    if (!response.ok) {
+      return unavailableAntigravityQuota(antigravityUnavailableFailure(summaryFailure, quotaHttpFailure(response.status)));
+    }
+    const customWindows = antigravityWindowsFromModels(asRecord(await readQuotaJson(response)));
+    if (!customWindows.length) {
+      return unavailableAntigravityQuota(antigravityUnavailableFailure(summaryFailure, "response_unusable"));
+    }
+    return { kind: "available", quota: { customWindows, updatedAt: Date.now() }, source: "google-antigravity:fetchAvailableModels" };
+  } catch (error) {
+    // The public compatibility wrapper still rejects this exact fallback error; it never enters a DTO.
+    return {
+      kind: "unavailable",
+      failure: antigravityUnavailableFailure(summaryFailure, quotaTransportFailure(error)),
+      legacy: { kind: "throw", error },
+    };
+  }
+}
+
+export async function fetchAntigravityUsageQuota(accessToken: string, projectId: string): Promise<ProviderQuota | null> {
+  const result = await probeAntigravityUsageQuota(accessToken, projectId);
+  if (result.kind === "available") return result.quota;
+  if (result.legacy.kind === "throw") throw result.legacy.error;
+  return null;
+}
+
+export async function fetchAntigravityQuota(provider: string): Promise<ProviderQuotaReport | null> {
+  const credential = getCredential("google-antigravity");
+  if (!credential?.projectId) return null;
+  let accessToken: string;
+  try { accessToken = await getValidAccessToken("google-antigravity"); } catch { return null; }
+  const result = await probeAntigravityUsageQuota(accessToken, credential.projectId);
+  if (result.kind === "available") return report(provider, result.source, result.quota);
+  if (result.legacy.kind === "throw") throw result.legacy.error;
+  return null;
+}

package/src/providers/quota/report-cache.ts

@@ -0,0 +1,320 @@
+import { createHash } from "node:crypto";
+import { effectiveCodexAuthAccountId, listCodexAuthAccountsSnapshot } from "../../codex/auth-api";
+import { withoutRetiredCodexQuota, type StoredAccountQuota } from "../../codex/quota";
+import { isMainAccountIdentityGenerationLive } from "../../codex/main-account-cache";
+import { codexPlanKey } from "../../codex/plan";
+import { resolveProviderApiKey } from "../key-store";
+import { apiKeyPoolEntryId } from "../api-keys";
+import { getProviderRegistryEntry, providerCodexAccountMode } from "../registry";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../openai-tiers";
+import { CODEX_CAPACITY_MAX_QUOTA_AGE_MS, type CodexCapacityAggregation, type CodexCapacityQuota } from "../codex-capacity";
+import { clearCachedProviderQuotas, providerQuotaRoutingBinding, type ProviderQuotaRoutingEvidence } from "../quota-routing-cache";
+import { clearProviderApiKeyQuotaCache } from "../quota-key-accounts";
+import { QUOTA_JSON_READ_FAILURE, readQuotaJson } from "../quota-wire";
+import type { OcxConfig, OcxProviderConfig } from "../../types";
+import type { ProviderQuota, ProviderRoutingQuota } from "../quota-types";
+
+/** Keep a failed probe's previous row at most this long before dropping it. */
+export const LAST_GOOD_MAX_AGE_MS = CODEX_CAPACITY_MAX_QUOTA_AGE_MS;
+const nativeMainReportGenerations = new WeakMap<ProviderQuotaReport, number>();
+export const accountReportCurrent = new WeakMap<ProviderQuotaReport, () => boolean>();
+export const routingEvidence = new WeakMap<ProviderQuotaReport, ProviderQuotaRoutingEvidence>();
+export let providerQuotaBeforePublishForTests: (() => void | Promise<void>) | null = null;
+
+/** Test-only seam for identity/config invalidation after probes but before publication. */
+export function setProviderQuotaBeforePublishForTests(
+  hook: (() => void | Promise<void>) | null,
+): void {
+  providerQuotaBeforePublishForTests = hook;
+}
+export const TERMINAL_QUOTA_FAILURE = Symbol("terminal-quota-failure");
+/**
+ * The probe succeeded and the upstream authoritatively reported NO model-quota windows.
+ *
+ * Distinct from `null`, which means "this probe told us nothing" and deliberately preserves
+ * the last-good row for up to 30 minutes. Collapsing the two would let a stale report outlive
+ * the authoritative answer that replaced it: a GLM plan whose payload carries only MCP
+ * `TIME_LIMIT` rows has no model windows, and the dashboard and quota-aware routing must stop
+ * showing the previous token windows rather than keep them for another half hour.
+ *
+ * Suppression is shared with `TERMINAL_QUOTA_FAILURE`; only the reason differs.
+ */
+export const AUTHORITATIVE_EMPTY_QUOTA = Symbol("authoritative-empty-quota");
+export type ProviderQuotaProbeResult =
+  | ProviderQuotaReport
+  | null
+  | typeof TERMINAL_QUOTA_FAILURE
+  | typeof AUTHORITATIVE_EMPTY_QUOTA;
+
+export interface ProviderQuotaReport {
+  provider: string;
+  label: string;
+  source: string;
+  quota: ProviderQuota;
+  updatedAt: number;
+  /** Added by the management response projection, never stored on a cached report. */
+  routingQuota?: ProviderRoutingQuota;
+  reverseEngineered?: boolean;
+  /**
+   * The row was OBSERVED in-band on a streaming turn rather than probed.
+   *
+   * Age means something different for these. A probed provider re-reads on its own TTL,
+   * so a row older than the last-good bound means the probe is failing and showing it
+   * would misrepresent a live number. A passive provider publishes no endpoint at all
+   * (`hasPassiveAccountQuota`), so its last observation is not a stale reading of
+   * something fresher — it is the only measurement that exists, and dropping it leaves
+   * the operator with nothing. Consumers that enforce a freshness bound must exempt
+   * these and state the observation age instead.
+   */
+  observed?: boolean;
+  aggregation?: CodexCapacityAggregation;
+}
+
+export interface ProviderQuotaResponse {
+  generatedAt: number;
+  reports: ProviderQuotaReport[];
+}
+
+let cache: { key: string; ts: number; response: ProviderQuotaResponse } | null = null;
+export const inflight = new Map<string, { epoch: number; promise: Promise<ProviderQuotaResponse> }>();
+/** Bumped on cache clear and on force-refresh start; stale-epoch probes lose commit authority. */
+export let invalidationEpoch = 0;
+
+/** Owner-module accessors: cache reassignment stays inside this file. */
+export function getProviderQuotaReportCache(): { key: string; ts: number; response: ProviderQuotaResponse } | null {
+  return cache;
+}
+
+export function setProviderQuotaReportCache(next: { key: string; ts: number; response: ProviderQuotaResponse } | null): void {
+  cache = next;
+}
+
+export function bumpProviderQuotaInvalidationEpoch(): void {
+  invalidationEpoch += 1;
+}
+
+/** Invalidate the report cache (e.g. after switching a provider's active account). */
+export function clearProviderQuotaCache(): void {
+  cache = null;
+  clearCachedProviderQuotas();
+  clearProviderApiKeyQuotaCache();
+  invalidationEpoch += 1;
+}
+
+function cacheKey(config: OcxConfig): string {
+  const providers = Object.entries(config.providers)
+    .map(([name, provider]) => {
+      const resolvedKey = typeof provider.apiKey === "string"
+        ? resolveProviderApiKey(provider.apiKey)?.trim()
+        : undefined;
+      const activeKeyId = resolvedKey ? apiKeyPoolEntryId(resolvedKey) : "none";
+      return `${name}:${provider.adapter}:${provider.authMode ?? "key"}:${providerCodexAccountMode(name, provider) ?? "none"}:${provider.disabled === true ? "off" : "on"}:${provider.baseUrl}:${activeKeyId}`;
+    })
+    .sort()
+    .join("|");
+  return `${config.defaultProvider}|${providers}`;
+}
+
+export type CodexAuthAccountsSnapshotPromise = ReturnType<typeof listCodexAuthAccountsSnapshot>;
+
+export function hasCodexPoolProvider(config: OcxConfig): boolean {
+  return Object.entries(config.providers).some(([name, provider]) => (
+    provider.disabled !== true
+    && isBuiltInChatGptForwardProvider(name, provider)
+    && providerCodexAccountMode(name, provider) !== "direct"
+  ));
+}
+
+function quotaSignatureValue(quota: CodexCapacityQuota | null): unknown {
+  if (!quota) return null;
+  return {
+    fiveHourPercent: quota.fiveHourPercent,
+    fiveHourResetAt: quota.fiveHourResetAt,
+    weeklyPercent: quota.weeklyPercent,
+    weeklyResetAt: quota.weeklyResetAt,
+    monthlyPercent: quota.monthlyPercent,
+    monthlyResetAt: quota.monthlyResetAt,
+    updatedAt: quota.updatedAt,
+    customWindows: [...(quota.customWindows ?? [])]
+      .map(window => ({ label: window.label, percent: window.percent, resetAt: window.resetAt }))
+      .sort((a, b) => a.label.localeCompare(b.label)),
+  };
+}
+
+export function providerQuotaFromCodexQuota(
+  quota: StoredAccountQuota | Omit<StoredAccountQuota, "updatedAt"> | null | undefined,
+): CodexCapacityQuota | null {
+  if (!quota) return null;
+  // Direct snapshots bypass account DTOs; sanitize here as well as at ingestion.
+  quota = withoutRetiredCodexQuota(quota);
+  if (!quota) return null;
+  const projected: CodexCapacityQuota = {
+    ...(quota.shortPercent !== undefined ? { fiveHourPercent: quota.shortPercent } : {}),
+    ...(quota.shortResetAt !== undefined ? { fiveHourResetAt: quota.shortResetAt } : {}),
+    ...(quota.weeklyPercent !== undefined ? { weeklyPercent: quota.weeklyPercent } : {}),
+    ...(quota.weeklyResetAt !== undefined ? { weeklyResetAt: quota.weeklyResetAt } : {}),
+    ...(quota.monthlyPercent !== undefined ? { monthlyPercent: quota.monthlyPercent } : {}),
+    ...(quota.monthlyResetAt !== undefined ? { monthlyResetAt: quota.monthlyResetAt } : {}),
+    ...(quota.customWindows !== undefined ? { customWindows: quota.customWindows } : {}),
+    updatedAt: "updatedAt" in quota ? quota.updatedAt : Date.now(),
+  };
+  return hasQuotaRows(projected) ? projected : null;
+}
+
+/** Hash only presentation-relevant state; account ids and email addresses never enter the key. */
+export function cacheKeyWithAggregationState(
+  config: OcxConfig,
+  prefetchedSnapshot?: CodexAuthAccountsSnapshotPromise,
+): string | Promise<string> {
+  const base = cacheKey(config);
+  if (!hasCodexPoolProvider(config)) return base;
+  return (async () => {
+    try {
+      const activeId = effectiveCodexAuthAccountId(config);
+      const snapshot = await (prefetchedSnapshot ?? listCodexAuthAccountsSnapshot(config, false));
+      const rows = snapshot.accounts.map(account => ({
+        isMain: account.isMain,
+        active: account.id === activeId,
+        plan: codexPlanKey(account.plan) ?? null,
+        paused: account.paused,
+        needsReauth: account.needsReauth === true,
+        quota: quotaSignatureValue(providerQuotaFromCodexQuota(account.quota)),
+      }));
+      const canonicalRows = rows.map(row => JSON.stringify(row)).sort();
+      const digest = createHash("sha256").update(JSON.stringify(canonicalRows)).digest("hex").slice(0, 24);
+      return `${base}|codex-pool:${digest}`;
+    } catch {
+      return `${base}|codex-pool:unavailable`;
+    }
+  })();
+}
+
+function publicCapacityWindow(window: import("../codex-capacity").CodexCapacityWindowAggregation) {
+  const { totalWeight: _totalWeight, consumedWeight: _consumedWeight, remainingWeight: _remainingWeight, ...safe } = window;
+  return safe;
+}
+
+/** Management API metadata intentionally omits configured/weighted unit counts. */
+export function publicCapacityAggregation(
+  aggregation: CodexCapacityAggregation,
+  presentation: NonNullable<CodexCapacityAggregation["presentation"]>,
+): CodexCapacityAggregation {
+  const safeCurrentAccount = presentation === "coverage-only" && aggregation.currentAccount
+    ? { ...aggregation.currentAccount, quota: null }
+    : aggregation.currentAccount;
+  return {
+    ...aggregation,
+    presentation,
+    ...(safeCurrentAccount ? { currentAccount: safeCurrentAccount } : {}),
+    ...(aggregation.fiveHour ? { fiveHour: publicCapacityWindow(aggregation.fiveHour) } : {}),
+    ...(aggregation.weekly ? { weekly: publicCapacityWindow(aggregation.weekly) } : {}),
+    ...(aggregation.monthly ? { monthly: publicCapacityWindow(aggregation.monthly) } : {}),
+    ...(aggregation.customWindows ? {
+      customWindows: aggregation.customWindows.map(window => ({
+        label: window.label,
+        ...publicCapacityWindow(window),
+      })),
+    } : {}),
+  };
+}
+
+export function hasQuotaRows(quota: ProviderQuota | null | undefined): quota is ProviderQuota {
+  if (!quota) return false;
+  return typeof quota.fiveHourPercent === "number"
+    || typeof quota.weeklyPercent === "number"
+    || typeof quota.monthlyPercent === "number"
+    || quota.creditsUsd?.unlimited === true
+    || typeof quota.creditsUsd?.percent === "number"
+    || !!quota.customWindows?.some(window => typeof window.percent === "number");
+}
+
+export function providerLabel(providerId: string): string {
+  return getProviderRegistryEntry(providerId)?.label ?? providerId;
+}
+
+/** Test-only access to the quota reader's deadline and cancellation contract. */
+export async function readProviderQuotaJsonForTests(response: Response, timeoutMs: number): Promise<unknown> {
+  const result = await readQuotaJson(response, timeoutMs);
+  return result === QUOTA_JSON_READ_FAILURE ? null : result;
+}
+
+export function isBuiltInChatGptForwardProvider(name: string, provider: OcxProviderConfig): boolean {
+  return name === OPENAI_CODEX_PROVIDER_ID && isCanonicalOpenAiForwardProvider(provider);
+}
+
+export function report(
+  provider: string,
+  source: string,
+  quota: ProviderQuota,
+  aggregation?: CodexCapacityAggregation,
+): ProviderQuotaReport | null {
+  if (!hasQuotaRows(quota)) return null;
+  return {
+    provider,
+    label: providerLabel(provider),
+    source,
+    quota,
+    updatedAt: quota.updatedAt,
+    ...(aggregation ? { aggregation } : {}),
+  };
+}
+
+/**
+ * Publish a credential-bound report, and routing evidence only when the producer
+ * hands over its inference-only projection.
+ *
+ * The projection is deliberately not defaulted to the display quota. A producer must
+ * decide that its rows really do constrain inference on the probed credential; omitting
+ * the argument leaves the report display-only, so a new producer cannot inherit
+ * provider-veto authority merely by calling this helper. Ownership alone is not the
+ * scope decision: providerQuotaRoutingBinding resolving is necessary, never sufficient.
+ */
+export function keyReport(
+  provider: string,
+  source: string,
+  quota: ProviderQuota,
+  config: OcxProviderConfig,
+  probedCredential: string,
+  inferenceQuota?: ProviderQuota,
+): ProviderQuotaReport | null {
+  const result = report(provider, source, quota);
+  if (!result || !inferenceQuota) return result;
+  const binding = providerQuotaRoutingBinding(provider, config, probedCredential);
+  if (binding) routingEvidence.set(result, { quota: inferenceQuota, binding });
+  return result;
+}
+
+export function tagNativeMainReport(
+  value: ProviderQuotaReport | null,
+  generation: number,
+): ProviderQuotaReport | null {
+  if (value) nativeMainReportGenerations.set(value, generation);
+  return value;
+}
+
+/**
+ * Test-only seam: publish exactly as a credential-bound producer does, and hand back the
+ * routing evidence the publication actually attached.
+ *
+ * Live producers all pass a projection today, so no probe fixture can prove the OTHER half
+ * of the contract: that omitting it stays display-only. Routing an omitted argument through
+ * the real helper keeps that provable, and a re-introduced `= quota` default would be
+ * observed here (a defaulted parameter also fires for an explicitly undefined argument).
+ */
+export function publishKeyReportForTests(
+  provider: string,
+  source: string,
+  quota: ProviderQuota,
+  config: OcxProviderConfig,
+  probedCredential: string,
+  inferenceQuota?: ProviderQuota,
+): { report: ProviderQuotaReport | null; routing: ProviderQuotaRoutingEvidence | undefined } {
+  const result = keyReport(provider, source, quota, config, probedCredential, inferenceQuota);
+  return { report: result, routing: result ? routingEvidence.get(result) : undefined };
+}
+
+export function isProviderQuotaReportCurrent(value: ProviderQuotaReport): boolean {
+  const generation = nativeMainReportGenerations.get(value);
+  return (generation === undefined || isMainAccountIdentityGenerationLive(generation))
+    && (accountReportCurrent.get(value)?.() ?? true);
+}