@bitkyc08/opencodex 2.88.0 → 2.90.0

package/src/combos/failover.ts

@@ -2,6 +2,7 @@ import { parseResetCooldownMs } from "../codex/routing";
 import { classifyError, isCyberPolicyCode } from "../lib/errors";
 import { isNonReplayableUpstreamCode } from "../lib/upstream-retry";
 import { isAnthropicBillingFailure } from "../providers/anthropic-billing-refusal";
+import { isKiroAccountProfileRefusal } from "../adapters/kiro-refusal";
 import type { OcxComboTarget } from "../types";
 import { targetKey } from "./types";
 import {
@@ -666,8 +667,9 @@ function isDefiniteContextOverflowMessage(text: string): boolean {
  * arbitrary field that happens to sit in the first 500 bytes authorize a hop, so it fails closed.
  *
  * Only the exact proxy wrapper is unwrapped, within a fixed envelope budget and 16,384 characters.
+ * Exported for the sidecar loops, which classify their own provider failures with the same rule.
  */
-function isDefiniteContextOverflow(status: number, message: string): boolean {
+export function isDefiniteContextOverflow(status: number, message: string): boolean {
   if (!CONTEXT_VERDICT_STATUSES.has(status) && status < 500) return false;
   if (message.length > 16_384) return false;
   let text = message.trim();
@@ -771,7 +773,7 @@ export function codexAccountModelRefusal(
 export function comboFailureDecision(
   status: number,
   message: string,
-  options?: { code?: string | null; codexModelRefusal?: CodexAccountModelRefusal },
+  options?: { code?: string | null; codexModelRefusal?: CodexAccountModelRefusal; failedAdapter?: string },
 ): ComboFailureDecision {
   if (status === 499) return "stop";
   if (message.toLowerCase().includes("origin_rejected")) return "stop";
@@ -855,6 +857,12 @@ export function comboFailureDecision(
   // could have served the request (#4903).
   if (isResponseFormatCapabilityRefusal(status, message, options?.code)) return "hop";
   if (isAnthropicBillingFailure(status, message, options?.code)) return "hop";
+  // Kiro's body validator rejects the request for the identity it was routed under. The account
+  // layer rotates logins first; this is the no-alternate case, so the next combo target is the
+  // only remaining chance to serve the turn. Only a caller that knows the failed target is a Kiro
+  // adapter grants it (the words alone prove nothing for another provider); it must precede the
+  // generic invalid_request_error stop.
+  if (options?.failedAdapter === "kiro" && isKiroAccountProfileRefusal(status, message)) return "hop";
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }

package/src/combos/jev-model-backend.ts

@@ -1,3 +1,6 @@
+import { boundedJevQuotaPayload, jevQuotaCandidates, withJevQuotaSummary } from "./jev-quota-route";
+import { JEV_QUOTA_INSTRUCTION } from "./jev-quota";
+import { serializeJevModelRequest, type JevModelRequestBody } from "./jev-model-request";
 import {
   buildJevState,
   candidatesFitRequestBounds,
@@ -25,11 +28,14 @@ export interface JevModelInvokeRequest {
   instructions: string;
   input: string;
   signal: AbortSignal;
+  /** Budget-only fallback, selected by the detached invoker before admission or dispatch. */
+  withoutQuota?: Pick<JevModelRequestBody, "instructions" | "input">;
 }
 
 export interface JevModelInvokeResult {
   text: string;
   usage?: Record<string, number>;
+  quotaOmitted?: true;
 }
 
 export type JevModelInvoke = (request: JevModelInvokeRequest) => Promise<JevModelInvokeResult>;
@@ -69,29 +75,45 @@ export function parseJevModelChoice(text: string, allowed: ReadonlySet<string>):
   return choice;
 }
 
+/** Resolve a JEV decision through the decision model, falling back with a gate reason on any failure; quota tiers are advisory input only and never widen the allowlist. */
 export async function resolveJevModelDecision(
   options: ResolveJevDecisionOptions & { decisionModel: string; invokeModel: JevModelInvoke },
 ): Promise<JevDecision> {
   const now = options.now ?? Date.now;
   const startedAt = now();
+  let candidates = options.candidates;
+  /** Build the fallback decision for a failure gate, attaching the quota summary for the candidates in scope. */
   const failed = (gate: Exclude<JevDecision["gate"], "apply">): JevDecision =>
-    fallbackDecision(options.fallback, gate, Math.max(0, now() - startedAt), "model");
+    withJevQuotaSummary(fallbackDecision(options.fallback, gate, Math.max(0, now() - startedAt), "model"), candidates);
 
   if (options.signal?.aborted) throw options.signal.reason;
   if (options.candidates.length === 0) return failed("no_choices");
   if (!candidatesFitRequestBounds(options.candidates)) return failed("invalid");
 
   let routeOptions: JevRouteOptionDescriptor[];
-  let input: string;
+  let input = "";
+  let instructions = JEV_MODEL_INSTRUCTIONS;
+  let withoutQuota: JevModelInvokeRequest["withoutQuota"];
   try {
     routeOptions = jevRouteOptions(options.candidates);
     if (routeOptions.length > JEV_MODEL_MAX_OPTIONS) return failed("invalid");
     const state = buildJevState(options.body, options.candidates);
     if (!hasJevDecisionState(state)) return failed("no_state");
-    input = buildJevModelPrompt(state, options.candidates);
-    if (new TextEncoder().encode(JEV_MODEL_INSTRUCTIONS + input).byteLength > JEV_MAX_REQUEST_BYTES) {
+    const payload = boundedJevQuotaPayload(jevQuotaCandidates(options), rows => {
+      instructions = JEV_MODEL_INSTRUCTIONS + (rows.some(row => row.quota) ? " " + JEV_QUOTA_INSTRUCTION : "");
+      input = buildJevModelPrompt(state, rows);
+      if (options.decisionQuotaSignals !== true) return instructions + input;
+      const request = { model: options.decisionModel, instructions, input };
+      return serializeJevModelRequest(request);
+    }, JEV_MAX_REQUEST_BYTES);
+    candidates = payload.candidates;
+    if (new TextEncoder().encode(payload.body).byteLength > JEV_MAX_REQUEST_BYTES) {
       return failed("invalid");
     }
+    if (candidates.some(row => row.quota)) {
+      withoutQuota = { instructions: JEV_MODEL_INSTRUCTIONS,
+        input: buildJevModelPrompt(state, candidates.map(({ quota: _quota, ...row }) => row)) };
+    }
   } catch {
     return failed("invalid");
   }
@@ -99,7 +121,8 @@ export async function resolveJevModelDecision(
   const timeoutSignal = AbortSignal.timeout(jevDecisionTimeoutMs(options.timeoutMs));
   const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
   try {
-    const result = await options.invokeModel({ model: options.decisionModel, instructions: JEV_MODEL_INSTRUCTIONS, input, signal });
+    const result = await options.invokeModel({ model: options.decisionModel, instructions, input, signal, ...(withoutQuota ? { withoutQuota } : {}) });
+    if (result.quotaOmitted) candidates = candidates.map(({ quota: _quota, ...row }) => row);
     if (options.signal?.aborted) throw options.signal.reason;
     if (timeoutSignal.aborted) return failed("timeout");
     let choice: string;
@@ -111,14 +134,14 @@ export async function resolveJevModelDecision(
     const selected = routeOptions.find(option => option.key === choice)!;
     const usage = jevUsage({ usage: result.usage });
     if (options.signal?.aborted) throw options.signal.reason;
-    return {
+    return withJevQuotaSummary({
       backend: "model",
       targetKey: selected.targetKey,
       effort: selected.effort,
       gate: "apply",
       latencyMs: Math.max(0, now() - startedAt),
       ...(usage ? { usage } : {}),
-    };
+    }, candidates);
   } catch (error) {
     if (options.signal?.aborted) throw options.signal.reason;
     if (timeoutSignal.aborted || (error instanceof Error && error.name === "TimeoutError")) return failed("timeout");

package/src/combos/jev-model-request.ts

@@ -0,0 +1,20 @@
+/** The exact detached Responses envelope, shared by quota sizing and the invoker. */
+export const JEV_MODEL_MAX_OUTPUT_TOKENS = 1024;
+export interface JevModelRequestBody {
+  model: string;
+  instructions: string;
+  input: string;
+}
+/** Serialize the streaming decision-model request body, adding the reasoning effort only when one is given. */
+export function serializeJevModelRequest(request: JevModelRequestBody, effort?: string): string {
+  return JSON.stringify({
+    model: request.model,
+    stream: true,
+    store: false,
+    instructions: request.instructions,
+    input: [{ role: "user", content: [{ type: "input_text", text: request.input }] }],
+    tools: [],
+    max_output_tokens: JEV_MODEL_MAX_OUTPUT_TOKENS,
+    ...(effort ? { reasoning: { effort } } : {}),
+  });
+}

package/src/combos/jev-quota-activation.ts

@@ -0,0 +1,153 @@
+/**
+ * Activation owner for JEV advisory quota evidence.
+ *
+ * The decision snapshot (`src/providers/quota-decision-snapshot.ts`) is imported here and by
+ * nothing on the core path. Core credential stores and quota producers call the slot in
+ * `src/lib/decision-quota-sink.ts`; this module registers the snapshot-backed sink only while the
+ * live config has a JEV combo with `decisionQuotaSignals: true`, and withdraws everything when the
+ * last such combo is turned off, deleted or the config root changes.
+ *
+ * Activation replays the current stores through observe-only reads (`peekAuthStore`,
+ * `peekCodexAccountRecordStore`, `peekMainDecisionRow`): no hardening, backup, write, credential
+ * resolution or upstream probe, and never on a request's decision path. Stores keep no in-memory
+ * cache, so this one bounded read at activation is what "publish once from the loaded stores" costs,
+ * paid only by installs that opted in.
+ */
+import {
+  clearDecisionAccountQuotas, invalidateDecisionKeyQuotas, observeDecisionKeyCredential, publishDecisionAccountQuota,
+  publishDecisionKeyQuota, publishDecisionQuotaRoster, readLoadedDecisionKeyQuota, readLoadedDecisionQuotaPool,
+  setDecisionAccountUsable, withdrawDecisionQuotaRoster,
+} from "../providers/quota-decision-snapshot";
+import { registerDecisionQuotaSink, type DecisionQuotaSink, type MainDecisionRow } from "../lib/decision-quota-sink";
+import { registerLiveConfigObserver } from "../lib/state-store-registrations";
+import { getConfigDir } from "../config/paths";
+import { peekAuthStore } from "../oauth/store";
+import { peekCodexAccountRecordStore } from "../codex/account-store";
+import { peekMainDecisionRow } from "../codex/main-account-cache";
+import { createHash } from "node:crypto";
+import type { AuthStore } from "../oauth/store";
+import type { CodexAccountCredentialRecord, OcxConfig } from "../types";
+
+const POOL_PROVIDERS = ["anthropic", "codex", "codex-main"] as const;
+
+/** Project an auth store the owner already read into the secret-free Anthropic roster (primary pool only); a failure withdraws so the pool reads as unknown. The generation is a one-way digest of the credential, never the credential itself. */
+function publishAuthDecisionQuotaRoster(store: AuthStore): void {
+  try {
+    publishDecisionQuotaRoster("anthropic", (store.anthropic?.accounts ?? []).map(row => ({
+      id: row.id,
+      generation: createHash("sha256").update(JSON.stringify([row.credential.refresh, row.credential.access, row.credential.expires])).digest("hex"),
+      usable: row.paused !== true && row.needsReauth !== true && Boolean(row.credential.access || row.credential.refresh),
+    })));
+  } catch {
+    try { withdrawDecisionQuotaRoster("anthropic"); } catch { /* unknown */ }
+  }
+}
+
+/** Project a Codex account store the owner already read into the secret-free roster (id, credential generation, usability); a failure withdraws. */
+function publishCodexDecisionQuotaRoster(store: Readonly<Record<string, CodexAccountCredentialRecord>>): void {
+  try {
+    publishDecisionQuotaRoster("codex", Object.entries(store).map(([id, row]) => ({
+      id, generation: row.generation,
+      usable: !!row.credential && row.deletedAt == null && !row.codexValidationPending && !row.lastCodexValidationTerminal,
+    })));
+  } catch {
+    try { withdrawDecisionQuotaRoster("codex"); } catch { /* unknown */ }
+  }
+}
+
+/** Whether a config enables advisory quota signals on at least one JEV combo. */
+export function jevQuotaSignalsWanted(config: Pick<OcxConfig, "combos"> | null | undefined): boolean {
+  return Object.values(config?.combos ?? {}).some(combo => combo?.strategy === "jev" && combo.decisionQuotaSignals === true);
+}
+
+/** Publish the native-main row, or withdraw it; a failed publication withdraws so a previous row cannot linger (same guard as the auth/Codex projections). */
+function publishMainRow(row: MainDecisionRow | undefined): void {
+  try {
+    if (row) publishDecisionQuotaRoster("codex-main", [{ id: "__main__", generation: row.generation, usable: row.usable }]);
+    else withdrawDecisionQuotaRoster("codex-main");
+  } catch {
+    try { withdrawDecisionQuotaRoster("codex-main"); } catch { /* best-effort; the pool reads as unknown */ }
+  }
+}
+
+const snapshotSink: DecisionQuotaSink = {
+  observeKeyCredential: observeDecisionKeyCredential,
+  invalidateKeyQuotas: invalidateDecisionKeyQuotas,
+  publishKeyQuota: publishDecisionKeyQuota,
+  publishAccountQuota: (provider, id, generation, windows, partial) => publishDecisionAccountQuota(provider, id, generation, windows, partial),
+  setAccountUsable: setDecisionAccountUsable,
+  clearAccountQuotas: clearDecisionAccountQuotas,
+  authStoreLoaded: publishAuthDecisionQuotaRoster,
+  codexStoreLoaded: publishCodexDecisionQuotaRoster,
+  mainRosterChanged: row => publishMainRow(row),
+  readKeyQuota: readLoadedDecisionKeyQuota,
+  readPool: readLoadedDecisionQuotaPool,
+};
+
+let active: { detach: () => void; root: string } | undefined;
+
+function withdrawAll(): void {
+  for (const provider of POOL_PROVIDERS) withdrawDecisionQuotaRoster(provider);
+  clearDecisionAccountQuotas();
+  invalidateDecisionKeyQuotas();
+}
+
+/**
+ * Replay the current stores into the snapshot through observe-only reads. Each pool fails closed to
+ * unknown. Ownership is rechecked after every read: a reentrant notification that deactivates (or
+ * restarts) during a read must not be followed by a publication from this stale replay.
+ */
+function replayCurrentStores(owner: object): void {
+  const owns = () => active === owner;
+  try { const store = peekAuthStore(); if (owns()) publishAuthDecisionQuotaRoster(store); } catch { if (owns()) withdrawDecisionQuotaRoster("anthropic"); }
+  try { const store = peekCodexAccountRecordStore(); if (owns()) publishCodexDecisionQuotaRoster(store); } catch { if (owns()) withdrawDecisionQuotaRoster("codex"); }
+  try { const row = peekMainDecisionRow(); if (owns()) publishMainRow(row); } catch { if (owns()) { try { withdrawDecisionQuotaRoster("codex-main"); } catch { /* unknown */ } } }
+}
+
+/** Detach the sink first, so no producer can write while the snapshot is withdrawn. */
+export function deactivateJevQuotaActivation(): void {
+  const current = active;
+  if (!current) return;
+  active = undefined;
+  current.detach();
+  try { withdrawAll(); } catch { /* the snapshot is unreachable once detached */ }
+}
+
+/** Converge activation with a live config: register on the first enabling combo, withdraw after the last, and restart on a config root change. Never throws. */
+export function reconcileJevQuotaActivation(config: OcxConfig): void {
+  try {
+    const wanted = jevQuotaSignalsWanted(config);
+    const root = getConfigDir();
+    if (active && (!wanted || active.root !== root)) deactivateJevQuotaActivation();
+    if (!wanted || active) return;
+    const owner = { detach: registerDecisionQuotaSink(snapshotSink), root };
+    active = owner;
+    replayCurrentStores(owner);
+  } catch {
+    deactivateJevQuotaActivation();
+  }
+}
+
+/** Whether the snapshot-backed sink is currently registered by this owner. */
+export function jevQuotaActivationActive(): boolean { return active !== undefined; }
+
+let stopCurrent: (() => void) | undefined;
+
+/**
+ * Live-owner lifecycle, started by the server's optional-subsystem set once it is serving.
+ * Registers the live-config observer and reconciles once with the start-time config; the returned
+ * stop unregisters and deactivates. A second start replaces the first.
+ */
+export function startJevQuotaActivation(config: OcxConfig): () => void {
+  stopCurrent?.();
+  const unregister = registerLiveConfigObserver("jev-quota-activation", reconcileJevQuotaActivation);
+  const stop = () => {
+    if (stopCurrent !== stop) return;
+    stopCurrent = undefined;
+    unregister();
+    deactivateJevQuotaActivation();
+  };
+  stopCurrent = stop;
+  reconcileJevQuotaActivation(config);
+  return stop;
+}

package/src/combos/jev-quota-config.ts

@@ -0,0 +1,62 @@
+/** Import-free quota policy shared by config, CLI and telemetry. */
+export interface JevQuotaTiers {
+  moderate?: number;
+  limited?: number;
+  nearlyExhausted?: number;
+}
+export interface ResolvedJevQuotaTiers {
+  moderate?: number;
+  limited: number;
+  nearlyExhausted: number;
+}
+export const JEV_QUOTA_TIERS = ["unknown", "healthy", "moderate", "limited", "nearly_exhausted"] as const;
+export type JevQuotaTier = typeof JEV_QUOTA_TIERS[number];
+export const JEV_QUOTA_DEFAULT_TIERS: ResolvedJevQuotaTiers = { limited: 70, nearlyExhausted: 90 };
+/** Validate quota tier overrides and merge them with the defaults; return undefined for unknown keys, non-finite or out-of-range values, or thresholds that are not strictly ascending. */
+export function normalizeJevQuotaTiers(value: unknown): ResolvedJevQuotaTiers | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  if (Object.keys(raw).some(key => !["moderate", "limited", "nearlyExhausted"].includes(key))) return undefined;
+  if (Object.keys(raw).some(key => raw[key] === undefined)) return undefined;
+  const result = { ...JEV_QUOTA_DEFAULT_TIERS, ...raw };
+  const values = [result.moderate, result.limited, result.nearlyExhausted].filter(value => value !== undefined);
+  if (values.some(value => typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100)) return undefined;
+  if (Object.hasOwn(raw, "moderate") && raw.moderate === undefined) return undefined;
+  if (values.some((value, i) => i > 0 && value! <= values[i - 1]!)) return undefined;
+  return result as ResolvedJevQuotaTiers;
+}
+/** Map a used percentage to a quota tier using the thresholds; a non-finite or out-of-range percentage is unknown. */
+export function jevQuotaTier(percent: number, tiers: ResolvedJevQuotaTiers = JEV_QUOTA_DEFAULT_TIERS): JevQuotaTier {
+  if (!Number.isFinite(percent) || percent < 0 || percent > 100) return "unknown";
+  if (percent >= tiers.nearlyExhausted) return "nearly_exhausted";
+  if (percent >= tiers.limited) return "limited";
+  if (tiers.moderate !== undefined && percent >= tiers.moderate) return "moderate";
+  return "healthy";
+}
+/** Rank a quota tier for ordering; unknown ties healthy so missing evidence is never treated as exhausted. */
+export function jevQuotaRank(tier: JevQuotaTier): number {
+  return tier === "unknown" || tier === "healthy" ? 0 : tier === "moderate" ? 1 : tier === "limited" ? 2 : 3;
+}
+export interface JevQuotaDecisionSummary {
+  unknown: number;
+  healthy: number;
+  moderate: number;
+  limited: number;
+  nearly_exhausted: number;
+  selected?: JevQuotaTier;
+}
+/** Validate a persisted decision quota summary (bounded per-tier counts and an optional selected tier), returning undefined when it is malformed. */
+export function normalizeJevQuotaSummary(value: unknown): JevQuotaDecisionSummary | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  const result = { unknown: 0, healthy: 0, moderate: 0, limited: 0, nearly_exhausted: 0 };
+  let total = 0;
+  for (const tier of JEV_QUOTA_TIERS) {
+    const count = raw[tier];
+    if (typeof count !== "number" || !Number.isInteger(count) || count < 0 || count > 64) return undefined;
+    result[tier] = count; total += count;
+  }
+  if (total > 64) return undefined;
+  const selected = JEV_QUOTA_TIERS.find(tier => tier === raw.selected);
+  return { ...result, ...(selected ? { selected } : {}) };
+}

package/src/combos/jev-quota-route.ts

@@ -0,0 +1,26 @@
+import { jevQuotaDecisionSummary, jevQuotaSignalForTarget } from "./jev-quota";
+import { JEV_QUOTA_DEFAULT_TIERS, normalizeJevQuotaTiers } from "./jev-quota-config";
+import type { JevCandidate, JevDecision, ResolveJevDecisionOptions } from "./jev";
+/** Attach a loaded-only quota signal to each candidate when the combo opted in; otherwise return the candidates unchanged. */
+export function jevQuotaCandidates(options: ResolveJevDecisionOptions): readonly JevCandidate[] {
+  if (options.decisionQuotaSignals !== true) return options.candidates;
+  const tiers = normalizeJevQuotaTiers(options.decisionQuotaTiers) ?? JEV_QUOTA_DEFAULT_TIERS;
+  const now = (options.now ?? Date.now)();
+  return options.candidates.map(candidate => ({ ...candidate,
+    quota: jevQuotaSignalForTarget(options.config, candidate.provider, candidate.model, now, tiers) }));
+}
+/** Attach the per-tier quota summary to a decision when any candidate carried quota evidence. */
+export function withJevQuotaSummary(decision: JevDecision, candidates: readonly JevCandidate[]): JevDecision {
+  const quota = jevQuotaDecisionSummary(candidates, decision.targetKey);
+  return quota ? { ...decision, quota } : decision;
+}
+/** Retries serialization without quota, never truncates ordinary evidence or the allowlist. */
+export function boundedJevQuotaPayload(candidates: readonly JevCandidate[], build: (rows: readonly JevCandidate[]) => string, limit: number): { body: string; candidates: readonly JevCandidate[] } {
+  let rows = candidates;
+  let body = build(rows);
+  if (new TextEncoder().encode(body).byteLength > limit && rows.some(row => row.quota)) {
+    rows = rows.map(({ quota: _quota, ...row }) => row);
+    body = build(rows);
+  }
+  return { body, candidates: rows };
+}

package/src/combos/jev-quota.ts

@@ -0,0 +1,88 @@
+import { anthropicModelFamily } from "../oauth/anthropic-model-family";
+/** Advisory quota only: loaded snapshots, never serving-account selection or hard eligibility. */
+import { resolveAnthropicModelRoute, routeCandidates } from "../oauth/anthropic-model-routes";
+import type { OcxConfig } from "../types";
+import type { DecisionQuotaWindow } from "../providers/quota-decision-snapshot";
+import { readLoadedDecisionKeyQuota, readLoadedDecisionQuotaPool } from "../lib/decision-quota-sink";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers-destination";
+import { providerCodexAccountMode } from "../providers/registry";
+import { NATIVE_RESERVE_MODEL } from "../codex/catalog/native-models";
+import { isSelectableCodexPoolAccount, MAIN_CODEX_ACCOUNT_ID } from "../codex/account-id";
+import { JEV_QUOTA_DEFAULT_TIERS, jevQuotaRank, jevQuotaTier, type JevQuotaTier, type ResolvedJevQuotaTiers, type JevQuotaDecisionSummary } from "./jev-quota-config";
+export const JEV_QUOTA_SIGNAL_MAX_AGE_MS = 30 * 60_000;
+export interface JevQuotaSignal {
+  tier: JevQuotaTier;
+  usedPercent?: number;
+  window?: DecisionQuotaWindow["window"];
+  resetsInSeconds?: number;
+}
+/** Build the signal used when evidence is missing, stale or invalid; it ties healthy. */
+const unknown = (): JevQuotaSignal => ({ tier: "unknown" });
+/** Reduce decision quota windows to the worst applicable window for a model, ignoring cold, stale, future, invalid or reset-expired rows. */
+export function jevQuotaSignalFromWindows(windows: readonly DecisionQuotaWindow[] | undefined, model: string, now: number, tiers = JEV_QUOTA_DEFAULT_TIERS): JevQuotaSignal {
+  let worst: DecisionQuotaWindow | undefined;
+  for (const row of windows ?? []) {
+    if (!["5h", "weekly", "monthly"].includes(row.window) && anthropicModelFamily(model)?.toLowerCase() !== row.window) continue;
+    if (!Number.isFinite(now) || now < 0 || !Number.isFinite(row.observedAt) || row.observedAt < 0 || row.observedAt > now
+      || now - row.observedAt > JEV_QUOTA_SIGNAL_MAX_AGE_MS || !Number.isFinite(row.percent) || row.percent < 0 || row.percent > 100
+      || row.resetAt !== undefined && (!Number.isFinite(row.resetAt) || row.resetAt < 0 || row.resetAt <= now)) continue;
+    if (!worst || row.percent > worst.percent) worst = row;
+  }
+  if (!worst) return unknown();
+  return { tier: jevQuotaTier(worst.percent, tiers), usedPercent: worst.percent, window: worst.window,
+    ...(worst.resetAt !== undefined ? { resetsInSeconds: Math.min(31_536_000, Math.ceil((worst.resetAt - now) / 1000)) } : {}) };
+}
+/** Unknown ties healthy; stable order within tiers. Exhaustion requires EVERY usable row known. */
+export function jevQuotaPoolSignal(signals: readonly JevQuotaSignal[]): JevQuotaSignal {
+  return signals.reduce<JevQuotaSignal | undefined>((best, signal) => !best || jevQuotaRank(signal.tier) < jevQuotaRank(best.tier) ? signal : best, undefined) ?? unknown();
+}
+/** Read only already-loaded evidence for a target provider and model and return its quota signal; never resolves credentials or probes upstream. */
+export function jevQuotaSignalForTarget(config: OcxConfig, provider: string, model: string, now = Date.now(), tiers: ResolvedJevQuotaTiers = JEV_QUOTA_DEFAULT_TIERS): JevQuotaSignal {
+  const row = config.providers[provider];
+  if (!row || row.disabled) return unknown();
+  if (provider === "anthropic" && row.authMode === "oauth" && config.anthropicAccountPool?.enabled === true) {
+    const route = resolveAnthropicModelRoute(config, model);
+    if (route.error) return unknown();
+    const usable = (readLoadedDecisionQuotaPool("anthropic") ?? []).filter(account => account.usable);
+    const ids = new Set(routeCandidates(usable.map(account => account.id), route.decision));
+    return jevQuotaPoolSignal(usable.filter(account => ids.has(account.id)).map(account => jevQuotaSignalFromWindows(account.windows, model, now, tiers)));
+  }
+  if (isCanonicalOpenAiForwardProvider(row) && providerCodexAccountMode(provider, row) === "pool") {
+    if (model.toLowerCase().split("/").at(-1) === NATIVE_RESERVE_MODEL) return unknown();
+    const roster = readLoadedDecisionQuotaPool("codex");
+    if (!roster) return unknown();
+    const paused = new Set(config.pausedCodexAccountIds ?? []);
+    const ids = new Set((config.codexAccounts ?? []).filter(isSelectableCodexPoolAccount).map(account => account.id));
+    const loadedIds = new Set(roster.map(account => account.id));
+    const signals = roster.filter(account => account.usable && ids.has(account.id) && !paused.has(account.id))
+      .map(account => jevQuotaSignalFromWindows(account.windows, model, now, tiers));
+    for (const id of ids) if (!loadedIds.has(id) && !paused.has(id)) signals.push(unknown());
+    if (!paused.has(MAIN_CODEX_ACCOUNT_ID)) {
+      const main = readLoadedDecisionQuotaPool("codex-main")?.[0];
+      if (!main || main.usable) signals.push(jevQuotaSignalFromWindows(main?.windows, model, now, tiers));
+    }
+    return jevQuotaPoolSignal(signals);
+  }
+  return jevQuotaSignalFromWindows(readLoadedDecisionKeyQuota(provider, row), model, now, tiers);
+}
+/** Render the short natural-language quota clause appended to an option description. */
+export function jevQuotaClause(signal: JevQuotaSignal): string {
+  return ` Quota ${signal.tier}${signal.usedPercent !== undefined ? ` (${signal.usedPercent}% of ${signal.window} used)` : ""}.`;
+}
+/** Project a quota signal onto the outbound criterion object: tier, used percentage, window and reset delay only. */
+export function jevQuotaCriterion(signal: JevQuotaSignal): Record<string, unknown> {
+  return { tier: signal.tier, ...(signal.usedPercent !== undefined ? { used_percent: signal.usedPercent, window: signal.window } : {}),
+    ...(signal.resetsInSeconds !== undefined ? { resets_in_seconds: signal.resetsInSeconds } : {}) };
+}
+export const JEV_QUOTA_INSTRUCTION = "Remaining subscription quota is advisory: among adequate options prefer healthier quota; unknown is not exhausted. Never change the target or effort allowlist.";
+/** Count candidate quota tiers and record the selected candidate's tier; undefined when no candidate carried quota evidence. */
+export function jevQuotaDecisionSummary(candidates: readonly { key: string; quota?: JevQuotaSignal }[], selectedKey: string): JevQuotaDecisionSummary | undefined {
+  if (!candidates.some(candidate => candidate.quota)) return undefined;
+  const summary: JevQuotaDecisionSummary = { unknown: 0, healthy: 0, moderate: 0, limited: 0, nearly_exhausted: 0 };
+  for (const candidate of candidates) {
+    const tier = candidate.quota?.tier ?? "unknown";
+    summary[tier]++;
+    if (candidate.key === selectedKey) summary.selected = tier;
+  }
+  return summary;
+}

package/src/combos/jev.ts

@@ -1,3 +1,7 @@
+import { jevQuotaClause, jevQuotaCriterion, JEV_QUOTA_INSTRUCTION, type JevQuotaSignal } from "./jev-quota";
+import type { JevQuotaTiers, JevQuotaDecisionSummary } from "./jev-quota-config";
+import { boundedJevQuotaPayload, jevQuotaCandidates, withJevQuotaSummary } from "./jev-quota-route";
+import { JEV_MAX_REQUEST_BYTES as REQUEST_LIMIT } from "./jev-service-exchange";
 import type { providerOutboundPost } from "../lib/provider-outbound";
 import type { OcxComboDefaultEffort, OcxConfig } from "../types";
 import {
@@ -75,6 +79,7 @@ export interface JevCandidate {
   reasoningEfforts: readonly OcxComboDefaultEffort[];
   /** Optional operator note sent as decision evidence for this target only. */
   modelProfile?: string;
+  quota?: JevQuotaSignal;
 }
 
 /**
@@ -98,6 +103,7 @@ export interface JevDecision {
   effort: OcxComboDefaultEffort | null;
   gate: "apply" | "missing_key" | "no_choices" | "no_state" | "timeout" | "network" | "redirect" | "http" | "malformed" | "invalid";
   latencyMs: number;
+  quota?: JevQuotaDecisionSummary;
   confidence?: number;
   chosenProbability?: number;
   usage?: Record<string, number>;
@@ -113,6 +119,8 @@ export interface ResolveJevDecisionOptions {
    * any other id names a configured `jev-decision` row (for example a self-hosted Ollama `tev1`).
    */
   decisionProvider?: string;
+  decisionQuotaSignals?: boolean;
+  decisionQuotaTiers?: JevQuotaTiers;
   /** Request-local authorization of the concrete decision destination, before credential access. */
   isDestinationAllowed?: (providerName: string, modelId: string) => boolean;
   /** Decision deadline; values outside 1000..120000 ms keep the four-second default. */
@@ -477,11 +485,12 @@ function modelProfile(candidate: JevCandidate): string {
     ?? "Configured target with capability unspecified by JEV; judge it only from the supplied request evidence.";
 }
 
-function criterionDescription(criterion: JevRouteOption["criterion"]): string {
+/** Describe one allowlisted target and effort option for a decision backend, including the optional advisory quota clause. */
+function criterionDescription(criterion: JevRouteOption["criterion"], quota?: JevQuotaSignal): string {
   const effort = criterion.reasoning_effort
     ? `${criterion.reasoning_effort} reasoning effort`
     : "no reasoning-effort control";
-  return `Target ${criterion.target} (provider ${criterion.provider}, model ${criterion.model}) with ${effort}.`;
+  return `Target ${criterion.target} (provider ${criterion.provider}, model ${criterion.model}) with ${effort}.${quota ? jevQuotaClause(quota) : ""}`;
 }
 
 /** One allowlisted target/effort option, shared by every decision backend. */
@@ -498,7 +507,7 @@ export function jevRouteOptions(candidates: readonly JevCandidate[]): JevRouteOp
     key,
     targetKey: option.targetKey,
     effort: option.effort,
-    description: criterionDescription(option.criterion),
+    description: criterionDescription(option.criterion, candidates.find(candidate => candidate.key === option.targetKey)?.quota),
   }));
 }
 
@@ -516,7 +525,8 @@ export function buildJevRouteQuestion(
   const routeOptions = candidateOptions(candidates);
   const criteria: Record<string, unknown> = {};
   for (const [choice, option] of routeOptions) {
-    criteria[choice] = options.descriptiveCriteria ? criterionDescription(option.criterion) : option.criterion;
+    const quota = candidates.find(candidate => candidate.key === option.targetKey)?.quota;
+    criteria[choice] = options.descriptiveCriteria ? criterionDescription(option.criterion, quota) : { ...option.criterion, ...(quota ? { quota: jevQuotaCriterion(quota) } : {}) };
   }
   const modelProfiles: Record<string, string> = {};
   for (const candidate of candidates) modelProfiles[candidate.key] = modelProfile(candidate);
@@ -531,6 +541,7 @@ export function buildJevRouteQuestion(
         model_profiles: modelProfiles,
         effort_profiles: EFFORT_PROFILES,
         speed: "Every option uses standard speed. Fast mode is unavailable.",
+        ...(candidates.some(candidate => candidate.quota) ? { quota: JEV_QUOTA_INSTRUCTION } : {}),
       },
       criteria,
     },
@@ -628,6 +639,7 @@ export async function resolveJevDecision(options: ResolveJevDecisionOptions): Pr
   if (options.candidates.length === 0) return failed("no_choices");
   if (!candidatesFitRequestBounds(options.candidates)) return failed("invalid");
 
+  let candidates = options.candidates;
   const exchanged = await exchangeJevDecision(options, (endpoint) => {
     if (endpoint.descriptiveCriteria) {
       // Self-hosted choice questions accept 2..26 options; decide locally instead of spending a
@@ -638,19 +650,20 @@ export async function resolveJevDecision(options: ResolveJevDecisionOptions): Pr
     }
     const state = buildJevState(options.body, options.candidates);
     if (!hasJevDecisionState(state)) return "no_state";
-    return { body: JSON.stringify({
-      model: endpoint.model,
-      state,
-      questions: buildJevRouteQuestion(options.candidates, { descriptiveCriteria: endpoint.descriptiveCriteria }),
-    }) };
+    const payload = boundedJevQuotaPayload(jevQuotaCandidates(options), rows => JSON.stringify({
+      model: endpoint.model, state,
+      questions: buildJevRouteQuestion(rows, { descriptiveCriteria: endpoint.descriptiveCriteria }),
+    }), REQUEST_LIMIT);
+    candidates = payload.candidates;
+    return { body: payload.body };
   }, (payload) => parseJevDecision(payload, options.candidates));
-  if ("gate" in exchanged) return failed(exchanged.gate);
-  return {
+  if ("gate" in exchanged) return withJevQuotaSummary(failed(exchanged.gate), candidates);
+  return withJevQuotaSummary({
     backend,
     ...exchanged.value,
     gate: "apply",
     latencyMs: Math.max(0, now() - startedAt),
-  };
+  }, candidates);
 }
 
 export type JevDecisionProbeResult =