feat(oauth): model-family aware quota headroom ranking and failover

scripts/test-layout/layout.json

@@ -952,6 +952,7 @@
     "nvidia-nim-hardening.test.ts": "providers",
     "oauth-account-attribution.test.ts": "oauth",
     "oauth-account-id-collision.test.ts": "oauth",
+    "oauth-account-quota-rank.test.ts": "oauth",
     "oauth-accounts-api.test.ts": "oauth",
     "oauth-callback-binds.test.ts": "oauth",
     "oauth-callback-server.test.ts": "oauth",

src/oauth/account-quota-rank.ts

@@ -45,23 +45,42 @@ interface Ranked {
  */
 const PASSIVE_HEADROOM_MAX_AGE_MS = 60 * 60_000;
 
+/**
+ * Map a requested model ID to the Antigravity quota-window family prefix.
+ * Returns "Gem" for Gemini models, "Cla" for Claude/Opus/Sonnet, or undefined
+ * for unknown models (which falls back to all-window ranking).
+ */
+function classifyModelFamilyForQuota(modelId: string): "Gem" | "Cla" | undefined {
+  const lower = modelId.toLowerCase();
+  if (lower.includes("gemini")) return "Gem";
+  if (lower.includes("claude") || lower.includes("opus") || lower.includes("sonnet") || lower.includes("gpt-oss") || lower.includes("gpt_oss")) return "Cla";
+  return undefined;
+}
+
 /**
  * Remaining headroom across every window the provider reports.
  *
  * The minimum wins: an account at 5% of its five-hour window is unusable right now even if
  * its monthly allowance is barely touched.
  */
-function headroomOf(provider: string, accountId: string): number | null {
+function headroomOf(provider: string, accountId: string, requestedModelId?: string): number | null {
   const quota = getCachedProviderAccountQuota(provider, accountId);
   if (!quota) return null;
   // Null, not a low rank: this must reproduce "no evidence" so a stale roster degrades to
   // the unranked ring rather than to a differently wrong answer.
   if (hasPassiveAccountQuota(provider) && Date.now() - quota.updatedAt > PASSIVE_HEADROOM_MAX_AGE_MS) return null;
+
+  const familyPrefix = provider === "google-antigravity" && requestedModelId
+    ? classifyModelFamilyForQuota(requestedModelId)
+    : undefined;
+
   const percents = [
     quota.fiveHourPercent,
     quota.weeklyPercent,
     quota.monthlyPercent,
-    ...(quota.customWindows ?? []).map(window => window.percent),
+    ...(quota.customWindows ?? [])
+      .filter(window => !familyPrefix || window.label.startsWith(familyPrefix))
+      .map(window => window.percent),
   ].filter((value): value is number => typeof value === "number");
   if (percents.length === 0) return null;
   return 100 - Math.max(...percents);
@@ -79,10 +98,10 @@ export function accountHeadroomPercent(provider: string, accountId: string): num
 }
 
 /** Unknown usage is not exhaustion; Kiro's explicit overage verdict is authoritative. */
-export function isAccountQuotaExhausted(provider: string, accountId: string): boolean {
+export function isAccountQuotaExhausted(provider: string, accountId: string, requestedModelId?: string): boolean {
   const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${accountId}`) : null;
   if (exhaustion !== null) return exhaustion.exhausted;
-  const headroom = headroomOf(provider, accountId);
+  const headroom = headroomOf(provider, accountId, requestedModelId);
   return headroom !== null && headroom <= 0;
 }
 
@@ -92,24 +111,28 @@ export function isAccountQuotaExhausted(provider: string, accountId: string): bo
  * Returns the input untouched when no candidate has quota evidence, which keeps every
  * provider without per-account quota on exactly the behaviour it has today.
  */
-export function rankAccountsByHeadroom(provider: string, ring: readonly string[]): string[] {
+export function rankAccountsByHeadroom(
+  provider: string,
+  ring: readonly string[],
+  requestedModelId?: string,
+): string[] {
   if (ring.length < 2) return [...ring];
 
   let sawEvidence = false;
   // Same rule as hasHeadroomEvidence: a passive provider's partial roster must not rank
   // at all. The failover path calls this directly (selectFailoverAccount), so the guard
   // cannot live only in the pre-dispatch predicate.
-  if (hasPassiveAccountQuota(provider) && !ring.every(id => headroomOf(provider, id) !== null)) {
+  if (hasPassiveAccountQuota(provider) && !ring.every(id => headroomOf(provider, id, requestedModelId) !== null)) {
     return [...ring];
   }
   const ranked: Ranked[] = ring.map((id, index) => {
     // A provider-declared exhaustion verdict outranks the percentage: an account may sit at
     // 100% and still be servable when overage is enabled, and the verdict knows that.
     const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${id}`) : null;
-    const headroom = headroomOf(provider, id);
+    const headroom = headroomOf(provider, id, requestedModelId);
     if (exhaustion !== null || headroom !== null) sawEvidence = true;
 
-    if (isAccountQuotaExhausted(provider, id)) return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
+    if (isAccountQuotaExhausted(provider, id, requestedModelId)) return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
     if (headroom === null) return { id, bucket: RANK_UNKNOWN, headroom: 0, index };
     return { id, bucket: RANK_HEALTHY, headroom, index };
   });
@@ -129,7 +152,7 @@ export function rankAccountsByHeadroom(provider: string, ring: readonly string[]
  * told "ranked" when nothing was measured. Pre-dispatch selection asks this first so it
  * can decline to act on a roster it knows nothing about.
  */
-export function hasHeadroomEvidence(provider: string, ids: readonly string[]): boolean {
+export function hasHeadroomEvidence(provider: string, ids: readonly string[], requestedModelId?: string): boolean {
   // A PASSIVE provider needs evidence for EVERY candidate, not any one of them.
   //
   // A probe fills the whole roster in one pass (fetchProviderAccountQuotas), so "any"
@@ -140,10 +163,10 @@ export function hasHeadroomEvidence(provider: string, ids: readonly string[]): b
   // AWAY from an unmeasured account and TOWARD the one account known to be spent, which
   // is the exact inversion of what ranking is for.
   if (hasPassiveAccountQuota(provider)) {
-    return ids.length > 0 && ids.every(id => headroomOf(provider, id) !== null);
+    return ids.length > 0 && ids.every(id => headroomOf(provider, id, requestedModelId) !== null);
   }
   return ids.some(id =>
-    headroomOf(provider, id) !== null
+    headroomOf(provider, id, requestedModelId) !== null
     || (provider === "kiro" && getKiroAccountExhaustion(`${provider}\u0000${id}`) !== null));
 }
 /**

src/oauth/generic-account-failover.ts

@@ -302,6 +302,7 @@ export function rotateGenericOAuthAccountOn429(
   failedAccountId: string,
   retryAfterHeader: string | null | undefined,
   now = Date.now(),
+  requestedModelId?: string,
 ): string | null {
   if (!isGenericOAuthFailoverEnabled(config, providerName)) return null;
   const set = getAccountSet(providerName);
@@ -359,7 +360,7 @@ export function rotateGenericOAuthAccountOn429(
   }
   // With no quota evidence this returns the ring untouched, so providers without
   // per-account quota keep exactly the traversal they have today.
-  return rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
+  return rankAccountsByHeadroom(providerName, candidates, requestedModelId)[0] ?? null;
 }
 
 /**
@@ -392,6 +393,7 @@ export function preferredInitialAccount(
   config: OcxConfig,
   providerName: string,
   now = Date.now(),
+  requestedModelId?: string,
 ): string | null {
   // The PROACTIVE predicate, not the reactive one: this steers a request upstream has not
   // refused, so `oauthAccountFailover.enabled: false` must still be able to refuse it.
@@ -430,14 +432,14 @@ export function preferredInitialAccount(
   const activeRow = selected.accounts.find(account => account.id === active);
   if (activeRow && activeRow.needsReauth !== true
     && !isCooled(providerName, activeRow.id, now)
-    && !isAccountQuotaExhausted(providerName, activeRow.id)) return null;
+    && !isAccountQuotaExhausted(providerName, activeRow.id, requestedModelId)) return null;
 
   // Evidence is required BEFORE eligibility narrows the field. Without this, a provider
   // with no quota data at all could still be redirected: cool the active account with a
   // 429 and the eligible list collapses to one candidate, which any ranking returns
   // unchanged — an answer that looks ranked but was never measured. The no-op guarantee
   // for quota-less providers has to be checked on the full roster.
-  if (!hasHeadroomEvidence(providerName, order)) return null;
+  if (!hasHeadroomEvidence(providerName, order, requestedModelId)) return null;
 
   // Cooldowns are respected here, unlike in the presence count: this picks the account to
   // send to right now, and one inside its 429 window is the single candidate we hold
@@ -451,7 +453,7 @@ export function preferredInitialAccount(
   const candidates = ring.filter(id => eligible.includes(id));
   if (candidates.length === 0) return null;
 
-  const best = rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
+  const best = rankAccountsByHeadroom(providerName, candidates, requestedModelId)[0] ?? null;
   // Nothing to do when the ranking agrees with the account we would have used anyway.
   //
   // A proposal still needs guarded selection commit after credential resolution: a

src/server/responses/adapter-continuation.ts

@@ -395,6 +395,8 @@ export function createAdapterContinuations(
             route.providerName,
             transportState.genericFailoverAccountId,
             response.headers.get("retry-after"),
+            Date.now(),
+            route.modelId,
           )
           : null;
         if (!nextAccountId) hop.permit?.release();

src/server/responses/adapter-dispatch.ts

@@ -732,6 +732,8 @@ export async function prepareAdapterExchange(
           route.providerName,
           transportState.genericFailoverAccountId,
           upstreamResponse.headers.get("retry-after"),
+          Date.now(),
+          route.modelId,
         );
         if (!nextAccountId) {
           hop.permit?.release();

src/server/responses/passthrough-dispatch.ts

@@ -1121,6 +1121,8 @@ export async function preparePassthroughExchange(
         const nextAccountId = rotateGenericOAuthAccountOn429(
           config, route.providerName, transportState.genericFailoverAccountId,
           upstreamResponse.headers.get("retry-after"),
+          Date.now(),
+          route.modelId,
         );
         let snapshot: OAuthAccessSnapshot | undefined;
         if (nextAccountId) {

src/server/responses/request-transport.ts

@@ -431,7 +431,7 @@ export async function prepareResponsesTransport(
         // measured as spent. A null answer means "use the active account", so every provider
         // without quota evidence keeps the resolution it has today.
         const preferredAccountId = isGenericFailoverProvider(route.providerName, route.provider)
-          ? preferredInitialAccount(config, route.providerName)
+          ? preferredInitialAccount(config, route.providerName, Date.now(), route.modelId)
           : null;
         // Resolved account-scoped, NOT through failoverAccountSnapshot: that helper marks a
         // rotation site, and rotation sites must apply their credential through

src/server/responses/run-turn-execution.ts

@@ -214,6 +214,8 @@ export async function executeResponsesRunTurn(
         route.providerName,
         transportState.genericFailoverAccountId,
         null,
+        Date.now(),
+        route.modelId,
       );
       if (!nextAccountId) {
         hop.permit?.release();

src/server/responses/sidecar-execution.ts

@@ -184,6 +184,8 @@ export async function executeResponsesSidecars(
         route.providerName,
         transportState.genericFailoverAccountId,
         retryAfter,
+        Date.now(),
+        route.modelId,
       );
       if (!nextAccountId) {
         hop.permit?.release();

structure/transports/inventory.md

@@ -148,3 +148,14 @@ Renamed fixed-key providers receive [missing reasoning metadata](../catalog.md#r
 
 Translated audio/file admission follows the [final-adapter input contract](../adapters/registry.md#untranslated-input-media); native raw passthrough remains separate.
 Canonical Responses identity sanitation and narrowly scoped pre-output combo recovery follow [request-local target compatibility](../runtime.md#request-local-target-compatibility); other adapter contracts remain unchanged.
+
+## Model-family-aware OAuth headroom
+
+`src/oauth/account-quota-rank.ts` ranks Antigravity custom windows for the requested
+Gemini or Claude family, including GPT-OSS in the Claude family. An unknown model
+retains all-window ranking; absent matching evidence retains the existing unranked behavior.
+`src/server/responses/request-transport.ts` passes the routed model at initial selection.
+The passthrough, adapter, continuation, sidecar and run-turn execution owners pass
+the same routed model during account rotation, without bypassing their send-budget
+admission or account-snapshot pairing. The forwarding contract is covered in
+`tests/oauth/oauth-account-quota-rank.test.ts`; the core facade remains orchestration-only.

tests/fixtures/test-layout-expected.json

@@ -780,6 +780,7 @@
   "nvidia-nim-hardening.test.ts": "providers",
   "oauth-account-attribution.test.ts": "oauth",
   "oauth-account-id-collision.test.ts": "oauth",
+  "oauth-account-quota-rank.test.ts": "oauth",
   "oauth-accounts-api.test.ts": "oauth",
   "oauth-callback-binds.test.ts": "oauth",
   "oauth-callback-server.test.ts": "oauth",