Skip to content

Write HTML. Render video. Built for agents.

10.5 KB
Raw Blame
import { cpus, freemem, platform, release } from "node:os";
import { existsSync, readFileSync, statfsSync } from "node:fs";
import { execSync } from "node:child_process";
import { getSystemTotalMb } from "@hyperframes/engine/system-memory";
import {
  detectAgentRuntime,
  detectAgentHints,
  detectExecutionHarnessHint,
  detectSandboxRuntime,
  type AgentRuntime,
  type SandboxRuntime,
} from "./agent_runtime.js";
import { detectWSL } from "./platform.js";

// ---------------------------------------------------------------------------
// System metadata collected once per CLI session and attached to all events.
// Follows the same patterns as Next.js, Turborepo, and Gatsby telemetry.
// No PII — only hardware/environment characteristics useful for debugging.
// ---------------------------------------------------------------------------

/** Convert bytes to whole megabytes. */
export function bytesToMb(bytes: number): number {
  return Math.trunc(bytes / (1024 * 1024));
}

export interface SystemMeta {
  os_release: string;
  cpu_count: number;
  cpu_model: string | null;
  cpu_speed: number | null;
  memory_total_mb: number;
  is_docker: boolean;
  is_ci: boolean;
  ci_name: string | null;
  is_wsl: boolean;
  is_tty: boolean;
  /**
   * Managed sandbox runtime hosting this invocation, when one is detectable
   * (gvisor / firecracker / docker / kvm / wsl). null on a normal dev
   * machine. Lets us distinguish "real laptop" from "ephemeral cloud
   * sandbox driving the CLI" without geo guesswork.
   */
  sandbox_runtime: SandboxRuntime;
  /**
   * Coding-agent vendor that spawned this process, if any (see the
   * `AgentRuntime` union in agent_runtime.ts for the full, current set).
   * Most rules check env-var existence only — values are never read; a few
   * use filesystem/kernel markers (e.g. the Gemini managed-agent mount).
   * Every rule keys on a marker with a source citation in agent_runtime.ts;
   * unverified guesses are deliberately omitted (false-negative > guess).
   * null when no agent is detected.
   */
  agent_runtime: AgentRuntime;
  /** Observed harness context, independent of agent attribution; null if absent. */
  execution_harness_hint: "harbor" | null;
  /**
   * New-agent discovery signals for the agent_runtime=null bucket, so an agent
   * we have no rule for surfaces on its own instead of vanishing into null.
   * All three are null on a classified event (agent_runtime != null) and on a
   * plain shell with no markers. See `detectAgentHints` in agent_runtime.ts for
   * the fields and the privacy contract.
   */
  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.
 */
export function getSystemMeta(): SystemMeta {
  if (cached) return cached;

  const cpuInfo = cpus();
  const firstCpu = cpuInfo[0] ?? null;

  // Only compute discovery hints for the unclassified bucket — a known agent
  // needs no hint, and gating keeps them off the ~80%+ of classified events.
  const agent_runtime = detectAgentRuntime();
  const hints =
    agent_runtime === null
      ? detectAgentHints()
      : { agent_hint: null, term_program: null, agent_env_hints: null };

  cached = {
    os_release: release(),
    cpu_count: cpuInfo.length,
    cpu_model: firstCpu?.model?.trim() ?? null,
    cpu_speed: firstCpu?.speed ?? null,
    memory_total_mb: getSystemTotalMb(),
    is_docker: detectDocker(),
    is_ci: detectCI(),
    ci_name: getCIName(),
    is_wsl: detectWSL(),
    is_tty: Boolean(process.stdout?.isTTY),
    sandbox_runtime: detectSandboxRuntime(),
    agent_runtime,
    execution_harness_hint: detectExecutionHarnessHint(),
    agent_hint: hints.agent_hint,
    term_program: hints.term_program,
    agent_env_hints: hints.agent_env_hints,
    client: readClientTag(),
  };
  return cached;
}

// ---------------------------------------------------------------------------
// Environment detectors
// ---------------------------------------------------------------------------

function detectDocker(): boolean {
  // Standard detection: /.dockerenv file or "docker" in /proc/1/cgroup
  try {
    if (existsSync("/.dockerenv")) return true;
    if (platform() === "linux") {
      const cgroup = readFileSync("/proc/1/cgroup", "utf-8");
      if (cgroup.includes("docker") || cgroup.includes("containerd")) return true;
    }
  } catch {
    // Ignore — not in Docker
  }
  return false;
}

// Named providers come first so getCIName() picks the most specific match.
// `truthy` accepts 'true' or '1'; `presence` matches any non-null value.
type CIProvider =
  | { name: string | null; envVar: string; mode: "truthy" }
  | { name: string | null; envVar: string; mode: "presence" };

const CI_PROVIDERS: CIProvider[] = [
  { name: "github_actions", envVar: "GITHUB_ACTIONS", mode: "truthy" },
  { name: "gitlab_ci", envVar: "GITLAB_CI", mode: "truthy" },
  { name: "circleci", envVar: "CIRCLECI", mode: "truthy" },
  { name: "jenkins", envVar: "JENKINS_URL", mode: "presence" },
  { name: "buildkite", envVar: "BUILDKITE", mode: "truthy" },
  { name: "travis", envVar: "TRAVIS", mode: "truthy" },
  { name: null, envVar: "CONTINUOUS_INTEGRATION", mode: "truthy" },
  { name: null, envVar: "CI", mode: "truthy" },
];

function matchesProvider(p: CIProvider): boolean {
  const v = process.env[p.envVar];
  if (p.mode === "presence") return v != null;
  return v === "true" || v === "1";
}

function detectCI(): boolean {
  return CI_PROVIDERS.some(matchesProvider);
}

function getCIName(): string | null {
  for (const provider of CI_PROVIDERS) {
    if (provider.name && matchesProvider(provider)) return provider.name;
  }
  return detectCI() ? "unknown" : null;
}

// ---------------------------------------------------------------------------
// Extended hardware checks (for doctor command and detailed render events)
// ---------------------------------------------------------------------------

/**
 * Get /dev/shm size in MB (Linux only). Chrome uses shared memory heavily;
 * Docker's default 64MB limit causes crashes.
 */
export function getShmSizeMb(): number | null {
  if (platform() !== "linux") return null;
  try {
    const stats = statfsSync("/dev/shm");
    return bytesToMb(stats.bsize * stats.blocks);
  } catch {
    return null;
  }
}

/**
 * Get available disk space in MB at a given path.
 */
export function getFreeDiskMb(path: string = "."): number | null {
  try {
    const stats = statfsSync(path);
    return bytesToMb(stats.bsize * stats.bavail);
  } catch {
    return null;
  }
}

export interface PowerState {
  /** true = running on battery, false = external power, null = undetectable. */
  on_battery: boolean | null;
  /** macOS Low Power Mode; null off-darwin or undetectable. */
  low_power_mode: boolean | null;
}

/**
 * Parse `pmset -g batt` output for the power source line. Exported for tests.
 * Example first line: `Now drawing from 'Battery Power'`.
 */
export function parsePmsetPowerSource(raw: string): boolean | null {
  const m = raw.match(/Now drawing from '([^']+)'/);
  if (!m) return null;
  return m[1] === "Battery Power";
}

