Merge pull request #33675 from storybookjs/valentin/implement-agent-detection-telemetry

Telemetry: Add agent detection

Author: valentinpalkovic

code/core/src/telemetry/detect-agent.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import { detectAgent } from './detect-agent';
+
+describe('detectAgent', () => {
+  it('detects amp via AGENT=amp (highest precedence)', () => {
+    expect(
+      detectAgent({
+        stdoutIsTTY: true,
+        env: {
+          AGENT: 'amp',
+          CLAUDECODE: '1',
+          GEMINI_CLI: '1',
+          CODEX_SANDBOX: '1',
+          CURSOR_AGENT: '1',
+        },
+      })
+    ).toEqual({ name: 'amp' });
+
+    expect(
+      detectAgent({
+        stdoutIsTTY: true,
+        env: {
+          CLAUDECODE: '1',
+          GEMINI_CLI: '1',
+          CODEX_SANDBOX: '1',
+          CURSOR_AGENT: '1',
+          AGENT: 'something',
+        },
+      })
+    ).toEqual({ name: 'claude-code' });
+  });
+
+  it('detects Gemini CLI via GEMINI_CLI', () => {
+    expect(detectAgent({ stdoutIsTTY: true, env: { GEMINI_CLI: '1' } })).toEqual({
+      name: 'gemini-cli',
+    });
+  });
+
+  it('detects OpenAI Codex via CODEX_SANDBOX', () => {
+    expect(detectAgent({ stdoutIsTTY: true, env: { CODEX_SANDBOX: '1' } })).toEqual({
+      name: 'codex',
+    });
+  });
+
+  it('detects Cursor Agent via CURSOR_AGENT (even if AGENT is also set)', () => {
+    expect(
+      detectAgent({ stdoutIsTTY: true, env: { CURSOR_AGENT: '1', AGENT: 'something' } })
+    ).toEqual({
+      name: 'cursor',
+    });
+  });
+
+  it('treats generic AGENT as unknown', () => {
+    expect(detectAgent({ stdoutIsTTY: true, env: { AGENT: 'some-agent' } })).toEqual({
+      name: 'unknown',
+    });
+  });
+
+  it('does not use heuristics when stdout is a TTY', () => {
+    expect(detectAgent({ stdoutIsTTY: true, env: { TERM: 'dumb' } })).toEqual(undefined);
+    expect(detectAgent({ stdoutIsTTY: true, env: { GIT_PAGER: 'cat' } })).toEqual(undefined);
+  });
+
+  it('detects unknown agent via TERM=dumb when stdout is not a TTY', () => {
+    expect(detectAgent({ stdoutIsTTY: false, env: { TERM: 'dumb' } })).toEqual({
+      name: 'unknown',
+    });
+  });
+
+  it('detects unknown agent via GIT_PAGER=cat when stdout is not a TTY', () => {
+    expect(detectAgent({ stdoutIsTTY: false, env: { GIT_PAGER: 'cat' } })).toEqual({
+      name: 'unknown',
+    });
+  });
+
+  it('returns isAgent=false when there are no signals', () => {
+    expect(detectAgent({ stdoutIsTTY: false, env: {} })).toEqual(undefined);
+  });
+
+  it('applies heuristics even when CI is set (no CI special-casing)', () => {
+    expect(
+      detectAgent({
+        stdoutIsTTY: false,
+        env: { CI: 'true', TERM: 'dumb' },
+      })
+    ).toEqual({ name: 'unknown' });
+  });
+
+  it('still detects explicit agents in CI', () => {
+    expect(detectAgent({ stdoutIsTTY: false, env: { CI: 'true', CODEX_SANDBOX: '1' } })).toEqual({
+      name: 'codex',
+    });
+  });
+});

code/core/src/telemetry/detect-agent.ts

