mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* 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.
257 lines
9.1 KiB
TypeScript
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 };
|
|
}
|