feat: identify every gitops API request with a User-Agent

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: small — a behavior change: every API request now carries a new header. No blast-radius path.

• Problem: we can't measure how gitops is used beyond simulations. Only npm run sim and npm run check identify themselves. Setup, pull, push, apply, promote, cleanup, rollback, call and audit send Node's default User-Agent, node, which was 126k of 728k api.vapi.ai requests in one hour this morning. So "how many deploys come from gitops, from CI or from laptops" has no answer.
• Who it affects: the Vapi team measuring adoption after the public launch. Customers see no change in behavior.
• What changes:
  • src/user-agent.ts builds vapi-gitops-<command>/<version>, plus (ci) when CI or GITHUB_ACTIONS is set:
    • <command> is the npm script that started the process. So npm run apply labels the pull and push it runs as apply, and a promotion's applies are labelled promote.
    • When a script is run directly, as the PR check workflow does, it falls back to the entry script's name.
    • sim and check keep their fixed labels, which existing simulation analytics already counts by.
  • Every fetch to the Vapi API sends it: api.ts (push, pull, apply, promote), cleanup, setup, the interactive pickers, rollback, call, and push's direct fetch.
  • Fixes two tests that called production. cleanup-safety and new-file-gate sent about 12 requests per npm test to api.vapi.ai, with a fake key, getting 401s. That breaks the repo's own rule that tests never call the real API, and with this PR it would have counted every fork's CI run as gitops usage. They now point at a dead local address.
  • Docs: how-it-works.md says exactly what the API sees (and that there is no other telemetry). AGENTS.md says every request must send the header.

Evidence of value

Live, through the Cloudflare request logs in Axiom (cloudflare-logpush): a read-only npm run setup -- ua-check --resources none against the test org, run from a scratch copy:

User-Agent	Requests	Status
vapi-gitops-setup/1.0.0	13 GET	200
vapi-gitops-test/1.0.0	24 GET	401 — the two leaky tests, from the two npm test runs before the fix

Before this PR, both rows would have been indistinguishable node traffic.

Tests:

• tests/user-agent-coverage.test.ts reads every fetch( in src/ and requires a User-Agent. On the parent branch it lists 10 call sites without one; here it lists none. It also runs api.ts against a local server with npm_lifecycle_event=apply.
• tests/user-agent.test.ts pins the format: fixed sim and check labels, npm script vs. entry script vs. cli, label cleaning, and the CI marker for GITHUB_ACTIONS=true, CI=true and CI=1 (but not false, 0 or empty).
• No more production calls: running the full suite with a fetch trap that records any request to vapi.ai caught 12 requests before the test fix and none after.

Testing plan

• npm test (527 tests) and npx tsc --noEmit pass.
• Not covered:
  • Distinct-org counts for non-simulation commands. The request logs carry the User-Agent but not the org. Only simulation runs get an org ID, through PostHog. Joining the two needs an API-side change, outside this repo.
  • The version is still 1.0.0; bumping it is deliberately left out of this PR.
  • The call command's WebSocket audio connection isn't a Vapi REST request and doesn't carry the header.

Refs TEST-141

🤖 Generated with Claude Code

[scott-lowe-vapi]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: identify every gitops API request with a User-Agent #78 👈 (View in Graphite)
• feat(validate): catch broken references and show findings on the PR #77
• ci: validate every org's resources on every pull request #76
• ci: lint workflows and test the PR check's key-sharing decision #75
• test(docs): check that doc links, commands and flags exist #74
• fix(cleanup): never delete resources matched by .vapi-ignore #73
• docs(agents): one compact guide for Claude, Codex and Cursor #72
• docs: edit the guides for new readers and fix inaccuracies #71
• docs: restructure the README into a short landing page and topic guides #70
• docs: prepare for public release: scrub internal names, fix examples, add community files #69
• feat(promotion): gate promotion out of an org on a passing check #66
• fix(promotion): commit the files of transitions that applied when a later one fails #65
• test(promotion): pin the exact files promoting an assistant writes to the target #68
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.