feat(core): differentiate User-Agent for a2a-server and ACP clients

[bdmorgan]

Summary

Implements a hybrid approach to differentiate Gemini CLI traffic in the User-Agent header, allowing enterprise customers and embedded products (like Gemini Code Assist) to accurately report on API usage from different surfaces. This replaces and expands upon the approach proposed in #21934.

Details

This PR introduces a hybrid identification mechanism:

1. Programmatic Identity (Prefix): The Config object now supports a clientName field. The a2a-server explicitly sets this to a2a-server, and the CLI sets it dynamically when running in ACP mode (e.g., acp-zed, acp-xcode, acp-intellijidea). This becomes the prefix of the User-Agent string (e.g., GeminiCLI-a2a-server/...).
2. Surface Auto-Detection (Parenthetical): Integrates the determineSurface() utility from PR feat(core): include surface identifier in User-Agent header #21934 to automatically probe the environment for the hosting surface (e.g., vscode, terminal) and appends it to the parenthetical metadata (e.g., ... (linux; x64; vscode)).
3. Custom Overrides: Enterprise customers can use the GEMINI_CLI_SURFACE environment variable to explicitly tag custom deployment tools.

This approach provides a robust, unforgeable contract for embedded systems while retaining broad telemetry improvements for standard users.

Includes:

• Comprehensive tests for User-Agent generation and IDE detection.
• Resolution of complex cross-package Vitest resolution and TypeScript typing issues.
• Updated documentation in docs/cli/telemetry.md and docs/reference/configuration.md.

Related Issues

Replaces/Closes #21934

How to Validate

1. Run the full test suite: npm run preflight
2. Review User-Agent headers in generated API calls when running the CLI normally vs. starting the a2a-server.
3. Verify documentation updates.

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, 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 significantly enhances the Gemini CLI's ability to differentiate API traffic origins by modifying the User-Agent header. It introduces a robust hybrid identification system that combines programmatic client naming for embedded systems like a2a-server and ACP clients, with automatic detection of the hosting environment (surface). Additionally, it provides an environment variable for custom overrides, allowing enterprise users to accurately track API usage from various deployment tools and integrated development environments.

Highlights

• User-Agent Header Differentiation: Introduced a hybrid mechanism to differentiate Gemini CLI traffic in the User-Agent header, allowing for more accurate API usage reporting from various environments.
• Programmatic Client Identification: Added a new clientName field to the Config object, which is explicitly set for a2a-server and dynamically for ACP clients (e.g., acp-zed, acp-xcode), forming a prefix in the User-Agent string.
• Automatic Surface Detection: Integrated a determineSurface() utility to automatically detect the hosting environment (e.g., vscode, terminal) and append it to the parenthetical metadata of the User-Agent string.
• Custom User-Agent Overrides: Enabled custom identification for enterprise customers and automation via the GEMINI_CLI_SURFACE environment variable.
• Documentation Updates: Updated docs/cli/telemetry.md and docs/reference/configuration.md to reflect the new client identification and User-Agent customization features.

Changelog

• docs/cli/telemetry.md
  • Updated documentation to include client identification details.
  • Added automatic identification examples.
  • Included custom identification instructions for GEMINI_CLI_SURFACE.
• docs/reference/configuration.md
  • Added documentation for the GEMINI_CLI_SURFACE environment variable.
• packages/a2a-server/src/config/config.test.ts
  • Added a test for a2a-server's clientName configuration.
• packages/a2a-server/src/config/config.ts
  • Explicitly set clientName for a2a-server.
• packages/cli/src/config/config.test.ts
  • Added tests for acpMode and dynamic clientName detection.
• packages/cli/src/config/config.ts
  • Integrated detectIdeFromEnv for dynamic clientName setting in ACP mode.
• packages/core/src/config/config.ts
  • Introduced clientName property to ConfigParameters and Config class.
• packages/core/src/core/contentGenerator.test.ts
  • Updated content generator tests to account for clientName and new User-Agent format.
• packages/core/src/core/contentGenerator.ts
  • Modified User-Agent generation to include clientName and detected surface.
• packages/core/src/ide/detect-ide.test.ts
  • Added tests for Zed and XCode IDE detection.
• packages/core/src/ide/detect-ide.ts
  • Expanded IDE detection logic to include Zed and XCode.
• packages/core/src/utils/surface.ts
  • Added determineSurface utility for environment identification.

Activity

• No specific activity (comments, reviews, progress) 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. ↩

[github-actions]

Size Change: +1.65 kB (+0.01%)

Total Size: 26.5 MB

Filename	Size	Change
./bundle/gemini.js	26.1 MB	+1.65 kB (+0.01%)

ℹ️ View Unchanged

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

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a mechanism to differentiate clients in the User-Agent header by adding a clientName prefix and a surface tag. The changes span across documentation, configuration, and core logic to support this for a2a-server and ACP clients. The implementation is mostly solid, but I've found a logic issue in how the clientName is determined for ACP mode which could lead to incorrect client identification in some scenarios. My review includes a suggestion to fix this.