@@ -0,0 +1,90 @@
+export type KnownAgentName =
+  | 'claude-code'
+  | 'gemini-cli'
+  | 'cursor'
+  | 'codex'
+  | 'opencode'
+  | 'amp'
+  | 'unknown';
+
+export type AgentInfo = {
+  name: KnownAgentName;
+};
+
+export type AgentDetection = AgentInfo | undefined;
+
+type DetectAgentOptions = {
+  stdoutIsTTY: boolean;
+  env: NodeJS.ProcessEnv;
+};
+
+function detectExplicitAgent(env: NodeJS.ProcessEnv): AgentInfo | undefined {
+  // Amp
+  if (env.AGENT === 'amp') {
+    return {
+      name: 'amp',
+    };
+  }
+
+  // Claude Code
+  if (env.CLAUDECODE) {
+    return {
+      name: 'claude-code',
+    };
+  }
+
+  // Gemini CLI
+  if (env.GEMINI_CLI) {
+    return {
+      name: 'gemini-cli',
+    };
+  }
+
+  // OpenAI Codex
+  if (env.CODEX_SANDBOX) {
+    return {
+      name: 'codex',
+    };
+  }
+
+  // Cursor Agent (proposed / best-effort; Cursor often sets VSCode env vars too)
+  if (env.CURSOR_AGENT) {
+    return {
+      name: 'cursor',
+    };
+  }
+
+  // Generic "AGENT" marker (unknown implementation)
+  if (env.AGENT) {
+    return { name: 'unknown' };
+  }
+
+  return undefined;
+}
+
+/** Detect whether Storybook CLI is likely being invoked by an AI agent. */
+export const detectAgent = (options: DetectAgentOptions): AgentDetection => {
+  const env = options.env;
+
+  // 1) Explicit agent variables (strong signal; allow even in CI/TTY)
+  const explicit = detectExplicitAgent(env);
+  if (explicit) {
+    return explicit;
+  }
+
+  const stdoutIsTTY = options.stdoutIsTTY;
+
+  // 2) Behavioral / fingerprint heuristics (exclude CI to reduce false positives)
+  if (stdoutIsTTY) {
+    return undefined;
+  }
+
+  const isDumbTerm = env.TERM === 'dumb';
+  const hasAgentPager = env.GIT_PAGER === 'cat';
+
+  if (isDumbTerm || hasAgentPager) {
+    return { name: 'unknown' };
+  }
+
+  return undefined;
+};

code/core/src/telemetry/telemetry.ts

@@ -11,6 +11,7 @@ import { nanoid } from 'nanoid';
 import { version } from '../../package.json';
 import { resolvePackageDir } from '../shared/utils/module';
 import { getAnonymousProjectId } from './anonymous-id';
+import { detectAgent } from './detect-agent';
 import { set as saveToCache } from './event-cache';
 import { fetch } from './fetch';
 import { getSessionId } from './session-id';
@@ -49,9 +50,12 @@ const getOperatingSystem = (): 'Windows' | 'macOS' | 'Linux' | `Other: ${string}
 // context info sent with all events, provided
 // by the app. currently:
 // - cliVersion
+const inCI = isCI();
+const agentDetection = detectAgent({ stdoutIsTTY: process.stdout.isTTY, env: process.env });
 const globalContext = {
-  inCI: isCI(),
+  inCI,
   isTTY: process.stdout.isTTY,
+  agent: agentDetection,
   platform: getOperatingSystem(),
   nodeVersion: process.versions.node,
   storybookVersion: getVersionNumber(),

code/core/src/telemetry/types.ts

@@ -2,6 +2,7 @@ import type { StorybookConfig, TypescriptOptions } from 'storybook/internal/type
 
 import type { DetectResult } from 'package-manager-detector';
 
+import type { AgentInfo } from './detect-agent';
 import type { KnownPackagesList } from './get-known-packages';
 import type { MonorepoType } from './get-monorepo-type';
 
@@ -56,6 +57,8 @@ export type StorybookMetadata = {
   storybookVersionSpecifier: string;
   generatedAt?: number;
   userSince?: number;
+  /** If we can identify the agent, report it; otherwise `unknown` when detected heuristically. */
+  agent?: AgentInfo;
   language: 'typescript' | 'javascript';
   framework?: {
     name?: string;