Skip to content

Write HTML. Render video. Built for agents.

7.0 KB
Raw Blame
import {
  getIdentityPersistence,
  getIdentityWriteOutcome,
  readConfig,
  writeConfig,
} from "./config.js";
import { getInvocationId } from "./runId.js";
import { VERSION } from "../version.js";
import { c } from "../ui/colors.js";
import { diag } from "../ui/diagnostics.js";
import { getSystemMeta } from "./system.js";
import { canaryEventProperties } from "./canary.js";
import { enqueue, type EventProperties } from "./transport.js";
import { telemetryRuntimeOverride } from "./policy.js";

// ---------------------------------------------------------------------------
// CLI-facing telemetry policy: opt-out checks, system-metadata enrichment, and
// the first-run disclosure notice. The reliability-critical delivery layer
// (the event queue, `flush()`, and the exit-time `flushSync()`) lives in
// transport.ts. `flush` / `flushSync` are re-exported here so existing callers
// (events.ts, index.ts, the cli.ts exit handlers) keep importing from
// `./client.js` unchanged.
// ---------------------------------------------------------------------------

export { flush, flushSync } from "./transport.js";

let telemetryEnabled: boolean | null = null;

/**
 * Check if telemetry should be active.
 * Disabled when: a privacy env var is set, this is a development or
 * telemetry-disabled build, or the persisted preference is off.
 */
export function shouldTrack(): boolean {
  if (telemetryEnabled !== null) return telemetryEnabled;

  if (telemetryRuntimeOverride() !== null) {
    telemetryEnabled = false;
    return false;
  }

  const config = readConfig();
  telemetryEnabled = config.telemetryEnabled;
  return telemetryEnabled;
}

/**
 * Drop the cached posture so the next `shouldTrack()` re-reads the persisted
 * preference.
 *
 * The memo is right for a CLI command — one process, one answer, and the
 * question is asked per event. It is wrong for `hyperframes preview`, which
 * lives for hours: run `hyperframes telemetry disable` in another terminal and
 * this process kept the old answer indefinitely, still resolving canaries and
 * still injecting the CLI id into every page load. Callers that serve requests
 * refresh at a request boundary; see `refreshTelemetryPosture` in
 * server/telemetryIdentity.ts, which invalidates this and the config cache
 * together so the two cannot disagree.
 */
export function resetTelemetryPostureCache(): void {
  telemetryEnabled = null;
}

/**
 * Queue a telemetry event. Non-blocking, fail-silent.
 * Enriches the event with system metadata, then hands it to the transport
 * queue (which stamps the dedup uuid + timestamp).
 */
export function trackEvent(
  event: string,
  properties: EventProperties = {},
  distinctId?: string,
): void {
  if (!shouldTrack()) return;

  const sys = getSystemMeta();
  enqueue(
    event,
    {
      ...properties,
      cli_version: VERSION,
      os: process.platform,
      arch: process.arch,
      node_version: process.version,
      os_release: sys.os_release,
      cpu_count: sys.cpu_count,
      cpu_model: sys.cpu_model ?? undefined,
      cpu_speed: sys.cpu_speed ?? undefined,
      memory_total_mb: sys.memory_total_mb,
      is_docker: sys.is_docker,
      is_ci: sys.is_ci,
      ci_name: sys.ci_name ?? undefined,
      is_wsl: sys.is_wsl,
      is_tty: sys.is_tty,
      sandbox_runtime: sys.sandbox_runtime ?? undefined,
      agent_runtime: sys.agent_runtime ?? undefined,
      execution_harness_hint: sys.execution_harness_hint ?? undefined,
      // New-agent discovery signals — populated only when agent_runtime is null.
      agent_hint: sys.agent_hint ?? undefined,
      term_program: sys.term_program ?? undefined,
      // Did this install's mint find a previous install's state marker?
      // The fleet-wide rate of `true` IS the recoverable-churn fraction —
      // the share of "new" ids that are really a config re-mint on a machine
      // we already knew. Absent (not false) when the config predates the
      // marker. Resolved after the shouldTrack guard.
      install_predecessor_found: readConfig().predecessorFound,
      // Splits the `true` share above: a machine we knew but whose record we
      // could not read. Without it a partial disk write is indistinguishable
      // from a genuinely fresh install. Absent in the normal case.
      install_state_file_corrupt: readConfig().stateFileCorrupt,
      // Whether this process's anonymousId can be trusted to survive to the
      // next run: `durable` (loaded from a preexisting config), `unknown`
      // (minted+persisted this run — an ephemeral HOME is indistinguishable
      // from a genuine first run), `process_only` (not persisted). Install-
      // grain metrics must also consider environment and repeated-day use:
      // a short-lived container can persist its id between two CLI processes.
      identity_persistence: getIdentityPersistence(),
      // Outcome of the identity-establishing config write; absent when that
      // path did not write (including a durable id loaded from disk).
      config_write_outcome: getIdentityWriteOutcome(),
      // Groups one invocation's events even when the install identity is
      // untrustworthy. Always present, unlike the orchestrator-set run_id.
      invocation_id: getInvocationId(),
      // Canary assignments as `$feature/canary-<name>` — PostHog's native flag
      // property shape, so breakdowns and experiment analysis work on a canary
      // with nothing configured server-side. On EVERY event, not just renders:
      // a staged rollout is only as good as the ability to split any metric by
      // cohort. Resolved after the shouldTrack guard, so opted-out installs
      // never pay for it. See telemetry/canary.ts.
      ...canaryEventProperties(),
      agent_env_hints: sys.agent_env_hints ?? undefined,
      client: sys.client ?? undefined,
    },
    distinctId,
  );
}

/**
 * Show the first-run telemetry notice if it hasn't been shown yet.
 * Must be called BEFORE any tracking calls so the user sees the disclosure
 * before any data is sent.
 */
export function showTelemetryNotice(): boolean {
  if (!shouldTrack()) return false;

  const config = readConfig();
  if (config.telemetryNoticeShown) return false;

  // Persist the notice flag first, before any tracking occurs,
  // so the user is never tracked without having seen the disclosure.
  config.telemetryNoticeShown = true;
  writeConfig(config);

  // stderr (via diag), not stdout: this first-run disclosure is not gated by
  // --json (the guard in cli.ts filters by command only), so a stdout banner
  // would corrupt the JSON envelope of the very first `check --json` etc.
  diag.notice();
  diag.notice(`  ${c.dim("Hyperframes collects anonymous usage data to improve the tool.")}`);
  diag.notice(`  ${c.dim("File paths and composition content are never collected.")}`);
  diag.notice(
    `  ${c.dim("If you sign in to HeyGen, your account (email, or username) is linked to your usage.")}`,
  );
  diag.notice();
  diag.notice(`  ${c.dim("Disable anytime:")} ${c.accent("hyperframes telemetry disable")}`);
  diag.notice();

  return true;
}