Feature/quota visibility 16795

[spencer426]

Summary

Implements real-time usage visibility in the Gemini CLI footer and /stats commands. This feature ensures users are aware of
their remaining usage limits through a non-blocking, event-driven architecture that supports Auto Mode pooling and
post-response background refreshes.

Details

• Real-time Synchronization: Added QuotaChanged event to CoreEventEmitter to push quota updates from Core to the CLI UI
  instantly.
• Auto Mode Pooling: Implemented logic to aggregate gemini-pro and gemini-flash quotas, providing a unified "pooled" view of
  remaining usage and limits.
• Conservative Reset Tracking: Reset times are now tracked per model; in Auto Mode, the UI displays the latest (most
  conservative) recovery time.
• Smart Refresh: Integrated refreshUserQuotaIfStale (30s TTL) into LoggingContentGenerator to trigger background refreshes
  after model responses without blocking the user.
• UI/UX Refinements:
  • Visibility Gate: Footer indicator is strictly hidden when usage is > 20%.
  • Color Coding: transitions from Yellow (≤ 20%) to Red (< 5% or reached).
  • Terminology: Standardized on "Usage remaining" and "Usage limit" across all components.
  • Actionable States: Added explicit recovery instructions (e.g., /auth to upgrade) in both the footer and /stats when
    limits are reached.
• Testing: Updated snapshots and unit tests in Footer, StatsDisplay, and ModelStatsDisplay to match new layouts and phrasing.

Near Limit

Limit Reached

Related Issues

Fixes #16795

How to Validate

• Manual Testing: Mock refreshUserQuota in config.ts with various remainingFraction values:
  - 0.50: Footer should be hidden.
  - 0.20: Footer should show yellow warning.
  - 0.00: Footer should show red "Limit reached" with /auth instructions.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello @spencer426, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new feature to display real-time quota usage information directly within the CLI's user interface. It involves a comprehensive set of changes across UI components, application state management, and API communication layers to fetch, track, and present the user's remaining quota. The goal is to provide users with immediate visibility into their usage limits, enhancing their overall experience and preventing unexpected service interruptions.

Highlights

• Quota Display Component: Introduced a new QuotaDisplay React component to visually represent the user's remaining quota in the CLI footer, with color-coded indicators for different usage levels (green, yellow, red).
• Quota State Management: Integrated quotaRemaining and quotaLimit into the AppContainer's state and the UIStateContext, allowing the UI to reactively display quota information.
• Quota Event System: Added a new CoreEvent.QuotaChanged event and corresponding payload (QuotaChangedPayload) to the core event emitter, enabling other parts of the application to subscribe and react to quota updates.
• API Response Interception for Quota: Implemented a wrapFetchWithQuotaInterception utility function that intercepts HTTP responses from the API, extracts rate limit headers (e.g., x-ratelimit-remaining, x-ratelimit-limit), and triggers quota updates.
• CodeAssistServer Integration: Modified the CodeAssistServer to accept an onQuotaUpdate callback, which is invoked when quota headers are detected in API responses, ensuring the Config and UI are kept up-to-date.
• Improved Testability for Clipboard Utilities: Added a resetClipboardToolForTesting function to clipboardUtils to improve test isolation by clearing the cached Linux clipboard tool state between tests.

Changelog

• packages/cli/src/ui/AppContainer.tsx
  • Added quotaRemaining and quotaLimit state variables, initialized from config.getQuotaRemaining() and config.getQuotaLimit() respectively.
  • Subscribed to CoreEvent.QuotaChanged to update the quotaRemaining and quotaLimit state when a quota change event is emitted.
  • Passed quotaRemaining and quotaLimit as props to relevant child components.
• packages/cli/src/ui/components/Footer.test.tsx
  • Added a new test case to verify that the Footer component correctly displays the quota indicator when quotaRemaining and quotaLimit are provided in the uiState.
• packages/cli/src/ui/components/Footer.tsx
  • Imported the new QuotaDisplay component.
  • Destructured quotaRemaining and quotaLimit from uiState.
  • Conditionally rendered the QuotaDisplay component in the footer when both quotaRemaining and quotaLimit are defined.
• packages/cli/src/ui/components/QuotaDisplay.test.tsx
  • New file: Added comprehensive unit tests for the QuotaDisplay component, covering scenarios where remaining or limit are undefined, limit is zero, and different percentage thresholds for color rendering (green, yellow, red).
• packages/cli/src/ui/components/QuotaDisplay.tsx
  • New file: Created the QuotaDisplay React functional component which takes remaining and limit as props.
  • Calculates the percentage of quota remaining and applies semantic colors (success, warning, error) based on predefined thresholds (20% and 5%).
  • Renders a formatted string like '[Quota: 85%]' or returns null if quota data is incomplete or invalid.
