feat(core): include surface identifier in User-Agent header

[SandyTao520]

Summary

Include the detected surface/IDE identifier (e.g., vscode, cursor, terminal) in the User-Agent HTTP header sent with Gemini API requests. This enables enterprise customers to distinguish traffic originating from different clients (e.g., GCA VSCode Agent Mode vs standalone CLI) in their GCP Cloud Logging/Monitoring dashboards.

Details

Problem: The CLI's User-Agent (GeminiCLI/{version}/{model} ({platform}; {arch})) doesn't identify the source environment. Enterprise customers cannot tell whether a request came from VSCode Agent Mode, standalone CLI, Cursor, or any other embedding.

Solution: Append the surface identifier to the User-Agent parenthetical:

GeminiCLI/0.34.0/gemini-2.5-pro (linux; x64; vscode)
GeminiCLI/0.34.0/gemini-2.5-pro (linux; x64; terminal)
GeminiCLI/0.34.0/gemini-2.5-pro (linux; x64; my-custom-app)

Implementation:

• New shared utility (packages/core/src/utils/surface.ts): determineSurface() with priority:

  1. GEMINI_CLI_SURFACE env var — first-class override for enterprise customers
  2. SURFACE env var — legacy, backward-compatible
  3. Auto-detection via existing detectIdeFromEnv() (supports ~15+ IDEs)
  4. Falls back to SURFACE_NOT_SET

• contentGenerator.ts: User-Agent now includes the surface identifier

• clearcut-logger.ts: Refactored to use the shared utility (also gains GEMINI_CLI_SURFACE support; existing telemetry values preserved)

Enterprise usage:

# In .gemini/.env for GCA Agent Mode workspaces:
GEMINI_CLI_SURFACE=gca-agent

# Or globally for terminal:
export GEMINI_CLI_SURFACE=my-org-terminal

Related Issues

Closes #18007

How to Validate

1. Run the new surface utility tests:

   npm test -w @google/gemini-cli-core -- src/utils/surface.test.ts

2. Run content generator tests (includes new User-Agent surface tests):

   npm test -w @google/gemini-cli-core -- src/core/contentGenerator.test.ts

3. Run clearcut-logger tests (includes GEMINI_CLI_SURFACE test cases):

   npm test -w @google/gemini-cli-core -- src/telemetry/clearcut-logger/clearcut-logger.test.ts

4. Manual verification:

   export GEMINI_CLI_SURFACE=test-surface
   # Start the CLI and inspect outgoing requests — User-Agent should contain "test-surface"

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

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, 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 enhances the Gemini CLI's ability to identify its operating environment by including a "surface" identifier in the User-Agent HTTP header. This change allows enterprise customers to more accurately track and distinguish API traffic originating from different client applications or environments, such as VSCode Agent Mode versus a standalone CLI, within their monitoring dashboards. The implementation introduces a new shared utility for surface detection with a clear priority system for environment variables and auto-detection, and integrates this utility into both API request headers and telemetry logging.

Highlights

• Surface Identification Utility: Introduced a new shared utility determineSurface() to identify the client environment (e.g., vscode, terminal, gca-agent) based on environment variables and auto-detection.
• User-Agent Header Enhancement: Modified the User-Agent HTTP header in Gemini API requests to include the detected surface identifier, enabling better traffic differentiation for enterprise customers.
• Prioritized Surface Detection: Implemented a clear priority for surface detection: GEMINI_CLI_SURFACE environment variable takes precedence, followed by SURFACE, and then various auto-detection mechanisms.
• Telemetry Refactoring: Refactored the clearcut-logger to utilize the new shared determineSurface() utility, ensuring consistent surface identification across the application.

Changelog

• packages/core/src/core/contentGenerator.test.ts
  • Added new test cases to verify that the User-Agent header correctly includes the surface identifier when GEMINI_CLI_SURFACE is set.
  • Added a test case to confirm SURFACE_NOT_SET is used when no surface is detected.
• packages/core/src/core/contentGenerator.ts
  • Imported the new determineSurface utility.
  • Modified the User-Agent string construction to append the determined surface identifier.
• packages/core/src/telemetry/clearcut-logger/clearcut-logger.test.ts
  • Added test cases to ensure GEMINI_CLI_SURFACE environment variable is correctly prioritized for surface detection.
  • Updated a test description for SURFACE env var precedence.
• packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts
  • Removed the previously defined local determineSurface function.
  • Updated imports to use the new shared determineSurface utility from ../utils/surface.js.
• packages/core/src/utils/surface.test.ts
  • Added a new test file to thoroughly test the determineSurface utility's logic, including priority for different environment variables and auto-detection scenarios.
• packages/core/src/utils/surface.ts
  • Added a new utility file defining the determineSurface function and SURFACE_NOT_SET constant.
  • Implemented the logic for prioritizing GEMINI_CLI_SURFACE, SURFACE, and auto-detection for Cloud Shell, GitHub Actions, and VSCode.

Activity

• No human activity (comments, reviews, or progress updates) has been recorded for this pull request yet.

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 is a great improvement, adding the surface identifier to the User-Agent header for better request tracking and refactoring the detection logic into a shared utility. The implementation is clean and well-tested. I found one high-severity issue with the surface detection logic. The current implementation is too restrictive and fails to detect several supported IDEs (like Sublime Text, JetBrains, Replit), leading to incorrect telemetry and User-Agent data. I've suggested a fix to make the detection more comprehensive and robust.

[github-actions]

Size Change: +300 B (0%)

Total Size: 26.5 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	26 MB	+300 B (0%)
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B

_{compressed-size-action}