feat(telemetry): anonymous opt-out usage telemetry (stack, cost, deploy-shape, CLI usage, call funnel)

[nicolotognoni]

Summary

Adds anonymous, opt-out usage telemetry to both SDKs (Python getpatter + TypeScript getpatter) so the maintainers can see, in aggregate, how the SDK is actually used — which engines, providers, models, and carriers people choose, on which platforms, at which versions — and prioritise accordingly. It follows the open-source norm (Next.js, Astro, Homebrew): on by default, completely anonymous, trivially disabled, and fail-safe so it can never block, slow, or break a live phone call.

No PII or call content is ever collected. Every field is a coarse enum, bucket, or bool, enforced by a two-layer allowlist (key and value) in the SDK and re-validated server-side by the collector.

Events

Event	When	Carries (all coarse / PII-safe)
sdk_initialized	SDK construction	version, language, OS/arch, runtime, install id, upgrade funnel, carrier, tunnel, and presence-only deploy-shape probes (AI-agent invoker, container, serverless, cloud, package manager)
first_run	once per install	activation marker — same anonymous deploy-shape dims; never sent when opted out
cli_command	every getpatter CLI run	the command name only (dashboard / eval / telemetry / other) — never arguments or flags
feature_used	first use of a stack	engine + provider family, and for pipeline the composed stack: vendor + sanitized model token per layer (e.g. anthropic-claude-haiku-4-5, deepgram-nova-3)
agent_configured	per agent shape	bucketed tool counts, integration category, and which coarse features are enabled
call_started	a call connects	engine / provider / carrier / direction — pairs with call_completed for a connect→complete funnel
call_completed	a call ends	outcome, direction (inbound/outbound), error code (the code, never the message), duration, latency, cost, bucketed turn count

Privacy posture

Never collected: phone numbers, transcripts, audio, prompts, tool arguments, API keys, customer identifiers, IPs (dropped at the collector), hostnames, file paths, or any free text. Custom / self-hosted model names and custom tool names are structurally impossible to send — they collapse to a vendor bucket or other before anything leaves the process. The two identifiers (run_id, install_id) are random UUIDs, never derived from hardware.

Opt out — any one of

• Patter(telemetry=False) / new Patter({ telemetry: false })
• getpatter telemetry disable (persisted, machine-level; re-enable with getpatter telemetry enable, inspect with getpatter telemetry status)
• PATTER_TELEMETRY_DISABLED=1, or the cross-tool standard DO_NOT_TRACK=1

Auto-disabled in CI/test. Inspect-without-send: PATTER_TELEMETRY_DEBUG=1 prints each event to stderr and sends nothing. Redirect to your own collector with PATTER_TELEMETRY_ENDPOINT.

Implementation notes

• New telemetry/ module in each SDK: events (schema + allowlist), consent, client (bounded buffer, short timeouts, swallow-all, best-effort exit flush), stack (vendor + PII-safe model sanitizer), environment (presence-only probes), install_id, call_metrics.
• Schema is at v5; Python ↔ TypeScript verified byte-for-byte (7 events, 23 dimensions).
• The README gains an OSS-standard Anonymous Telemetry disclosure (what we collect / what we never collect / not PII / opt-out incl. CLI + debug), and docs/telemetry.mdx documents every field.
• Fail-isolation is load-bearing: every emit is wrapped so a telemetry bug can never break SDK construction, a call, or the CLI.

Test plan

• Python suite green (telemetry: dedicated authentic tests with a real local HTTP collector)
• TypeScript suite green (telemetry: dedicated tests)
• tsc --noEmit clean
• Python ↔ TypeScript schema parity verified byte-for-byte
• Off-list values (custom tool/integration/model names, unknown commands/directions) verified to coerce to other and never reach the wire raw
• Opt-out paths (env vars, DO_NOT_TRACK, in-code flag, persisted CLI marker, CI/test auto-disable, debug inspect-only) verified to produce zero egress