/**
 * Sample the machine's power state. Volatile — sample at event time, never
 * cache alongside SystemMeta.
 *
 * Why this exists: the DE fast path only engages on macOS + hardware GPU, so
 * the render fleet is overwhelmingly laptops, and laptop perf is
 * power-managed — bench sweeps on an M4 Pro showed the SAME render flipping
 * between ~9.6 and ~17.2 ms/frame regimes with no load/thermal signal to
 * explain it. Without a power-state dimension on render telemetry those
 * regimes are indistinguishable noise; with it, perf distributions (and the
 * DE parallel-router soak) can be segmented by the machine state real users
 * actually render in.
 */
export function getPowerState(): PowerState {
  if (platform() !== "darwin") {
    // Linux laptops exist but the DE fleet is darwin; don't guess elsewhere.
    return { on_battery: null, low_power_mode: null };
  }
  let on_battery: boolean | null = null;
  let low_power_mode: boolean | null = null;
  try {
    on_battery = parsePmsetPowerSource(
      execSync("pmset -g batt", { encoding: "utf-8", timeout: 2000 }),
    );
  } catch {
    // pmset missing/slow — leave null rather than fail telemetry.
  }
  try {
    const raw = execSync("pmset -g", { encoding: "utf-8", timeout: 2000 });
    const m = raw.match(/lowpowermode\s+(\d)/);
    if (m) low_power_mode = m[1] === "1";
  } catch {
    // Same: absence of the reading is itself acceptable.
  }
  return { on_battery, low_power_mode };
}

/**
 * Get available memory in MB, accounting for OS-level page caching.
 *
 * `os.freemem()` on macOS returns only truly free pages — ignoring
 * inactive/purgeable/speculative pages that the kernel reclaims on demand.
 * On a 24 GB Mac this reports ~0.1 GB "free" when ~5 GB is actually
 * available. Linux has a similar (milder) issue; its kernel exposes the
 * correct value via `MemAvailable` in /proc/meminfo.
 */
export function getAvailableMemoryMb(): number {
  const fallback = bytesToMb(freemem());

  if (platform() === "darwin") {
    try {
      const raw = execSync("vm_stat", { encoding: "utf-8", timeout: 5000 });
      const pageSize = parseInt(raw.match(/page size of (\d+)/)?.[1] ?? "0", 10);
      if (!pageSize) return fallback;

      const pages = (key: string) =>
        parseInt(raw.match(new RegExp(`${key}:\\s+(\\d+)`))?.[1] ?? "0", 10);

      const available =
        (pages("Pages free") +
          pages("Pages inactive") +
          pages("Pages purgeable") +
          pages("Pages speculative")) *
        pageSize;

      return available > 0 ? bytesToMb(available) : fallback;
    } catch {
      return fallback;
    }
  }

  if (platform() === "linux") {
    try {
      const meminfo = readFileSync("/proc/meminfo", "utf-8");
      const match = meminfo.match(/MemAvailable:\s+(\d+)\s+kB/);
      if (match) {
        return Math.trunc(parseInt(match[1]!, 10) / 1024);
      }
      return fallback;
    } catch {
      return fallback;
    }
  }

  return fallback;
}