Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cli): tag telemetry and feedback with the app that launched the CLI (#4632)
Miguel Ángelfa044a89e562
diff --git a/docs/guides/feedback.mdx b/docs/guides/feedback.mdxindex 7f110a4d0f..eeb3d19bf7 100644--- a/docs/guides/feedback.mdx+++ b/docs/guides/feedback.mdx@@ -62,7 +62,7 @@ Do not include API keys, access tokens, credentials, private media, or customerHyperFrames may occasionally show a short rating prompt after a render or during a Studio session. You can ignore or dismiss it.-Feedback can include the rating, an optional comment, and basic environment information used to understand the problem. It does not include your composition HTML, video files, project names, file paths, or environment-variable values.+Feedback can include the rating, an optional comment, and basic environment information used to understand the problem. It does not include your composition HTML, video files, project names, file paths, or environment-variable values beyond the short agent and app names listed under [`telemetry`](/packages/cli#telemetry), such as `client=example-app/1.2.3/stable` when another app launched the CLI.To turn off CLI telemetry:diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdxindex c3e4ee4fd7..78dc13ac61 100644--- a/docs/packages/cli.mdx+++ b/docs/packages/cli.mdx@@ -1236,10 +1236,12 @@ Studio installs and which of the two installed them, and system info — includienvironment fingerprint: OS, kernel string, CPU and memory shape, sandboxruntime such as gVisor or Docker, and the _name_ of a coding agent driving theCLI when one is detected (`claude_code`, `codex`, `cursor`). That name is-inferred from which well-known environment variables exist; their values are-never read. Local paths and URL query strings are redacted from error and+inferred from which well-known environment variables exist. Local paths and URL query strings are redacted from error andcheckpoint messages. Project names, video content, and environment variable-values are never collected.+values are never collected, except short self-identifying names: `AGENT`,+`AI_AGENT` and `TERM_PROGRAM` (filtered to short slugs), and `HYPERFRAMES_CLIENT`,+the `<app>/<version>/<channel>` tag an app that launches the CLI sets, sent as+`client` so reports from that app can be told apart.Nothing personally identifying is collected until you sign in. When you run`hyperframes auth login`, your HeyGen account email — or username, if thediff --git a/packages/cli/src/telemetry/client.test.ts b/packages/cli/src/telemetry/client.test.tsindex bd947ecdfb..e393ecaffd 100644--- a/packages/cli/src/telemetry/client.test.ts+++ b/packages/cli/src/telemetry/client.test.ts@@ -54,7 +54,7 @@ vi.mock("node:child_process", () => ({const { trackEvent, flush, flushSync } = await import("./client.js");const system = await import("./system.js");-type Batch = { uuid: string; event: string }[];+type Batch = { uuid: string; event: string; properties: Record<string, unknown> }[];function sentBatch(fetchMock: ReturnType<typeof vi.fn>, call = 0): Batch {const init = fetchMock.mock.calls[call]?.[1] as { body: string } | undefined;@@ -106,6 +106,29 @@ describe("telemetry queue delivery", () => {}});+ it("tags every event, feedback and catalog misses included, with the launching app", async () => {+ const meta = vi.spyOn(system, "getSystemMeta").mockReturnValue({+ ...system.getSystemMeta(),+ client: "example-app/1.2.3/stable",+ });+ try {+ const fetchMock = vi.fn(() => Promise.resolve(new Response("")));+ vi.stubGlobal("fetch", fetchMock);+ const { trackRenderFeedback, trackCatalogSearchMiss } = await import("./events.js");+ trackEvent("cli_command", { command: "lint" });+ trackRenderFeedback({ rating: 9 });+ trackCatalogSearchMiss({ query: "confetti" });+ await flush();+ expect(sentBatch(fetchMock).map((e) => [e.event, e.properties.client])).toEqual([+ ["cli_command", "example-app/1.2.3/stable"],+ ["cli_render_feedback", "example-app/1.2.3/stable"],+ ["cli_catalog_search_miss", "example-app/1.2.3/stable"],+ ]);+ } finally {+ meta.mockRestore();+ }+ });+it("keeps events queued for the exit-time send when DNS does not answer", async () => {dns.answers = false;const fetchMock = vi.fn(() => Promise.resolve(new Response("")));diff --git a/packages/cli/src/telemetry/client.ts b/packages/cli/src/telemetry/client.tsindex 38340ab2ff..edfed5cb27 100644--- a/packages/cli/src/telemetry/client.ts+++ b/packages/cli/src/telemetry/client.ts@@ -129,6 +129,7 @@ export function trackEvent(// never pay for it. See telemetry/canary.ts....canaryEventProperties(),agent_env_hints: sys.agent_env_hints ?? undefined,+ client: sys.client ?? undefined,},distinctId,);diff --git a/packages/cli/src/telemetry/feedback.test.ts b/packages/cli/src/telemetry/feedback.test.tsnew file mode 100644index 0000000000..f204bce345--- /dev/null+++ b/packages/cli/src/telemetry/feedback.test.ts@@ -0,0 +1,9 @@+import { afterEach, expect, it, vi } from "vitest";++afterEach(() => vi.unstubAllEnvs());++it("names the launching app in the feedback env string", async () => {+ vi.stubEnv("HYPERFRAMES_CLIENT", "example-app/1.2.3/stable");+ const { getDoctorSummary } = await import("./feedback.js");+ expect((await getDoctorSummary()).split(" ")).toContain("client=example-app/1.2.3/stable");+});diff --git a/packages/cli/src/telemetry/feedback.ts b/packages/cli/src/telemetry/feedback.tsindex 620c000220..3aa55295f3 100644--- a/packages/cli/src/telemetry/feedback.ts+++ b/packages/cli/src/telemetry/feedback.ts@@ -102,6 +102,7 @@ export async function getDoctorSummary(): Promise<string> {];if (sys.is_docker) parts.push("docker");if (sys.is_wsl) parts.push("wsl");+ if (sys.client) parts.push(`client=${sys.client}`);return parts.join(" ");} catch {return "";diff --git a/packages/cli/src/telemetry/system.test.ts b/packages/cli/src/telemetry/system.test.tsindex 669578611d..1ee8e7c5da 100644--- a/packages/cli/src/telemetry/system.test.ts+++ b/packages/cli/src/telemetry/system.test.ts@@ -26,6 +26,32 @@ describe("getSystemMeta execution context", () => {});});+describe("getSystemMeta client", () => {+ afterEach(() => vi.unstubAllEnvs());++ it("reads the launching app's tag from HYPERFRAMES_CLIENT", async () => {+ vi.stubEnv("HYPERFRAMES_CLIENT", "example-app/1.2.3/stable");+ const { getSystemMeta } = await import("./system.js");+ expect(getSystemMeta().client).toBe("example-app/1.2.3/stable");+ });++ it("is null when the CLI runs from a shell", async () => {+ vi.stubEnv("HYPERFRAMES_CLIENT", "");+ const { getSystemMeta } = await import("./system.js");+ expect(getSystemMeta().client).toBeNull();+ });++ it.each([+ "example-app/1.2.3 build 7",+ "example-app/1.2.3\nstable",+ `example-app/${"9".repeat(80)}`,+ ])("drops a tag that is not a short slash-separated slug: %j", async (tag) => {+ vi.stubEnv("HYPERFRAMES_CLIENT", tag);+ const { getSystemMeta } = await import("./system.js");+ expect(getSystemMeta().client).toBeNull();+ });+});+describe("getAvailableMemoryMb", () => {it("parses vm_stat on macOS to compute available memory", async () => {vi.doMock("node:os", async () => ({diff --git a/packages/cli/src/telemetry/system.ts b/packages/cli/src/telemetry/system.tsindex ce793ece35..4cc32bed96 100644--- a/packages/cli/src/telemetry/system.ts+++ b/packages/cli/src/telemetry/system.ts@@ -63,10 +63,20 @@ export interface SystemMeta {agent_hint: string | null;term_program: string | null;agent_env_hints: string | null;+ /** App that launched the CLI, from HYPERFRAMES_CLIENT (`<app>/<version>/<channel>`); null from a shell. */+ client: string | null;}let cached: SystemMeta | null = null;+// Short `<app>/<version>/<channel>`-shaped tags only: the value lands verbatim in the space-delimited feedback string.+const CLIENT_TAG = /^[a-z0-9][a-z0-9._+-]{0,31}(\/[a-z0-9._+-]{1,32}){0,3}$/i;++function readClientTag(): string | null {+ const tag = process.env["HYPERFRAMES_CLIENT"]?.trim() ?? "";+ return CLIENT_TAG.test(tag) ? tag : null;+}+/*** Collect system metadata. Cached after first call.* Only includes static values — use `freemem()` directly for volatile readings.@@ -102,6 +112,7 @@ export function getSystemMeta(): SystemMeta {agent_hint: hints.agent_hint,term_program: hints.term_program,agent_env_hints: hints.agent_env_hints,+ client: readClientTag(),};return cached;}diff --git a/skills-manifest.json b/skills-manifest.jsonindex fd62a8d3ae..77c13c3a5b 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -30,7 +30,7 @@"files": 7},"hyperframes-cli": {- "hash": "272d811ab4564fb7",+ "hash": "2617903119c32228","files": 11},"hyperframes-core": {diff --git a/skills/hyperframes-cli/references/upgrade-info-misc.md b/skills/hyperframes-cli/references/upgrade-info-misc.mdindex cb7b90d14b..5366192b9d 100644--- a/skills/hyperframes-cli/references/upgrade-info-misc.md+++ b/skills/hyperframes-cli/references/upgrade-info-misc.md@@ -111,6 +111,7 @@ Events include two fingerprint properties used to distinguish managed-sandbox ru- **`sandbox_runtime`**: `gvisor` / `firecracker` / `docker` / `kvm` / `wsl` / `null`. gVisor via kernel string + `/proc/version`. Firecracker via `/dev/vsock` + DMI sys_vendor. Docker via `/.dockerenv` + cgroup.- **`agent_runtime`**: `claude_code` / `codex` / `cursor` / `copilot_agent` / `jules` / `replit` / `devin` / `aider` / `gemini_cli` / `hermes` / `openclaw` / `null`. Detected by the existence of well-known vendor env vars; the values themselves are never read.+- **`client`**: set only when an app launched the CLI with a `HYPERFRAMES_CLIENT` tag (`<app>/<version>/<channel>`), sent as-is when it is a short slug.## Asset Preprocessing