feat(analytics): attribute requests by client surface and add CLI usage telemetry

[waleedlatif1]

Summary

• Add X-Sim-Client-Info (<surface>[/version]; <runtime>/<v>; os/<os>; arch/<arch>; agent/<slug>) as the one header every official client sends; parser/formatter/resolver in @sim/utils/client-info
• withRouteHandler resolves the client once (header → legacy sim-cli/ user agent → Fetch Metadata for uncredentialed browser requests) into the logger request context; every log line and server-side PostHog event now carries surface, client_version, coding_agent
• Route builders and hybrid/v1 auth stamp how the request authenticated (auth_kind, auth_service, auth_client_id); the workflow call chain from X-Sim-Via and the API method/path are stamped too
• Web app sends the header from requestJson; desktop shell stamps desktop/<version>; electron/<v> on every app-origin request from the main process; posthog-js registers surface and app_version as super properties
• CLI: X-Sim-Client-Info with coding-agent detection (Claude Code, Codex, Cursor, Gemini CLI, Amp, Cline, and the generic AI_AGENT/AGENT conventions), plus anonymous usage telemetry — one cli_command_executed event per command (command path, flag names only, arg count, exit code, duration, session sequence), sent from a detached child so the prompt never waits
• Telemetry is opt-out with a first-run notice, honours DO_NOT_TRACK and SIM_TELEMETRY_DISABLED, adds sim telemetry status|enable|disable, and only reports from builds made with SIM_CLI_TELEMETRY_KEY (public PostHog token injected at publish time via --env); the agent hint is withheld when reporting is off
• TypeScript and Python SDKs send X-Sim-Client-Info and a User-Agent
• Docs: new CLI "Usage data" guide, telemetry command page, env var tables

Type of Change

• New feature

Testing

• Unit tests for the header grammar, route-wrapper context, PostHog merging, builder auth stamping, desktop header injection, CLI telemetry (state, policy, transport, invocation, agent detection), SDK headers
• bun run check:audits, check:api-validation, check:cli-docs, docs-manifest:check, repo lint, and type-check across all touched packages pass
• Verified the CLI build inlines the key and that a build without one reports nothing

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 11, 2026 5:32am UTC

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no actionable new failure remains from the changes since the previous review.

Summary

• Introduces the shared X-Sim-Client-Info formatter, parser, and resolver.
• Propagates client, workflow-call-chain, API, and authentication metadata through request context.
• Adds client identification to the web, desktop, CLI, TypeScript SDK, and Python SDK.
• Adds opt-out-aware CLI telemetry, detached delivery, first-run disclosure, configuration commands, tests, publishing configuration, and documentation.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Web[Web app] -->|X-Sim-Client-Info| API[Sim API route wrapper]
  Desktop[Desktop shell] -->|X-Sim-Client-Info| API
  CLI[Sim CLI] -->|Client info and optional agent| API
  TS[TypeScript SDK] -->|Client info| API
  Python[Python SDK] -->|Client info| API

  API --> Context[Request context]
  Auth[Route authentication] -->|auth attribution| Context
  Via[X-Sim-Via and API route] -->|call-chain attribution| Context
  Context --> Logs[Structured logs]
  Context --> ServerPH[Server-side PostHog]

  CLI -->|Anonymous command event when enabled| Detached[Detached telemetry process]
  Detached --> CLIAnalytics[PostHog ingestion]

Loading

_{Reviews (2) · Last reviewed commit: "fix(analytics): tolerate get-only header..."}

[waleedlatif1]

@greptile