Files
Hubert Gancarczyk 8483fe23f9 feat: add telemetry (#274)
## Summary

Adds anonymous, opt-out telemetry for Argent installer, update/uninstall
flows, CLI telemetry controls, tool-server lifecycle, and tool
invocation health signals.
## What Changed
- Added a new private `@argent/telemetry` package
- Introduced typed telemetry events with runtime property
allowlisting/sanitization.
- Added lazy anonymous identity creation in `~/.argent/telemetry-id`.
- Added consent handling via: `argent telemetry enable`, `argent
telemetry disable`, `argent telemetry status`
- Added local debug logging with `ARGENT_TELEMETRY_DEBUG=1`.
- Tracks installer funnel events for init, global install/update
decisions, editor selection, allowlist decisions, skill installation,
rules/agents copy, update, and uninstall.
- Tracks tool-server start/stop and tool invocation/complete/fail
events.
- Adds per-tool invocation IDs so request metadata can be correlated
without relying on ordering.
- Records only coarse platform metadata (`ios` / `android`) for device
tools
- Ensures short-lived commands drain telemetry with bounded shutdown
before exit.
- Wires telemetry package into bundling and injects full Argent CLI
version metadata at build time.
- Added central `FAILURE_CODES` and `FailureSignal` helpers in
`@argent/registry`.
- Attached structured, sanitized failure metadata across registry
errors, tool-server tools/services, HTTP validation/dependency gates,
installer flows, and `argent run`.
- Added telemetry allowlisting for safe failure fields only: static
error codes/stages, coarse area/kind/command, bounded exit codes,
allowlisted signals/spawn codes, and coarse network failure classes.
- Split CLI-local `argent run` failures into `cli:run_fail` so they are
not double-counted as tool failures.
- Added installer telemetry for failed package actions, update/uninstall
failures, rules/agents copy results, and skill refresh results.
- Made telemetry consent writes atomic and kept telemetry status
side-effect free via `peekAnonId()`.
- Adds a coarse, anonymous signal to tool telemetry: which AI coding
tool is driving the MCP server (Claude Code, Codex, Cursor, Gemini, VS
Code, Windsurf, Zed, opencode, Copilot, or other).

## Tests Added / Updated

- Telemetry unit coverage for consent precedence, identity creation,
base props, sanitization, PostHog config, debug logging, shutdown,
opt-out, and forget behavior.
- Registry/tool-server tests for invocation IDs, platform metadata
boundaries, startup failure flushing, and tool lifecycle telemetry.
- Installer tests for final telemetry drain, update action
classification, and uninstall identity cleanup ordering.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-19 18:22:34 +02:00

60 lines
1.8 KiB
TypeScript

import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
import { afterEach, beforeEach } from "vitest";
import { _resetConsentCacheForTest } from "../src/consent.js";
import { _resetIdentityCacheForTest } from "../src/identity.js";
let savedHome: string | undefined;
let savedUserProfile: string | undefined;
// Point telemetry home resolution at a vitest-scoped temp directory.
export function useTempHome(): { tmp: string } {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "argent-telemetry-"));
savedHome = process.env.HOME;
savedUserProfile = process.env.USERPROFILE;
process.env.HOME = tmp;
process.env.USERPROFILE = tmp;
return { tmp };
}
export function restoreHome(tmp: string): void {
if (savedHome === undefined) delete process.env.HOME;
else process.env.HOME = savedHome;
if (savedUserProfile === undefined) delete process.env.USERPROFILE;
else process.env.USERPROFILE = savedUserProfile;
try {
fs.rmSync(tmp, { recursive: true, force: true });
} catch {
/* best-effort */
}
_resetConsentCacheForTest();
_resetIdentityCacheForTest();
}
export function scopeHome(): { tmp: () => string } {
let active: string;
beforeEach(() => {
const { tmp } = useTempHome();
active = tmp;
});
afterEach(() => {
restoreHome(active);
});
return { tmp: () => active };
}
export function withEnv(snapshot: Record<string, string | undefined>): void {
for (const [k, v] of Object.entries(snapshot)) {
if (v === undefined) delete process.env[k];
else process.env[k] = v;
}
}
/** Snapshot env vars and return a restorer. */
export function snapshotEnv(keys: string[]): () => void {
const saved: Record<string, string | undefined> = {};
for (const k of keys) saved[k] = process.env[k];
return () => withEnv(saved);
}