@bitkyc08/opencodex 2.87.0 → 2.89.0

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 =

package/src/combos/types.ts

@@ -1,3 +1,4 @@
+import { normalizeJevQuotaTiers, type ResolvedJevQuotaTiers } from "./jev-quota-config";
 import { isCodexReasoningEffort, isDeclaredReasoningEffort } from "../reasoning-effort";
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
 import type { OcxComboConfig, OcxComboCooldownWaitPolicy, OcxComboDefaultEffort, OcxComboDefaultEffortMode, OcxComboReasoningEffortMode, OcxComboStrategy, OcxComboTarget, OcxProviderConfig } from "../types";
@@ -68,12 +69,16 @@ export interface NormalizedComboConfig {
   nativeAlias: boolean;
   /** Display-only label for the catalog row, or null when unset. */
   displayName: string | null;
+  /** Display-only catalog row description; absent keeps the generated text (#7229). */
+  description?: string;
   /** JEV decision service provider id; absent means the canonical `jev` service. */
   decisionProvider?: string;
   /** Ordinary inference route used for JEV decisions. */
   decisionModel?: string;
   /** JEV decision deadline override; absent keeps the default four-second deadline. */
   decisionTimeoutMs?: number;
+  decisionQuotaSignals?: boolean;
+  decisionQuotaTiers?: ResolvedJevQuotaTiers;
   targets: NormalizedComboTarget[];
 }
 
@@ -137,6 +142,7 @@ export interface ComboValidationOptions {
   excludeComboId?: string;
 }
 
+/** Validate a raw combo definition against the configured providers and return every issue found, without mutating the input. */
 export function comboConfigIssues(
   id: string,
   raw: unknown,
@@ -277,6 +283,16 @@ export function comboConfigIssues(
       });
     }
   }
