Tag events/v2 telemetry with X-Mapbox-Agent during agent-driven test runs

[ctufts]

This adds test-only tooling that lets this repo's own test suite tag the telemetry events/v2 request it fires when running under an AI coding agent (Claude Code, Codex, Cursor, etc.), so agent-driven test/CI traffic can be told apart from normal usage.

Browsers won't let scripts set the User-Agent header, and GL JS running in a page has no way to know it's being driven by a coding agent: that signal only exists in the Node process running the Playwright/Vitest test driver, via env vars the agent sets (e.g. CLAUDECODE for Claude Code). To get that signal from Node into the browser:

• test/integration/lib/agent-forwarding.ts (new, test-only) checks process.env against an allowlist of about 20 known agent env-var indicators, first match wins by table order, with a validated fallback to a generic AI_AGENT/AGENT env var. It never throws. If nothing matches, it returns nothing rather than a vague "unknown", so no header gets sent.
• A small Vite transformIndexHtml plugin, wired into the render and query integration test configs, forwards that id into the browser as window.__mapboxAgent before any other page script runs (same idea as a Playwright page.addInitScript).
• TelemetryEvent.postEvent (src/util/mapbox.ts) reads window.__mapboxAgent defensively and, if it's present, adds an X-Mapbox-Agent header to the events/v2 request.

agent-forwarding.ts is never imported by production code and isn't part of the shipped bundle. The postEvent change is a no-op anywhere window.__mapboxAgent isn't set (npm run dev, a consuming app, or a worker context without window), so behavior there is unchanged.

Testing

• Unit tests cover the agent-detection logic (allowlist precedence, exact-match vs. presence-check entries, charset validation on the fallback env vars, and the never-throws/no-"unknown" guarantees) and postEvent (header added when window.__mapboxAgent is set, absent otherwise).
• npm run lint, npm run test-typings, and npm run test-unit pass locally.
• I couldn't run the full browser-driven render/query integration suite in my environment (needs a built dist bundle and a real browser session), so an actual end-to-end capture of the header on an events/v2 request is unverified beyond the unit tests above.

Downstream impact

None for consuming applications: this only touches this repo's own test tooling and adds one conditional header to a telemetry request that's already unauthenticated and opt-in via access token configuration.

Operational considerations

The X-Mapbox-Agent header won't be visible/actionable server-side until the events ingestion endpoint is updated to accept and record it (tracked separately, outside this repo).

Launch Checklist

• Make sure the PR title is descriptive and preferably reflects the change from the user's perspective.
• Add additional detail and context in the PR description (with screenshots/videos if there are visual changes).
• Manually test the debug page.
• Write tests for all new functionality and make sure the CI checks pass.
• Document any changes to public APIs.
• Post benchmark scores if the change could affect performance.
• Tag @mapbox/map-design-team @mapbox/static-apis if this PR includes style spec API or visual changes.
• Tag @mapbox/gl-native if this PR includes shader changes or needs a native port.
• Tag @mapbox/gl-native if this PR disables any test because it also needs to be disabled on their side.
• Create a ticket for gl-native to groom in the MAPSNAT JIRA queue if this PR includes shader changes or features not present in the native side or if it disables a test that's not disabled there.

[github-actions]

Hey, @ctufts 👋 Thanks for your contribution to Mapbox GL JS!

Important: This repository does not accept direct merges. All changes go through our internal review process.

What happens next:

1. A team member will review your PR here first
2. If it looks good, they will import it to our internal repository for further review
3. If approved, changes will be synced back here via our release process

Please respond to any review comments on this PR. For more details, see CONTRIBUTING.md.