fix(usage): normalize Antigravity and agy provider quotas

[dhaern]

Summary

This is the second split-out PR from #3584. It contains the Antigravity/agy Provider Quota accuracy work and is intended to be reviewed after #3603.

Stacking note: GitHub does not allow opening an upstream PR whose base is a branch that only exists in a fork. This PR is therefore opened against release/v3.8.21, but it depends on #3603. After #3603 lands, this branch can be rebased so the diff contains only the quota commit.

Changes:

• normalizes Antigravity and agy quota bucket IDs to the same clean public IDs used by the model catalog
• prefers retrieveUserQuota when Google reports live consumption data
• keeps fetchAvailableModels as a fallback for buckets that are only available from the catalog/eligibility response
• uses local usage_history as a fallback signal for fetchAvailableModels-only buckets that otherwise stay at 100% / 0 used
• sanitizes cached Provider Limits entries so retired upstream IDs are not re-exposed in the UI/API
• schedules a small deduplicated post-usage refresh for Antigravity/agy connections after successful usage records
• preserves the v3.8.21 GLM monthly/no-cap quota behavior

Scope

Included:

• Provider Limits backend normalization
• quota source priority and cache sanitization
• post-usage quota refresh for Antigravity/agy
• minimal UI parsing/auto-refresh changes required to show accurate quota data

Not included:

• reasoning leak sanitizer/translator changes

Dependency

Depends on #3603 because the quota normalization uses the clean Antigravity/agy model IDs introduced there.

Validation

Ran focused tests locally:

bun test tests/unit/agy-usage-quota.test.ts \
  tests/unit/provider-columns.test.ts \
  tests/unit/usage-service-hardening.test.ts

Result: 36 pass, 0 fail.

Also tested the combined local stack against OmniRoute v3.8.21 with omniroute-install-local-build --restart and confirmed the Provider Quota view updates against the cleaned model set.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[diegosouzapw]

Merged into release/v3.8.21 🎉 Thanks @dhaern — the retrieveUserQuota-first accuracy work is great. One maintainer follow-up (co-authored): the post-usage refresh originally used import("./providerLimits") inside usageHistory, which transitively pulled the executors/translator graph into the typecheck:core surface and surfaced ~390 pre-existing strictNullChecks errors in unrelated translators (0 → 394). I decoupled it via a lightweight usageEvents bus (usageHistory emits, providerLimits subscribes at load) — same behavior, typecheck:core back to 0. Quota + new event-bus tests green. Ships next release.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

This PR introduces a sophisticated quota tracking system for Antigravity/agy providers that addresses several important issues:

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	0

Key Changes Reviewed

1. open-sse/services/usage.ts:

   • Added fetchAntigravityUserQuotaCached function to fetch real-time user quota from retrieveUserQuota endpoint
   • Added toClientAntigravityQuotaModelId normalization for retired model ID mapping (e.g., gemini-3-flash-agent → gemini-3.5-flash-high)
   • Added applyLocalUsageFallback to supplement catalog quota data with actual usage from DB
   • Modified getAntigravityUsage to prefer retrieveUserQuota buckets over catalog quotaInfo
   • Proper inflight deduplication and TTL cache management

2. src/lib/usage/providerLimits.ts:

   • Added getSanitizedCachedProviderLimitsMap to normalize quota keys before returning cached data
   • Added notifyProviderUsageRecorded and post-usage refresh scheduling (5s delay)
   • Added sanitizeUsageQuotasForProvider and normalizeUsageQuotasForProvider with source ranking
   • Source ranking correctly prioritizes: retrieveUserQuota (2) > localUsageHistory (1) > fetchAvailableModels (0)

3. src/lib/usage/usageEvents.ts (new file):

   • Lightweight event bus to decouple usageHistory from providerLimits
   • Proper error handling with try/catch per listener

4. Tests updated:

   • Changed mock usage to direct globalThis.fetch assignment (better pattern for Node.js native test runner)
   • Added tests for retrieveUserQuota preference and retired bucket normalization
   • Added usage-events.test.ts for event bus coverage

Architecture Quality

• The event bus pattern correctly prevents circular import dependencies (usageHistory ← providerLimits via executors)
• Model ID normalization handles the transition from legacy to clean model names
• Source ranking logic correctly deduplicates same-key entries while preferring higher-quality sources
• Cache TTL is consistent with other Antigravity caches (60s)
• Auto-refresh logic only triggers when gemini quotas lack retrieveUserQuota source

Files Reviewed (8 files)

• open-sse/services/usage.ts
• src/lib/usage/providerLimits.ts
• src/lib/usage/usageEvents.ts
• src/lib/usage/usageHistory.ts
• src/app/api/usage/provider-limits/route.ts
• src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.tsx
• src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.tsx
• tests/unit/*/*.ts (multiple test files)

---

_{Reviewed by laguna-m.1-20260312:free · 3,037,332 tokens}