Skip to content

Write HTML. Render video. Built for agents.

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.mdx
index 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 customer
HyperFrames 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.mdx
index 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 — includi
environment fingerprint: OS, kernel string, CPU and memory shape, sandbox
runtime such as gVisor or Docker, and the _name_ of a coding agent driving the
CLI 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 and
checkpoint 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 the
diff --git a/packages/cli/src/telemetry/client.test.ts b/packages/cli/src/telemetry/client.test.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.md
index 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