• packages/cli/src/ui/contexts/UIStateContext.tsx
  • Extended the UIState interface to include quotaRemaining and quotaLimit properties, both of type number | undefined.
• packages/cli/src/ui/utils/clipboardUtils.test.ts
  • Imported resetClipboardToolForTesting for test setup.
  • Called resetClipboardToolForTesting() in the beforeEach hook to ensure a clean state for clipboard tool detection in each test.
  • Modified a test case to explicitly set platform and remove XDG_SESSION_TYPE for more robust testing of clipboard tool detection.
• packages/cli/src/ui/utils/clipboardUtils.ts
  • Exported a new function resetClipboardToolForTesting() which sets linuxClipboardTool to null, allowing tests to re-evaluate the clipboard tool detection.
• packages/core/src/code_assist/codeAssist.test.ts
  • Updated mockUserData to include userTierName.
  • Modified calls to createCodeAssistContentGenerator to pass userTierName and a new onQuotaUpdate callback function for testing purposes.
• packages/core/src/code_assist/codeAssist.ts
  • Modified the createCodeAssistContentGenerator function to pass a callback to the CodeAssistServer constructor. This callback uses config.setQuota to update the quota state when new quota information is received.
• packages/core/src/code_assist/server.test.ts
  • Added a new test case to verify that CodeAssistServer correctly extracts x-ratelimit-remaining and x-ratelimit-limit headers from API responses.
  • Ensured that the onQuotaUpdate callback provided to the CodeAssistServer constructor is called with the parsed remaining and limit values.
• packages/core/src/code_assist/server.ts
  • Added an optional onQuotaUpdate callback to the CodeAssistServer constructor, which will be invoked when quota headers are found.
  • Implemented a private extractQuotaHeaders method to parse various forms of rate limit headers (e.g., x-ratelimit-remaining, X-RateLimit-Remaining, x-goog-ratelimit-remaining) from HTTP response headers.
  • Integrated extractQuotaHeaders calls into requestPost and requestStream methods to process quota information from all API responses.
• packages/core/src/config/config.ts
  • Added private fields quotaRemaining and quotaLimit to store the current quota status.
  • Implemented setQuota(remaining: number | undefined, limit: number | undefined) method to update these fields and emit a CoreEvent.QuotaChanged event.
  • Added getQuotaRemaining() and getQuotaLimit() public methods to retrieve the current quota values.
• packages/core/src/core/contentGenerator.test.ts
  • Updated expectations for GoogleGenAI constructor calls to include fetch: expect.any(Function) within httpOptions, reflecting the new fetch interception mechanism.
• packages/core/src/core/contentGenerator.ts
  • Imported wrapFetchWithQuotaInterception.
  • Modified the httpOptions object passed to the GoogleGenAI constructor to include a wrapped fetch function. This wrapped fetch intercepts API responses to extract quota headers and update the gcConfig via gcConfig.setQuota.
• packages/core/src/utils/events.ts
  • Defined a new interface QuotaChangedPayload with remaining and limit properties.
  • Added CoreEvent.QuotaChanged to the CoreEvent enum.
  • Included [CoreEvent.QuotaChanged]: [QuotaChangedPayload] in the CoreEvents interface.
  • Implemented emitQuotaChanged(remaining: number | undefined, limit: number | undefined) in CoreEventEmitter to facilitate broadcasting quota updates.
• packages/core/src/utils/fetch.ts
  • Added a new utility function wrapFetchWithQuotaInterception.
  • This function takes an existing fetch function and an onQuotaUpdate callback.
  • It returns a new fetch function that executes the original fetch, then inspects the response headers for rate limit information, parses it, and calls onQuotaUpdate before returning the original response.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new feature to display API usage quota information in the CLI's footer. The changes are well-implemented across the core and UI packages. Quota information is extracted from API response headers for both Google-auth and API-key based authentication methods, propagated through the application via the core event system, and stored in the central config. The UI is updated to consume this new state and render it in a new QuotaDisplay component, which correctly shows the remaining quota percentage with color-coding for different thresholds. The changes include comprehensive unit tests for the new components and logic. The implementation is solid and I don't see any issues.

[github-actions]

Size Change: +13.5 kB (+0.06%)

Total Size: 23.9 MB

Filename	Size	Change
./bundle/gemini.js	23.9 MB	+13.5 kB (+0.06%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[chrstnb]

Thoughts on only emitting this if this.quotaRemaining !== remaining || this.quotaLimit !== limit?

[spencer426]

Done.

[chrstnb]

Just a few nits, otherwise looks good!

[chrstnb]

let's hold off and get @jacob314's approval!

[sehoon38]

does this work for all auth types?
I tried with oauth and didn't see the limit showing up after making requests.
for /stats, we use refreshUserQuota from config.ts to fetch the quota by the models, and I'm not sure if this will give the same limit.
also this seems to be called for every call and not just the model used by the main agent, so this could show the limit remaining of a model that's used by a tool call.