feat(cli): report the client environment on API requests

[kylegani]

Stack position: 2 of 2. Stacked on #102 — this diff is against it, not main.

Problem

Every request already carries X-Source: cli and X-CLI-Version, but nothing says what invoked the CLI. An agent-driven deploy and an engineer at a terminal are indistinguishable, so deploy-side agent metrics can only split on the calling principal: currently around 32% of deploying principals are automation against around 70% of build volume, and that gap is one undifferentiated blob of service accounts belonging to CI, to coding agents, and to internal tooling.

Change

internal/clientenv classifies the invoking environment into one of three shapes, emitted as X-Client-Env:

• agent:<name> for a detected agent
• ci for a CI system (CI, plus 13 vendor variables)
• interactive otherwise

Wired onto the JSON API client, the multipart RunApp path and both device-auth endpoints. Computed once per process.

The agent matrix mirrors vercel/detect-agent agents.json (schema version 1): 20 agents, its identifiers verbatim (including its mixed claude_code and cursor-cli styles) and its array order, since order decides which of two simultaneous markers wins. TestAgentDetectorsMatchRegistryOrder pins both, so a drifting sync fails instead of silently reclassifying traffic. The registry promotes AI_AGENT as the cross-vendor self-declaration variable, which we honour.

Two deliberate narrowings, both flagged in the code:

• replit is gated on the absence of a TTY. REPL_ID is set for every process on Replit including a human in the editor, so bare REPL_ID evidences the host, not an agent. This is the registry's own stated reasoning for kiro ("set by both the IDE terminal and the CLI agent, so gate on no_tty to avoid misdetecting a human at the integrated terminal") applied to the variable with the same problem. Following the registry literally here would have put humans in the agent bucket, which is the exact overcount this header exists to avoid.
• AI_AGENT is evaluated first, not as a fallback, so an operator wrapping a known agent can name their own harness and have that win.

Detection never influences behaviour: no output default, no prompt suppression, nothing branches on it. That is why the non-TTY deploy guard from #87 keys off stdin rather than agent detection. Detect takes its environment, filesystem and TTY probes as parameters, so the matrix is tested without touching the real environment.

AI_AGENT values are caller-supplied, so they are lowercased, restricted to [a-z0-9._-] and capped at 64 characters. A value that sanitizes to nothing becomes agent:unknown rather than degrading to interactive, keeping a declared-but-unparseable agent in the agent bucket.

Not in scope

The header is only stored once dashboard-backend #4132 lands; until then it is accepted and discarded. X- prefixes are discouraged for new headers by RFC 6648, but this joins an existing X-Source / X-CLI-Version / X-Client-OS family and consistency won.

Test

go test ./internal/clientenv/... ./internal/api/... ./internal/auth/... green: 58 detection cases (one per registry variable, both TTY branches for the two host-gated agents, the three ordering rules, the AI_AGENT sanitizer and the CI matrix), plus header-presence tests on the API client and both OAuth endpoints.

gofmt clean. golangci-lint run ./internal/clientenv/... reports 0 issues; on the other touched packages the single finding (nilerr in internal/auth/docker.go) is pre-existing, verified by re-running against a stash. Repo-wide make lint and go build ./... fail on vendored cortex/server/node_modules AWS CDK templates, unrelated and also failing on main.

🤖 Generated with Claude Code

[kylegani]

Per Wesley's suggestion, b9e5e41 swaps the hand-rolled detection matrix for github.com/vercel/detect-agent v1.2.0 (their Go implementation, zero transitive deps). clientenv.go went 271 -> 118 lines and its tests 407 -> 104 (now testing only our wrapper: header format, CI, sanitization, agent-beats-CI precedence).

Unchanged: the X-Client-Env header format, CI detection, interactive fallback, and the sanitize-to-agent:unknown rule; detection still cannot affect behavior (any Detect error falls through).

Three small semantic deltas from adopting upstream as-is: Replit now matches on REPL_ID alone (we previously gated it on no-TTY), the AI_AGENT github-copilot-cli normalization is dropped (raw sanitized value passes through), and Kiro's TTY gate uses upstream's stdout check instead of our stdin isatty. All three seem fine to inherit rather than fork over.

[kylegani]

One follow-up in 061b076 + 693791f: the header now preserves the AI_AGENT @Version suffix (the documented detect-agent convention is name@version, e.g. devin@1; our charset was stripping @ and merging version digits into the name), and agent ids are normalized to lowercase-hyphen (agent:claude-code, agent:gemini-cli). Rationale for the normalization: upstream's name strings mix underscores and hyphens with no stability guarantee, and these values become long-lived analytics dimensions on builds, so a one-line separator normalization keeps our recorded history stable across upstream renames and matches the hyphenated ids the ecosystem registries use. Still zero mapping tables to maintain.

[wesrobin]

LGTM