Skip to content

Commit 00dc6a3

Browse files
feat(oauth): rank Antigravity failover by Gemini vs Claude quota family
Co-authored-by: chilung <[email protected]>
1 parent 41f1832 commit 00dc6a3

13 files changed

Lines changed: 525 additions & 82 deletions

‎scripts/test-layout/layout.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -970,6 +970,7 @@
970970
"nvidia-nim-hardening.test.ts": "providers",
971971
"oauth-account-attribution.test.ts": "oauth",
972972
"oauth-account-id-collision.test.ts": "oauth",
973+
"oauth-account-quota-rank.test.ts": "oauth",
973974
"oauth-accounts-api.test.ts": "oauth",
974975
"oauth-callback-binds.test.ts": "oauth",
975976
"oauth-callback-server.test.ts": "oauth",

‎src/oauth/account-quota-rank.ts‎

Lines changed: 72 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,38 @@
1313
import { getCachedProviderAccountQuota, hasPassiveAccountQuota } from "../providers/quota";
1414
import { getKiroAccountExhaustion } from "../providers/kiro-usage";
1515

16+
/** Antigravity hosts Gemini and Claude windows on one account; ranking must not mix them. */
17+
export type QuotaModelFamily = "gem" | "cla";
18+
19+
export function classifyModelFamilyForQuota(
20+
provider: string,
21+
modelId?: string | null,
22+
): QuotaModelFamily | undefined {
23+
if (provider !== "google-antigravity" || typeof modelId !== "string" || !modelId.trim()) {
24+
return undefined;
25+
}
26+
const id = modelId.toLowerCase();
27+
// Gemma is not Gemini: a substring/prefix match would poison Gemini ranking.
28+
if (/(?:^|[^a-z])gemma(?:[^a-z]|$)/.test(id)) return undefined;
29+
// Catalog ids are gemini-*, never a bare gem- token. Window labels still match Gem via
30+
// windowMatchesFamily; this classifier is only for request model ids.
31+
if (/(?:^|[^a-z])gemini(?:[^a-z]|$)/.test(id)) return "gem";
32+
if (
33+
/(?:^|[^a-z])claude(?:[^a-z]|$)/.test(id)
34+
|| /(?:^|[^a-z])opus(?:[^a-z]|$)/.test(id)
35+
|| /(?:^|[^a-z])sonnet(?:[^a-z]|$)/.test(id)
36+
|| /(?:^|[^a-z])haiku(?:[^a-z]|$)/.test(id)
37+
|| /(?:^|[^a-z])gpt[-_]oss(?:[^a-z]|$)/.test(id)
38+
) return "cla";
39+
return undefined;
40+
}
41+
42+
function windowMatchesFamily(label: string, family: QuotaModelFamily): boolean {
43+
const token = label.trim().split(/[\s(/]+/)[0] ?? "";
44+
if (family === "gem") return /^gem(?:ini)?$/i.test(token);
45+
return /^cla(?:ude)?$/i.test(token);
46+
}
47+
1648
/** Lower sorts earlier. Unknown sits between measured-healthy and measured-empty. */
1749
const RANK_HEALTHY = 0;
1850
const RANK_UNKNOWN = 1;
@@ -48,15 +80,24 @@ const PASSIVE_HEADROOM_MAX_AGE_MS = 60 * 60_000;
4880
/**
4981
* Remaining headroom across every window the provider reports.
5082
*
51-
* The minimum wins: an account at 5% of its five-hour window is unusable right now even if
52-
* its monthly allowance is barely touched.
53-
*/
54-
function headroomOf(provider: string, accountId: string): number | null {
83+
* The minimum wins: an account at 5% of its five-hour window is unusable right now even if
84+
* its monthly allowance is barely touched.
85+
*/
86+
function headroomOf(provider: string, accountId: string, requestedModelId?: string | null): number | null {
5587
const quota = getCachedProviderAccountQuota(provider, accountId);
5688
if (!quota) return null;
5789
// Null, not a low rank: this must reproduce "no evidence" so a stale roster degrades to
5890
// the unranked ring rather than to a differently wrong answer.
5991
if (hasPassiveAccountQuota(provider) && Date.now() - quota.updatedAt > PASSIVE_HEADROOM_MAX_AGE_MS) return null;
92+
const family = classifyModelFamilyForQuota(provider, requestedModelId);
93+
if (family) {
94+
const percents = (quota.customWindows ?? [])
95+
.filter(window => windowMatchesFamily(window.label, family))
96+
.map(window => window.percent)
97+
.filter((value): value is number => typeof value === "number");
98+
if (percents.length === 0) return null;
99+
return 100 - Math.max(...percents);
100+
}
60101
const percents = [
61102
quota.fiveHourPercent,
62103
quota.weeklyPercent,
@@ -74,15 +115,23 @@ function headroomOf(provider: string, accountId: string): number | null {
74115
* than an ordering. Null stays null all the way out: a caller must decide what "unmeasured"
75116
* means for its own rule instead of being handed a fabricated 0 or 100.
76117
*/
77-
export function accountHeadroomPercent(provider: string, accountId: string): number | null {
78-
return headroomOf(provider, accountId);
118+
export function accountHeadroomPercent(
119+
provider: string,
120+
accountId: string,
121+
requestedModelId?: string | null,
122+
): number | null {
123+
return headroomOf(provider, accountId, requestedModelId);
79124
}
80125

81126
/** Unknown usage is not exhaustion; Kiro's explicit overage verdict is authoritative. */
82-
export function isAccountQuotaExhausted(provider: string, accountId: string): boolean {
127+
export function isAccountQuotaExhausted(
128+
provider: string,
129+
accountId: string,
130+
requestedModelId?: string | null,
131+
): boolean {
83132
const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${accountId}`) : null;
84133
if (exhaustion !== null) return exhaustion.exhausted;
85-
const headroom = headroomOf(provider, accountId);
134+
const headroom = headroomOf(provider, accountId, requestedModelId);
86135
return headroom !== null && headroom <= 0;
87136
}
88137

@@ -92,24 +141,28 @@ export function isAccountQuotaExhausted(provider: string, accountId: string): bo
92141
* Returns the input untouched when no candidate has quota evidence, which keeps every
93142
* provider without per-account quota on exactly the behaviour it has today.
94143
*/
95-
export function rankAccountsByHeadroom(provider: string, ring: readonly string[]): string[] {
144+
export function rankAccountsByHeadroom(
145+
provider: string,
146+
ring: readonly string[],
147+
requestedModelId?: string | null,
148+
): string[] {
96149
if (ring.length < 2) return [...ring];
97150

98151
let sawEvidence = false;
99152
// Same rule as hasHeadroomEvidence: a passive provider's partial roster must not rank
100153
// at all. The failover path calls this directly (selectFailoverAccount), so the guard
101154
// cannot live only in the pre-dispatch predicate.
102-
if (hasPassiveAccountQuota(provider) && !ring.every(id => headroomOf(provider, id) !== null)) {
155+
if (hasPassiveAccountQuota(provider) && !ring.every(id => headroomOf(provider, id, requestedModelId) !== null)) {
103156
return [...ring];
104157
}
105158
const ranked: Ranked[] = ring.map((id, index) => {
106159
// A provider-declared exhaustion verdict outranks the percentage: an account may sit at
107160
// 100% and still be servable when overage is enabled, and the verdict knows that.
108161
const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${id}`) : null;
109-
const headroom = headroomOf(provider, id);
162+
const headroom = headroomOf(provider, id, requestedModelId);
110163
if (exhaustion !== null || headroom !== null) sawEvidence = true;
111164

112-
if (isAccountQuotaExhausted(provider, id)) return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
165+
if (isAccountQuotaExhausted(provider, id, requestedModelId)) return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
113166
if (headroom === null) return { id, bucket: RANK_UNKNOWN, headroom: 0, index };
114167
return { id, bucket: RANK_HEALTHY, headroom, index };
115168
});
@@ -129,7 +182,11 @@ export function rankAccountsByHeadroom(provider: string, ring: readonly string[]
129182
* told "ranked" when nothing was measured. Pre-dispatch selection asks this first so it
130183
* can decline to act on a roster it knows nothing about.
131184
*/
132-
export function hasHeadroomEvidence(provider: string, ids: readonly string[]): boolean {
185+
export function hasHeadroomEvidence(
186+
provider: string,
187+
ids: readonly string[],
188+
requestedModelId?: string | null,
189+
): boolean {
133190
// A PASSIVE provider needs evidence for EVERY candidate, not any one of them.
134191
//
135192
// A probe fills the whole roster in one pass (fetchProviderAccountQuotas), so "any"
@@ -140,10 +197,10 @@ export function hasHeadroomEvidence(provider: string, ids: readonly string[]): b
140197
// AWAY from an unmeasured account and TOWARD the one account known to be spent, which
141198
// is the exact inversion of what ranking is for.
142199
if (hasPassiveAccountQuota(provider)) {
143-
return ids.length > 0 && ids.every(id => headroomOf(provider, id) !== null);
200+
return ids.length > 0 && ids.every(id => headroomOf(provider, id, requestedModelId) !== null);
144201
}
145202
return ids.some(id =>
146-
headroomOf(provider, id) !== null
203+
headroomOf(provider, id, requestedModelId) !== null
147204
|| (provider === "kiro" && getKiroAccountExhaustion(`${provider}\u0000${id}`) !== null));
148205
}
149206
/**

‎src/oauth/generic-account-failover.ts‎

Lines changed: 40 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ import {
2222
hasHeadroomEvidence,
2323
isAccountQuotaExhausted,
2424
rankAccountsByHeadroom,
25+
classifyModelFamilyForQuota,
26+
type QuotaModelFamily,
2527
} from "./account-quota-rank";
2628
import {
2729
genericPoolKey,
@@ -81,13 +83,14 @@ const health = new Map<string, AccountHealth>();
8183
/** Provider -> recent eligible-account count. TTL-bounded; never holds credential material. */
8284
const presence = new Map<string, PresenceEntry>();
8385

84-
const healthKey = (provider: string, accountId: string) => `${provider}\u0000${accountId}`;
86+
const healthKey = (provider: string, accountId: string, family?: QuotaModelFamily) =>
87+
family ? `${provider}\u0000${accountId}\u0000${family}` : `${provider}\u0000${accountId}`;
8588

86-
function isCooled(provider: string, accountId: string, now: number): boolean {
87-
const entry = health.get(healthKey(provider, accountId));
89+
function isCooled(provider: string, accountId: string, now: number, family?: QuotaModelFamily): boolean {
90+
const entry = health.get(healthKey(provider, accountId, family));
8891
if (!entry) return false;
8992
if (entry.cooldownUntil <= now) {
90-
health.delete(healthKey(provider, accountId));
93+
health.delete(healthKey(provider, accountId, family));
9194
return false;
9295
}
9396
return true;
@@ -175,11 +178,11 @@ function isProactivePreferenceEnabled(config: OcxConfig, providerName: string, n
175178
}
176179

177180
/** Accounts that may serve traffic right now: not cooled, not flagged for reauth. */
178-
export function eligibleFailoverAccounts(providerName: string, now = Date.now()): string[] {
181+
export function eligibleFailoverAccounts(providerName: string, now = Date.now(), family?: QuotaModelFamily): string[] {
179182
const set = getAccountSet(providerName);
180183
if (!set) return [];
181184
return set.accounts
182-
.filter(account => account.needsReauth !== true && !isCooled(providerName, account.id, now))
185+
.filter(account => account.needsReauth !== true && !isCooled(providerName, account.id, now, family))
183186
.map(account => account.id);
184187
}
185188

@@ -230,8 +233,8 @@ function stableGenericRoster(providerName: string): string[] {
230233
* statement about observed usage, and treating "no observation" as "spent" would evacuate every
231234
* quota-less provider off its active account on the very first request.
232235
*/
233-
function isOverAutoSwitchThreshold(providerName: string, accountId: string, threshold: number): boolean {
234-
const headroom = accountHeadroomPercent(providerName, accountId);
236+
function isOverAutoSwitchThreshold(providerName: string, accountId: string, threshold: number, requestedModelId?: string | null): boolean {
237+
const headroom = accountHeadroomPercent(providerName, accountId, requestedModelId);
235238
if (headroom === null) return false;
236239
return 100 - headroom >= threshold;
237240
}
@@ -245,15 +248,17 @@ function pickFillFirstGenericAccount(
245248
providerName: string,
246249
activeId: string | undefined,
247250
now: number,
251+
requestedModelId?: string | null,
248252
): string | null {
249253
const stableAll = stableGenericRoster(providerName);
250254
if (stableAll.length < 2) return null;
251-
const eligible = new Set(eligibleFailoverAccounts(providerName, now));
255+
const family = classifyModelFamilyForQuota(providerName, requestedModelId);
256+
const eligible = new Set(eligibleFailoverAccounts(providerName, now, family));
252257
const stored = config.providers?.[providerName]?.oauthAccountFailover?.autoSwitchThreshold;
253258
const threshold = typeof stored === "number" && Number.isInteger(stored) && stored >= 0 && stored <= 100
254259
? stored
255260
: DEFAULT_GENERIC_AUTO_SWITCH_THRESHOLD;
256-
if (activeId && eligible.has(activeId) && !isOverAutoSwitchThreshold(providerName, activeId, threshold)) {
261+
if (activeId && eligible.has(activeId) && !isOverAutoSwitchThreshold(providerName, activeId, threshold, requestedModelId)) {
257262
return null;
258263
}
259264
const start = activeId ? stableAll.indexOf(activeId) : -1;
@@ -277,11 +282,17 @@ function pickFillFirstGenericAccount(
277282
* advance and round-robin would propose the same account forever. This is the same shape
278283
* `commitAnthropicSelectionRouting` already commits with.
279284
*/
280-
export function noteGenericPoolSelection(config: OcxConfig, providerName: string, accountId: string): void {
285+
export function noteGenericPoolSelection(
286+
config: OcxConfig,
287+
providerName: string,
288+
accountId: string,
289+
requestedModelId?: string | null,
290+
): void {
281291
if (activeGenericStrategy(config, providerName) !== "round-robin") return;
282292
const poolKey = genericPoolKey(providerName);
283293
const limit = genericStickyLimit(config, providerName);
284-
const picked = pickRoundRobinAccount(poolKey, eligibleFailoverAccounts(providerName), limit);
294+
const family = classifyModelFamilyForQuota(providerName, requestedModelId);
295+
const picked = pickRoundRobinAccount(poolKey, eligibleFailoverAccounts(providerName, Date.now(), family), limit);
285296
// The resolver may have admitted a different account than the ring proposed: a removal, a
286297
// reauth verdict or a manual selection can land during credential resolution. Realign the
287298
// cursor onto what actually served rather than leaving it on a road not taken.
@@ -302,6 +313,7 @@ export function rotateGenericOAuthAccountOn429(
302313
failedAccountId: string,
303314
retryAfterHeader: string | null | undefined,
304315
now = Date.now(),
316+
requestedModelId?: string | null,
305317
): string | null {
306318
if (!isGenericOAuthFailoverEnabled(config, providerName)) return null;
307319
const set = getAccountSet(providerName);
@@ -314,13 +326,14 @@ export function rotateGenericOAuthAccountOn429(
314326
// A Retry-After from upstream still wins — it is the server's own instruction.
315327
const exhausted = parsed === undefined ? exhaustedCooldownMs(providerName, failedAccountId, now) : null;
316328
const cooldownMs = exhausted ?? Math.min(parsed ?? DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS);
317-
health.set(healthKey(providerName, failedAccountId), {
329+
const family = classifyModelFamilyForQuota(providerName, requestedModelId);
330+
health.set(healthKey(providerName, failedAccountId, family), {
318331
cooldownUntil: now + cooldownMs,
319332
cooldownSource: parsed ? "retry-after" : "default",
320333
});
321334
sweepExpiredOnWrite(now);
322335

323-
const eligible = eligibleFailoverAccounts(providerName, now).filter(id => id !== failedAccountId);
336+
const eligible = eligibleFailoverAccounts(providerName, now, family).filter(id => id !== failedAccountId);
324337
if (eligible.length === 0) return null;
325338
// A rotation means the roster in use just changed; do not answer the next activation question
326339
// from a count read before the failure.
@@ -359,7 +372,7 @@ export function rotateGenericOAuthAccountOn429(
359372
}
360373
// With no quota evidence this returns the ring untouched, so providers without
361374
// per-account quota keep exactly the traversal they have today.
362-
return rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
375+
return rankAccountsByHeadroom(providerName, candidates, requestedModelId)[0] ?? null;
363376
}
364377

365378
/**
@@ -392,6 +405,7 @@ export function preferredInitialAccount(
392405
config: OcxConfig,
393406
providerName: string,
394407
now = Date.now(),
408+
requestedModelId?: string | null,
395409
): string | null {
396410
// The PROACTIVE predicate, not the reactive one: this steers a request upstream has not
397411
// refused, so `oauthAccountFailover.enabled: false` must still be able to refuse it.
@@ -411,7 +425,8 @@ export function preferredInitialAccount(
411425
// would never reach its own test. Cooldowns and reauth are still honoured inside each pick.
412426
const strategy = activeGenericStrategy(config, providerName);
413427
if (strategy === "round-robin") {
414-
const eligibleNow = eligibleFailoverAccounts(providerName, now);
428+
const family = classifyModelFamilyForQuota(providerName, requestedModelId);
429+
const eligibleNow = eligibleFailoverAccounts(providerName, now, family);
415430
if (eligibleNow.length === 0) return null;
416431
// PEEK, not pick: this proposal is discardable, and advancing the ring for an account the
417432
// resolver then rejects would skip a turn for nothing. noteGenericPoolSelection commits.
@@ -423,26 +438,26 @@ export function preferredInitialAccount(
423438
return picked && picked !== active ? picked : null;
424439
}
425440
if (strategy === "fill-first") {
426-
const picked = pickFillFirstGenericAccount(config, providerName, active, now);
441+
const picked = pickFillFirstGenericAccount(config, providerName, active, now, requestedModelId);
427442
return picked && picked !== active ? picked : null;
428443
}
429444

430445
const activeRow = selected.accounts.find(account => account.id === active);
431446
if (activeRow && activeRow.needsReauth !== true
432-
&& !isCooled(providerName, activeRow.id, now)
433-
&& !isAccountQuotaExhausted(providerName, activeRow.id)) return null;
447+
&& !isCooled(providerName, activeRow.id, now, classifyModelFamilyForQuota(providerName, requestedModelId))
448+
&& !isAccountQuotaExhausted(providerName, activeRow.id, requestedModelId)) return null;
434449

435450
// Evidence is required BEFORE eligibility narrows the field. Without this, a provider
436451
// with no quota data at all could still be redirected: cool the active account with a
437452
// 429 and the eligible list collapses to one candidate, which any ranking returns
438453
// unchanged — an answer that looks ranked but was never measured. The no-op guarantee
439454
// for quota-less providers has to be checked on the full roster.
440-
if (!hasHeadroomEvidence(providerName, order)) return null;
455+
if (!hasHeadroomEvidence(providerName, order, requestedModelId)) return null;
441456

442457
// Cooldowns are respected here, unlike in the presence count: this picks the account to
443458
// send to right now, and one inside its 429 window is the single candidate we hold
444459
// positive evidence against.
445-
const eligible = order.filter(id => !isCooled(providerName, id, now));
460+
const eligible = order.filter(id => !isCooled(providerName, id, now, classifyModelFamilyForQuota(providerName, requestedModelId)));
446461
if (eligible.length === 0) return null;
447462

448463
// Start the ring at the active account so an unranked outcome reproduces today's choice.
@@ -451,7 +466,7 @@ export function preferredInitialAccount(
451466
const candidates = ring.filter(id => eligible.includes(id));
452467
if (candidates.length === 0) return null;
453468

454-
const best = rankAccountsByHeadroom(providerName, candidates)[0] ?? null;
469+
const best = rankAccountsByHeadroom(providerName, candidates, requestedModelId)[0] ?? null;
455470
// Nothing to do when the ranking agrees with the account we would have used anyway.
456471
//
457472
// A proposal still needs guarded selection commit after credential resolution: a
@@ -461,12 +476,10 @@ export function preferredInitialAccount(
461476

462477
/** Earliest remaining cooldown, for a client-facing Retry-After when every account is cooled. */
463478
export function genericFailoverRetryAfterSeconds(providerName: string, now = Date.now()): number | null {
464-
const set = getAccountSet(providerName);
465-
if (!set) return null;
479+
const prefix = `${providerName}\u0000`;
466480
let earliest: number | null = null;
467-
for (const account of set.accounts) {
468-
const entry = health.get(healthKey(providerName, account.id));
469-
if (!entry || entry.cooldownUntil <= now) continue;
481+
for (const [key, entry] of health) {
482+
if (!key.startsWith(prefix) || entry.cooldownUntil <= now) continue;
470483
if (earliest === null || entry.cooldownUntil < earliest) earliest = entry.cooldownUntil;
471484
}
472485
return earliest === null ? null : Math.max(1, Math.ceil((earliest - now) / 1000));

0 commit comments

Comments
 (0)