+  if (body.description !== undefined) {
+    if (typeof body.description !== "string") {
+      issues.push({ path: ["description"], message: "description must be a string" });
+    } else if (body.description.trim().length > 128 || /\p{Cc}/u.test(body.description)) {
+      issues.push({
+        path: ["description"],
+        message: "description must be at most 128 characters and contain no control characters",
+      });
+    }
+  }
   const alias = typeof body.alias === "string" ? body.alias.trim() : "";
   const nativeAlias = body.nativeAlias === true;
   if (nativeAlias && !SUPPORTED_NATIVE_OPENAI_SLUGS.has(alias)) {
@@ -288,6 +304,12 @@ export function comboConfigIssues(
   if (nativeAlias && (typeof body.displayName !== "string" || body.displayName.trim().length === 0)) {
     issues.push({ path: ["displayName"], message: "displayName is required for native aliases" });
   }
+  for (const field of ["decisionQuotaSignals", "decisionQuotaTiers"] as const) {
+    if (body[field] === undefined || body[field] === null) continue;
+    if (body.strategy !== "jev") issues.push({ path: [field], message: `${field} is only valid with strategy "jev"` });
+    if (field === "decisionQuotaSignals" ? typeof body[field] !== "boolean" : !normalizeJevQuotaTiers(body[field]))
+      issues.push({ path: [field], message: field === "decisionQuotaSignals" ? "decisionQuotaSignals must be a boolean" : "decisionQuotaTiers must contain finite 0..100 strictly ascending thresholds" });
+  }
   if (body.decisionProvider !== undefined && body.decisionProvider !== null) {
     const decisionProvider = typeof body.decisionProvider === "string" ? body.decisionProvider.trim() : "";
     if (!decisionProvider) {
@@ -480,9 +502,11 @@ export function comboConfigError(
   return comboConfigIssues(id, raw, providers, options)[0]?.message ?? null;
 }
 
+/** Normalize a validated combo definition into its canonical form: trimmed strings, defaults and the opt-in quota signal fields. */
 export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig {
   const alias = typeof raw.alias === "string" ? raw.alias.trim() : "";
   const displayName = typeof raw.displayName === "string" ? raw.displayName.trim() : "";
+  const description = typeof raw.description === "string" ? raw.description.trim() : "";
   const decisionProvider = typeof raw.decisionProvider === "string" ? raw.decisionProvider.trim() : "";
   const decisionModel = typeof raw.decisionModel === "string" ? raw.decisionModel.trim() : "";
   const defaultEffort = typeof raw.defaultEffort === "string" && isCodexReasoningEffort(raw.defaultEffort)
@@ -502,10 +526,13 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
     alias: alias || null,
     nativeAlias: raw.nativeAlias === true,
     displayName: displayName || null,
+    ...(description ? { description } : {}),
     // Explicit "jev" is the default and stays sparse.
     ...(decisionProvider && decisionProvider !== CANONICAL_JEV_DECISION_PROVIDER ? { decisionProvider } : {}),
     ...(decisionModel ? { decisionModel } : {}),
     ...(typeof raw.decisionTimeoutMs === "number" ? { decisionTimeoutMs: raw.decisionTimeoutMs } : {}),
+    ...(raw.strategy === "jev" && raw.decisionQuotaSignals === true ? { decisionQuotaSignals: true } : {}),
+    ...(raw.strategy === "jev" && normalizeJevQuotaTiers(raw.decisionQuotaTiers) ? { decisionQuotaTiers: normalizeJevQuotaTiers(raw.decisionQuotaTiers)! } : {}),
     targets: raw.targets.map(target => ({
       provider: target.provider.trim(),
       model: target.model.trim(),

package/src/compatibility/index.ts

@@ -1,4 +1,5 @@
 import { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+import { OPENGATEWAY_KEY_GLM53_RESPONSES_MANIFEST } from "./opengateway-responses";
 import type { CompatibilityManifestV1 } from "./manifest";
 
 export {
@@ -16,9 +17,11 @@ export type {
   CompatibilitySubjectV1,
 } from "./manifest";
 export { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+export { OPENGATEWAY_KEY_GLM53_RESPONSES_MANIFEST } from "./opengateway-responses";
 
 export const COMPATIBILITY_MANIFESTS: readonly CompatibilityManifestV1[] = Object.freeze([
   OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST,
+  OPENGATEWAY_KEY_GLM53_RESPONSES_MANIFEST,
 ]);
 
 export function getCompatibilityManifest(id: string): CompatibilityManifestV1 | undefined {

package/src/compatibility/openai-responses.ts

@@ -9,7 +9,7 @@ const FIXTURE_ID = "openai-codex-forward-gpt56-sol-v1";
 export const OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST = defineCompatibilityManifest({
   schemaVersion: 1,
   id: "openai.codex-forward.gpt-5-6-sol.responses",
-  version: "1.3.0",
+  version: "1.4.0",
   subject: {
     providerId: "openai",
     baseUrl: "https://chatgpt.com/backend-api/codex",
@@ -117,5 +117,12 @@ export const OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST = defineCompatibilityManife
       limitation: "The field is removed only for the canonical forward destination; public and custom Responses providers keep it.",
       evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["prompt-cache-options-removed"] }],
     },
+    {
+      id: "custom-tool-grammar",
+      feature: "request.custom_tools.grammar",
+      disposition: "passthrough",
+      summary: "A custom tool's grammar format, including its definition, reaches the backend unchanged.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["custom-tool-grammar-preserved"] }],
+    },
   ],
 } as const);

package/src/compatibility/opengateway-responses.ts

@@ -0,0 +1,61 @@
+import { defineCompatibilityManifest } from "./manifest";
+
+const FIXTURE_ID = "opengateway-key-glm53-responses-v1";
+
+/**
+ * A routed Responses subject whose destination rejects native custom tools, so OpenCodex lowers
+ * them to functions before dispatch. The claims describe that local wire transformation only;
+ * they do not certify how the upstream model treats the lowered declaration.
+ */
+export const OPENGATEWAY_KEY_GLM53_RESPONSES_MANIFEST = defineCompatibilityManifest({
+  schemaVersion: 1,
+  id: "opengateway.key.glm-5-3-flash-ultrafast.responses",
+  version: "1.0.0",
+  subject: {
+    providerId: "opengateway",
+    baseUrl: "https://apis.opengateway.ai/v1",
+    adapterId: "openai-responses",
+    authMode: "key",
+    inboundProtocol: "responses",
+    upstreamProtocol: "openai-responses",
+    modelIds: ["z-ai/glm-5.3-flash-ultrafast"],
+  },
+  claims: [
+    {
+      id: "custom-tools",
+      feature: "request.custom_tools",
+      disposition: "translated",
+      summary: "Custom tool declarations are sent as functions that take one raw string input.",
+      limitation: "The destination rejects native custom tools, so each declaration is lowered to a function with a single required string parameter named input.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["custom-tool-lowered-to-function"] }],
+    },
+    {
+      id: "custom-tool-grammar",
+      feature: "request.custom_tools.grammar",
+      disposition: "degraded",
+      summary: "The tool and its description survive, but its grammar does not reach the destination.",
+      limitation: "The format, including any grammar definition, is removed during lowering, so the upstream model is not constrained by it; only the string input type remains.",
+      evidence: [{
+        kind: "fixture",
+        id: FIXTURE_ID,
+        assertionIds: ["custom-tool-grammar-removed", "custom-tool-lowered-to-function"],
+      }],
+    },
+    {
+      id: "custom-tool-call-history",
+      feature: "continuation.custom_tool_call",
+      disposition: "translated",
+      summary: "Replayed custom tool calls are sent as function calls with the same call_id and name.",
+      limitation: "The raw input is wrapped as the JSON arguments object {\"input\": <raw input>}.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["custom-tool-call-lowered"] }],
+    },
+    {
+      id: "custom-tool-output-history",
+      feature: "continuation.custom_tool_call_output",
+      disposition: "translated",
+      summary: "Replayed custom tool outputs are sent as function call outputs with the same call_id and output.",
+      limitation: "Only the item type changes from custom_tool_call_output to function_call_output.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["custom-tool-output-lowered"] }],
+    },
+  ],
+} as const);