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> comes from a fixed list of this repo's commands, so a fork's own npm script names are never sent. The first process pins its label in VAPI_GITOPS_COMMAND, which child processes inherit: npm run apply labels its pull and push apply, a promotion's applies are promote, and the PR check's bindings pull is check. Promotion gate runs are labelled promote, apart from PR check runs.
    • 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

After review

• Labels: come only from the known command list, and are pinned for child processes (Chris's 🟠: the PR check's bindings pull was counted as a CI pull). npx and fork script names fall through to the entry script, then to cli.
• GitHub status call: now sends the User-Agent too, so every fetch in src/ does. The coverage test checks each call on its own and scans subfolders.
• tests/no-vapi-api.ts: loads before every test file, with an unroutable base URL and no inherited real key. With a pretend key exported and a fetch trap on, the suite makes zero requests to vapi.ai.
• Docs: how-it-works.md matches the code on (ci) and <command>.
• Formatting: the unrelated Prettier changes are reverted.

🤖 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.

[chris-garber-vapi]

Aggressive review: 1 🟠, 3 🟡, 4 🟢, no blockers.

The main problem: the label doesn't reach child processes when a command isn't started through npm run, so PR check runs are counted as CI pulls (🟠 on user-agent.ts:61). The fix for that also keeps the label set bounded (🟡 on :63).

Every comment says what I checked. Every fix was tried on a copy of 674d8a1: tsc and npm test pass.

Not part of this diff, so no inline comment: under npm run promote, the promotion gate's simulation runs still send vapi-gitops-check/… (promotion-gate.ts:90). That means check-run counts include promotion gates.

[scott-lowe-vapi]

@chris-garber-vapi on the gate label from your summary: done. Promotion gate runs now send vapi-gitops-promote/…, so PR check counts no longer include gate runs. The sim and check prefixes are unchanged.

🤖 Generated with Claude Code