Files
hyperframes/packages/cli/src/telemetry/system.ts
T
Miguel Ángel c50918277a perf(engine): fast capture stays on for frames a shadow, blur or clip effect does not touch (#6318)
* perf(engine): fast capture stays on for frames a shadow, blur or clip effect does not touch

A single drop-shadow, blur, backdrop-filter or blend element, or one clip-path or mask
tween, sent the whole render to screenshot capture, 2-3x slower than drawElement. The two
init gates now name the frames the effect can show on. Only those frames capture by
screenshot, in a second browser opened on the first of them; every other frame keeps
drawElement.

* fix(engine): scan effects in a throwaway session; hand risk frames over only where captured

The effect scan seeked the render's own page to the end, leaving its timeline state ahead of
the render. It now runs in a throwaway session with the render's own seek. A hidden effect
element with a visible descendant counts as shown. Per-frame capture is opt-in per caller
(deFrameFallback), so disk, segmented, chunk and parallel-worker sessions keep the
whole-render fallback, and a route that cannot hand frames over drops drawElement up front.

* fix(engine): a timeline callback keeps the whole-render fallback; trim comment share

A tl.call or onComplete can add an effect's class to any element mid-render, so the elements
found at the start are not the only ones it can reach. Such a timeline is unbounded and keeps
the whole-render screenshot fallback.

* style(engine): shorten the live-frame scan comment

* perf(engine): after a timeline callback, not before, every frame may show the effect

A callback can add an effect's class to any element, so only the frames from the first
callback on lose their element bounds. Frames before it keep the scanned bounds, so a late
callback no longer sends the whole render to screenshot capture.

* perf(engine): open the second screenshot browser only when memory is available for it

Per-frame capture needs a second browser (479 MB measured at 1080p). When the render would
leave less than 1.5 GB available after it, the render keeps the whole-render screenshot
fallback instead. getAvailableMemoryMb moves from the CLI to the engine's system-memory
module, which already owns the host's memory readings; os.freemem() reads 367 MB on this
49 GB Mac, so the guard uses free, inactive, speculative and purgeable pages.

* fix(engine): budget the whole 1 GB per-frame capture adds, not just the second browser

The render's process tree goes from 1002 to 2001 MB at 1080p: the screenshot browser (479 MB)
plus a drawElement browser that is itself about 500 MB larger than a screenshot one. The guard
budgeted 500 MB. It now budgets the 1 GB measured, scaled by output pixels.
2026-10-25 19:15:18 +00:00

257 lines
9.1 KiB
TypeScript

import { cpus, 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";
export { getAvailableMemoryMb } 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 };
}