feat(studio): instrument the audio FX rack, including work an agent did

packages/cli/src/server/telemetryIdentity.test.ts

@@ -17,6 +17,11 @@ const canaryDecisions = vi.fn<() => Record<string, { enabled: boolean; forced: b
 // assertion below ran against a refresh that silently did nothing.
 const resetPostureCache = vi.fn();
 const readConfigFresh = vi.fn();
+// Mocked for the same reason as the canary registry above: the real detector
+// reads THIS process env, so every string assertion here would pass on a
+// developer laptop and fail the moment an agent ran the suite (CLAUDECODE=1),
+// or vice versa. The agent-specific behaviour gets its own cases below.
+const detectAgent = vi.fn<() => string | null>();
 
 vi.mock("../telemetry/client.js", () => ({
   shouldTrack: (...args: unknown[]) => shouldTrack(...args),
@@ -26,6 +31,9 @@ vi.mock("../telemetry/config.js", () => ({
   readConfig: (...args: unknown[]) => readConfig(...args),
   readConfigFresh: () => readConfigFresh(),
 }));
+vi.mock("../telemetry/agent_runtime.js", () => ({
+  detectAgentRuntime: () => detectAgent(),
+}));
 vi.mock("../telemetry/canary.js", () => ({
   canaryDecisionsForStudio: () => canaryDecisions(),
 }));
@@ -46,6 +54,10 @@ describe("resolveCliTelemetryDistinctId", () => {
     readConfig.mockReset();
     canaryDecisions.mockReset();
     canaryDecisions.mockReturnValue({});
+    detectAgent.mockReset();
+    // No agent is the default so the existing assertions keep describing the
+    // ordinary case: a person at a terminal.
+    detectAgent.mockReturnValue(null);
   });
 
   it("returns the CLI anonymousId when telemetry is enabled", () => {
@@ -393,3 +405,61 @@ describe("cross-process opt-out refresh", () => {
     expect(after).not.toContain("__HF_CLI_BUCKET_SEED");
   });
 });
+
+/**
+ * Publishing which agent, if any, drives the CLI.
+ *
+ * Studio has no way to detect this — the signal is in the CLI process
+ * environment, which the browser never sees — so this injection is the only
+ * path by which an agent-driven session can ever be labelled as one.
+ */
+describe("buildCliIdentityScript agent runtime", () => {
+  beforeEach(() => {
+    shouldTrack.mockReset();
+    readConfig.mockReset();
+    readConfig.mockReturnValue({});
+    canaryDecisions.mockReset();
+    canaryDecisions.mockReturnValue({});
+    detectAgent.mockReset();
+    detectAgent.mockReturnValue(null);
+  });
+
+  it("publishes the agent when one is driving the CLI", () => {
+    shouldTrack.mockReturnValue(true);
+    detectAgent.mockReturnValue("claude_code");
+    expect(buildCliIdentityScript()).toContain('window.__HF_CLI_AGENT_RUNTIME="claude_code";');
+  });
+
+  it("publishes nothing when a person is driving it", () => {
+    shouldTrack.mockReturnValue(true);
+    expect(buildCliIdentityScript()).not.toContain("__HF_CLI_AGENT_RUNTIME");
+  });
+
+  it("stays silent when telemetry is off, even under an agent", () => {
+    // Unlike the canary decisions, which Studio needs in order NOT to enrol,
+    // this is only ever read to label an event. With telemetry off there is no
+    // event, so publishing it would leave a marker in the page of someone who
+    // asked not to be measured.
+    shouldTrack.mockReturnValue(false);
+    detectAgent.mockReturnValue("claude_code");
+    expect(buildCliIdentityScript()).not.toContain("__HF_CLI_AGENT_RUNTIME");
+  });
+
+  it("publishes it without an identity when the Host is not trusted", () => {
+    // The value is a category, not an id — a LAN Studio should still be able to
+    // say an agent opened it, the same way it still receives canary decisions.
+    shouldTrack.mockReturnValue(true);
+    detectAgent.mockReturnValue("codex");
+    const script = buildCliIdentityScript({ includeIdentity: false });
+    expect(script).toContain('window.__HF_CLI_AGENT_RUNTIME="codex";');
+    expect(script).not.toContain("__HF_CLI_DISTINCT_ID");
+  });
+
+  it("escapes a value that tries to close the script tag", () => {
+    shouldTrack.mockReturnValue(true);
+    detectAgent.mockReturnValue("</script><script>alert(1)</script>");
+    const script = buildCliIdentityScript();
+    expect(script).not.toContain("</script><script>");
+    expect(script.match(/<\/script>/g)).toHaveLength(1);
+  });
+});

packages/cli/src/server/telemetryIdentity.ts

@@ -23,6 +23,7 @@ import {
   shouldTrack as telemetryShouldTrack,
 } from "../telemetry/client.js";
 import { canaryDecisionsForStudio, type CliCanaryDecision } from "../telemetry/canary.js";
+import { detectAgentRuntime } from "../telemetry/agent_runtime.js";
 
 /**
  * The CLI's anonymous distinct id to hand to Studio, or null when CLI telemetry
@@ -156,6 +157,27 @@ export function buildCliIdentityScript(options: { includeIdentity?: boolean } =
     parts.push(`window.__HF_CLI_CANARY_DECISIONS=${encodeInlineScriptJson(decisions)};`);
   }
 
+  // Which agent, if any, is driving this CLI — and therefore the Studio it just
+  // opened. Studio cannot work this out for itself: the signal is entirely in
+  // the CLI process's environment, which the browser never sees.
+  //
+  // Published on the same terms as the decisions above, and for the same
+  // reason: it is a category derived from the EXISTENCE of well-known vendor
+  // env vars, never their values (`agent_runtime.ts` is explicit that it never
+  // reads a value, because some are API keys). One of a dozen fixed strings, or
+  // absent. Nothing identifying, so it does not belong behind the trusted-Host
+  // gate that gates the distinct id.
+  //
+  // Gated on telemetry being ON, unlike the decisions above. Those exist so a
+  // Studio whose CLI opted out does not enrol itself, so they have to survive
+  // the opt-out. This is only ever read to label an event, so with telemetry off
+  // there is nothing for it to label — publishing it anyway would leave a marker
+  // in the page of a user who asked not to be measured.
+  const agent = telemetryShouldTrack() ? detectAgentRuntime() : null;
+  if (agent) {
+    parts.push(`window.__HF_CLI_AGENT_RUNTIME=${encodeInlineScriptValue(agent)};`);
+  }
+
   return parts.length === 0 ? "" : `<script>${parts.join("")}</script>`;
 }
 

packages/studio/src/components/editor/audioFxTelemetry.test.ts

@@ -0,0 +1,129 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+
+const trackStudioEvent = vi.fn();
+vi.mock("../../utils/studioTelemetry", () => ({
+  trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
+}));
+
+const { chainShape, nodeOrigin, trackChainObserved, trackParamCommitted, trackPresetApplied } =
+  await import("./audioFxTelemetry");
+
+beforeEach(() => trackStudioEvent.mockReset());
+
+const chainOf = (nodes: HfAudioFxChain["nodes"]): HfAudioFxChain => ({ version: 1, nodes });
+
+describe("what the rack reports", () => {
+  it("namespaces every event so the feature can be found as one thing", () => {
+    trackPresetApplied("voice-clean", "voice", 5, "append", { trackKind: "voice" });
+    expect(trackStudioEvent).toHaveBeenCalledWith("audio_fx_preset_applied", expect.anything());
+  });
+
+  it("carries what the track is, so a preset's use can be read per material", () => {
+    trackPresetApplied("telephone", "character", 7, "append", { trackKind: "music" });
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({
+      preset: "telephone",
+      family: "character",
+      track_kind: "music",
+    });
+  });
+
+  it("says 'unknown' rather than nothing when the track is unclassified", () => {
+    // Absent and "unclassified" are different facts; encoding them the same way
+    // is what makes a breakdown read as a gap that is not there.
+    trackPresetApplied("hall", "space", 1, "append", {});
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({ track_kind: "unknown" });
+  });
+
+  it("separates the two surfaces a parameter can be set from", () => {
+    // The whole one-knob design rests on which of these people use.
+    trackParamCommitted("compressor", "ratio", 4, "details", {});
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({
+      effect: "compressor",
+      param: "ratio",
+      value: 4,
+      surface: "details",
+    });
+  });
+});
+
+describe("a chain reduced to counts", () => {
+  it("names where each node came from", () => {
+    expect(nodeOrigin({ type: "peaking", fromPreset: "voice-clean" })).toBe("preset");
+    expect(nodeOrigin({ type: "peaking", fromCarve: true })).toBe("carve");
+    expect(nodeOrigin({ type: "gain", fromLeveller: true })).toBe("leveller");
+    expect(nodeOrigin({ type: "highpass" })).toBe("hand");
+  });
+
+  it("counts by origin, which is what separates hand-built from generated", () => {
+    const shape = chainShape(
+      chainOf([
+        { type: "highpass", fromPreset: "voice-clean" },
+        { type: "peaking", fromPreset: "voice-clean" },
+        { type: "peaking", fromCarve: true },
+        { type: "lowpass" },
+      ]),
+    );
+    expect(shape).toMatchObject({
+      node_count: 4,
+      nodes_from_preset: 2,
+      nodes_from_carve: 1,
+      nodes_by_hand: 1,
+      preset_count: 1,
+    });
+  });
+
+  it("counts distinct presets, not preset nodes — stacking is the question", () => {
+    const shape = chainShape(
+      chainOf([
+        { type: "highpass", fromPreset: "voice-clean" },
+        { type: "lowpass", fromPreset: "telephone" },
+        { type: "peaking", fromPreset: "telephone" },
+      ]),
+    );
+    expect(shape.preset_count).toBe(2);
+  });
+
+  it("survives an empty or absent chain", () => {
+    expect(chainShape(null)).toMatchObject({ node_count: 0, preset_count: 0 });
+  });
+
+  it("ships no chain contents — only counts and flags", () => {
+    // The standing rule: nothing user-authored leaves the browser. A parameter
+    // value or an element id in here would be the author's own data.
+    const shape = chainShape(chainOf([{ type: "peaking", id: "n1", params: { frequency: 3000 } }]));
+    const serialized = JSON.stringify(shape);
+    expect(serialized).not.toContain("3000");
+    expect(serialized).not.toContain("n1");
+  });
+});
+
+describe("effects this session did not apply", () => {
+  it("calls a chain with no panel edits behind it authored outside", () => {
+    // This is the agent signal. An agent edits the composition and the panel
+    // simply finds the work done — none of its own events ever fire.
+    trackChainObserved(
+      chainOf([{ type: "highpass", fromPreset: "voice-clean" }]),
+      { firstSight: true, panelEdits: 0, hasCarve: false, hasAutomation: false },
+      { trackKind: "voice" },
+    );
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "audio_fx_chain_observed",
+      expect.objectContaining({ authored_outside: true, first_sight: true }),
+    );
+  });
+
+  it("does not, when this session's own edits explain it", () => {
+    trackChainObserved(
+      chainOf([{ type: "highpass" }]),
+      { firstSight: false, panelEdits: 3, hasCarve: false, hasAutomation: false },
+      {},
+    );
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({
+      authored_outside: false,
+      panel_edits: 3,
+    });
+  });
+});