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

Add the detected surface/IDE (e.g., vscode, cursor, terminal) to the
User-Agent string sent with API requests. This allows enterprise
customers to distinguish traffic from different clients (e.g., GCA
Agent Mode vs standalone CLI) in their GCP logs.

The surface is determined by a new shared utility that checks:
1. GEMINI_CLI_SURFACE env var (first-class enterprise override)
2. SURFACE env var (legacy, backward-compatible)
3. Auto-detection via existing detectIdeFromEnv()

The clearcut-logger telemetry is also updated to use this shared
utility, gaining GEMINI_CLI_SURFACE support.

Closes #18007

Author: SandyTao520

packages/core/src/core/contentGenerator.test.ts

@@ -152,6 +152,80 @@ describe('createContentGenerator', () => {
     );
   });
 
+  it('should include surface in User-Agent from GEMINI_CLI_SURFACE env var', async () => {
+    const mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getProxy: vi.fn().mockReturnValue(undefined),
+      getUsageStatisticsEnabled: () => true,
+    } as unknown as Config;
+
+    vi.stubEnv('CLI_VERSION', '1.2.3');
+    vi.stubEnv('GEMINI_CLI_SURFACE', 'my-custom-app');
+
+    const mockGenerator = {
+      models: {},
+    } as unknown as GoogleGenAI;
+    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
+    await createContentGenerator(
+      {
+        apiKey: 'test-api-key',
+        authType: AuthType.USE_GEMINI,
+      },
+      mockConfig,
+    );
+    expect(GoogleGenAI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpOptions: expect.objectContaining({
+          headers: expect.objectContaining({
+            'User-Agent': expect.stringMatching(
+              /GeminiCLI\/1\.2\.3\/gemini-pro \(.+; .+; my-custom-app\)/,
+            ),
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('should include default surface "SURFACE_NOT_SET" in User-Agent when no surface is detected', async () => {
+    const mockConfig = {
+      getModel: vi.fn().mockReturnValue('gemini-pro'),
+      getProxy: vi.fn().mockReturnValue(undefined),
+      getUsageStatisticsEnabled: () => true,
+    } as unknown as Config;
+
+    vi.stubEnv('CLI_VERSION', '1.2.3');
+    // Ensure no surface env vars are set
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', '');
+    vi.stubEnv('TERM_PROGRAM', '');
+    vi.stubEnv('GITHUB_SHA', '');
+    vi.stubEnv('EDITOR_IN_CLOUD_SHELL', '');
+    vi.stubEnv('CLOUD_SHELL', '');
+
+    const mockGenerator = {
+      models: {},
+    } as unknown as GoogleGenAI;
+    vi.mocked(GoogleGenAI).mockImplementation(() => mockGenerator as never);
+    await createContentGenerator(
+      {
+        apiKey: 'test-api-key',
+        authType: AuthType.USE_GEMINI,
+      },
+      mockConfig,
+    );
+    expect(GoogleGenAI).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpOptions: expect.objectContaining({
+          headers: expect.objectContaining({
+            'User-Agent': expect.stringMatching(
+              /GeminiCLI\/1\.2\.3\/gemini-pro \(.+; .+; SURFACE_NOT_SET\)/,
+            ),
+          }),
+        }),
+      }),
+    );
+  });
+
   it('should include custom headers from GEMINI_CLI_CUSTOM_HEADERS for Code Assist requests', async () => {
     const mockGenerator = {} as unknown as ContentGenerator;
     vi.mocked(createCodeAssistContentGenerator).mockResolvedValue(

packages/core/src/core/contentGenerator.ts

@@ -22,6 +22,7 @@ import { LoggingContentGenerator } from './loggingContentGenerator.js';
 import { InstallationManager } from '../utils/installationManager.js';
 import { FakeContentGenerator } from './fakeContentGenerator.js';
 import { parseCustomHeaders } from '../utils/customHeaderUtils.js';
+import { determineSurface } from '../utils/surface.js';
 import { RecordingContentGenerator } from './recordingContentGenerator.js';
 import { getVersion, resolveModel } from '../../index.js';
 import type { LlmRole } from '../telemetry/llmRole.js';
@@ -173,7 +174,8 @@ export async function createContentGenerator(
     );
     const customHeadersEnv =
       process.env['GEMINI_CLI_CUSTOM_HEADERS'] || undefined;
-    const userAgent = `GeminiCLI/${version}/${model} (${process.platform}; ${process.arch})`;
+    const surface = determineSurface();
+    const userAgent = `GeminiCLI/${version}/${model} (${process.platform}; ${process.arch}; ${surface})`;
     const customHeadersMap = parseCustomHeaders(customHeadersEnv);
     const apiKeyAuthMechanism =
       process.env['GEMINI_API_KEY_AUTH_MECHANISM'] || 'x-goog-api-key';

packages/core/src/telemetry/clearcut-logger/clearcut-logger.test.ts

@@ -512,13 +512,27 @@ describe('ClearcutLogger', () => {
         },
         expected: 'positron',
       },
+      {
+        name: 'GEMINI_CLI_SURFACE env var',
+        env: { GEMINI_CLI_SURFACE: 'gca-agent' },
+        expected: 'gca-agent',
+      },
+      {
+        name: 'GEMINI_CLI_SURFACE takes precedence over SURFACE and TERM_PROGRAM',
+        env: {
+          GEMINI_CLI_SURFACE: 'gca-agent',
+          SURFACE: 'ide-1234',
+          TERM_PROGRAM: 'vscode',
+        },
+        expected: 'gca-agent',
+      },
       {
         name: 'SURFACE env var',
         env: { SURFACE: 'ide-1234' },
         expected: 'ide-1234',
       },
       {
-        name: 'SURFACE env var takes precedence',
+        name: 'SURFACE env var takes precedence over auto-detection',
         env: { TERM_PROGRAM: 'vscode', SURFACE: 'ide-1234' },
         expected: 'ide-1234',
       },

packages/core/src/telemetry/clearcut-logger/clearcut-logger.ts

@@ -62,11 +62,7 @@ import {
 import { ASK_USER_TOOL_NAME } from '../../tools/tool-names.js';
 import { FixedDeque } from 'mnemonist';
 import { GIT_COMMIT_INFO, CLI_VERSION } from '../../generated/git-commit.js';
-import {
-  IDE_DEFINITIONS,
-  detectIdeFromEnv,
-  isCloudShell,
-} from '../../ide/detect-ide.js';
+import { determineSurface } from '../../utils/surface.js';
 import { debugLogger } from '../../utils/debugLogger.js';
 import { getErrorMessage } from '../../utils/errors.js';
 
@@ -153,28 +149,8 @@ export interface LogRequest {
   log_event: LogEventEntry[][];
 }
 
-/**
- * Determine the surface that the user is currently using.  Surface is effectively the
- * distribution channel in which the user is using Gemini CLI.  Gemini CLI comes bundled
- * w/ Firebase Studio and Cloud Shell.  Users that manually download themselves will
- * likely be "SURFACE_NOT_SET".
- *
- * This is computed based upon a series of environment variables these distribution
- * methods might have in their runtimes.
- */
-function determineSurface(): string {
-  if (process.env['SURFACE']) {
-    return process.env['SURFACE'];
-  } else if (isCloudShell()) {
-    return IDE_DEFINITIONS.cloudshell.name;
-  } else if (process.env['GITHUB_SHA']) {
-    return 'GitHub';
-  } else if (process.env['TERM_PROGRAM'] === 'vscode') {
-    return detectIdeFromEnv().name || IDE_DEFINITIONS.vscode.name;
-  } else {
-    return 'SURFACE_NOT_SET';
-  }
-}
+// Surface detection is provided by the shared determineSurface() utility
+// imported from '../../utils/surface.js'.
 
 /**
  * Determines the GitHub Actions workflow name if the CLI is running in a GitHub Actions environment.

packages/core/src/utils/surface.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { determineSurface, SURFACE_NOT_SET } from './surface.js';
+
+describe('determineSurface', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('should return GEMINI_CLI_SURFACE when set', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', 'my-custom-app');
+    expect(determineSurface()).toBe('my-custom-app');
+  });
+
+  it('should prioritize GEMINI_CLI_SURFACE over SURFACE', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', 'gca-agent');
+    vi.stubEnv('SURFACE', 'ide-1234');
+    expect(determineSurface()).toBe('gca-agent');
+  });
+
+  it('should prioritize GEMINI_CLI_SURFACE over auto-detection', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', 'gca-agent');
+    vi.stubEnv('TERM_PROGRAM', 'vscode');
+    expect(determineSurface()).toBe('gca-agent');
+  });
+
+  it('should fall back to SURFACE env var when GEMINI_CLI_SURFACE is not set', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', 'ide-1234');
+    expect(determineSurface()).toBe('ide-1234');
+  });
+
+  it('should detect Cloud Shell via CLOUD_SHELL env var', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', '');
+    vi.stubEnv('CLOUD_SHELL', 'true');
+    expect(determineSurface()).toBe('cloudshell');
+  });
+
+  it('should detect Cloud Shell via EDITOR_IN_CLOUD_SHELL env var', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', '');
+    vi.stubEnv('EDITOR_IN_CLOUD_SHELL', 'true');
+    expect(determineSurface()).toBe('cloudshell');
+  });
+
+  it('should detect GitHub Actions via GITHUB_SHA env var', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', '');
+    vi.stubEnv('GITHUB_SHA', 'abc123');
+    expect(determineSurface()).toBe('GitHub');
+  });
+
+  it('should detect VSCode via TERM_PROGRAM env var', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', '');
+    vi.stubEnv('GITHUB_SHA', '');
+    vi.stubEnv('TERM_PROGRAM', 'vscode');
+    vi.stubEnv('CURSOR_TRACE_ID', '');
+    vi.stubEnv('MONOSPACE_ENV', '');
+    vi.stubEnv('POSITRON', '');
+    vi.stubEnv('ANTIGRAVITY_CLI_ALIAS', '');
+    vi.stubEnv('__COG_BASHRC_SOURCED', '');
+    vi.stubEnv('REPLIT_USER', '');
+    vi.stubEnv('CODESPACES', '');
+    vi.stubEnv('CLOUD_SHELL', '');
+    vi.stubEnv('EDITOR_IN_CLOUD_SHELL', '');
+    expect(determineSurface()).toBe('vscode');
+  });
+
+  it('should detect Cursor when CURSOR_TRACE_ID is set', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', '');
+    vi.stubEnv('GITHUB_SHA', '');
+    vi.stubEnv('TERM_PROGRAM', 'vscode');
+    vi.stubEnv('CURSOR_TRACE_ID', 'abc123');
+    expect(determineSurface()).toBe('cursor');
+  });
+
+  it('should return SURFACE_NOT_SET when no surface is detected', () => {
+    vi.stubEnv('GEMINI_CLI_SURFACE', '');
+    vi.stubEnv('SURFACE', '');
+    vi.stubEnv('GITHUB_SHA', '');
+    vi.stubEnv('TERM_PROGRAM', '');
+    vi.stubEnv('CLOUD_SHELL', '');
+    vi.stubEnv('EDITOR_IN_CLOUD_SHELL', '');
+    expect(determineSurface()).toBe(SURFACE_NOT_SET);
+  });
+});

packages/core/src/utils/surface.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { detectIdeFromEnv, isCloudShell } from '../ide/detect-ide.js';
+
+/** Default surface value when no IDE/environment is detected. */
+export const SURFACE_NOT_SET = 'SURFACE_NOT_SET';
+
+/**
+ * Determines the surface/distribution channel the CLI is running in.
+ *
+ * Priority:
+ * 1. `GEMINI_CLI_SURFACE` env var (first-class override for enterprise customers)
+ * 2. `SURFACE` env var (legacy override, kept for backward compatibility)
+ * 3. Auto-detection via environment variables (Cloud Shell, GitHub Actions, IDE, etc.)
+ *
+ * @returns A human-readable surface identifier (e.g., "vscode", "cursor", "terminal").
+ */
+export function determineSurface(): string {
+  if (process.env['GEMINI_CLI_SURFACE']) {
+    return process.env['GEMINI_CLI_SURFACE'];
+  }
+  if (process.env['SURFACE']) {
+    return process.env['SURFACE'];
+  }
+  if (isCloudShell()) {
+    return 'cloudshell';
+  }
+  if (process.env['GITHUB_SHA']) {
+    return 'GitHub';
+  }
+  if (process.env['TERM_PROGRAM'] === 'vscode') {
+    return detectIdeFromEnv().name;
+  }
+  return SURFACE_NOT_SET;
+}