@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/host-load.d.ts

@@ -0,0 +1,156 @@
+/**
+ * What this machine can say about its own load, read straight from `/proc`.
+ *
+ * Until this existed, an overloaded dev server was visible in exactly one
+ * place: `sar` on the machine itself. The product could not say «this machine
+ * is on its knees», so it said nothing, and the first symptom a user saw was a
+ * session that had gone quiet (plan `agent-sessions-host-resources.md` §5.3).
+ *
+ * Two files and nothing else. That is a security property, not an
+ * implementation detail: this runner reports to a server, so what it may read
+ * for telemetry is listed here in full — `/proc/loadavg` and `/proc/meminfo`,
+ * both world-readable, neither containing a path, a command line, an
+ * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
+ *
+ * Mirror of `packages/shared/src/schemas/host-load.ts` and the `HOST_LOAD_*`
+ * block of `packages/shared/src/constants/runner.ts` — the DevBridge side is
+ * the source of truth, exactly like `levels.ts` mirrors the level thresholds
+ * and `protocol.ts` mirrors the API's wire types. Copied rather than imported
+ * on purpose: this package is published to npm on its own and installed by
+ * users who have no DevBridge workspace, so a `@devbridge/shared` import would
+ * make the published tarball unresolvable (see `recipe-schema.ts`).
+ *
+ * CHECKED: `host-load.test.ts` reads the shared file and compares every number
+ * below against it. A threshold edited on one side only would make the runner
+ * send frames the API throws away — or go silent while a card waits for one.
+ */
+/**
+ * How often the runner LOOKS at `/proc`. Not how often it sends.
+ *
+ * Fine enough that a card is never more than half a minute stale, coarse
+ * enough that reading two small files costs nothing measurable.
+ */
+export declare const HOST_LOAD_SAMPLE_INTERVAL_MS = 30000;
+/**
+ * The heartbeat: an unchanged machine still reports this often.
+ *
+ * Without it a quiet runner would go silent and the API's key would expire,
+ * turning «nothing is happening» into «we have no idea» on the card. With it,
+ * silence really does mean the runner stopped talking.
+ *
+ * Bound to the API's `HOST_LOAD_TTL_MS` (120 s), and the order is the design:
+ * a heartbeat LONGER than the TTL means a healthy quiet machine shows «no
+ * data» for the gap between them. The first draft had 5 minutes against a
+ * 2-minute TTL — three silent minutes out of every five.
+ */
+export declare const HOST_LOAD_HEARTBEAT_MS = 60000;
+/**
+ * How much load1 must move before an otherwise unchanged sample earns a frame.
+ *
+ * Same principle as `publishSlots`: a tick that would repeat what the server
+ * already knows is not sent at all. 0.5 is below the resolution at which a
+ * person reads the number and well above the noise of an idle machine.
+ */
+export declare const HOST_LOAD_MIN_DELTA_LOAD1 = 0.5;
+/** The same idea for memory, as a fraction — see `hostLoadChangedEnough`. */
+export declare const HOST_LOAD_MIN_DELTA_MEM_RATIO = 0.05;
+/**
+ * One measurement of this machine. Only the moving parts.
+ *
+ * `machine: {cpuCount, memTotalBytes, memAvailableBytes}` already travels in
+ * `hello` (`index.ts`), so nothing static is repeated here. `cpuCount` is the
+ * exception and it earns its place: load1 is meaningless without it, and a
+ * consumer that had to join two sources to answer «is 12.4 a lot?» would
+ * eventually paint one machine's load against another's core count.
+ */
+export interface HostLoadFrame {
+    /** `/proc/loadavg`, the three windows as the kernel reports them. */
+    load1: number;
+    load5: number;
+    load15: number;
+    /** Processors, so load1 can be read as a ratio without a second lookup. */
+    cpuCount: number;
+    /**
+     * `MemAvailable`, not `MemFree` — the kernel's own estimate of what a new
+     * allocation could actually get. `MemFree` on a healthy Linux box is near
+     * zero by design (page cache), and a card drawn from it would cry wolf on
+     * every machine, every minute.
+     */
+    memAvailableBytes: number;
+    /** Zero on a machine with no swap; consumers must not divide blindly. */
+    swapTotalBytes: number;
+    swapFreeBytes: number;
+    /**
+     * When THIS MACHINE measured it, ISO.
+     *
+     * Load-bearing, same as in `agent_versions`: frames without a session id take
+     * the gateway's unordered fast path, so two of these can be handled out of
+     * order. The card dates the number by this field, never by arrival.
+     */
+    at: string;
+}
+/** Test seams. Production calls `readHostLoad()` with nothing. */
+export interface HostLoadSources {
+    /**
+     * Where `/proc` is mounted. A seam so the parser can be driven by fixtures:
+     * a test that had to arrange the real kernel into a state would not be
+     * written, and the states worth covering (no swap, no `MemAvailable`, no
+     * file at all) cannot be arranged at all.
+     */
+    procDir?: string;
+    /** Processors. Seam for the same reason — a test cannot change its own. */
+    cpuCount?: number;
+    /** The clock behind `at`. */
+    now?: () => Date;
+}
+/**
+ * Measure this machine, or say honestly that we cannot.
+ *
+ * `null` is a first-class answer and every caller must treat it as «send
+ * nothing». There is deliberately no `process.platform` check in front of it:
+ * the absence of the files IS the check, and it is the wider one — it also
+ * covers a Linux container with `/proc` masked or mounted `hidepid`, which a
+ * platform test would sail straight past into an exception. The runner is
+ * Linux-only by its installer, but «only runs on Linux» must never mean
+ * «crashes anywhere else»: this is called from a timer, and an exception here
+ * would take the whole session supervisor with it.
+ */
+export declare function readHostLoad(sources?: HostLoadSources): HostLoadFrame | null;
+/**
+ * Is the heartbeat due, given how long ago the last frame actually went out?
+ *
+ * The second half of the answer is the whole reason this is a function: a
+ * backwards clock step makes «how long ago» NEGATIVE, and a machine whose load
+ * never moves would then say nothing for the entire offset — an hour of silence
+ * on a machine that may be on fire. A clock correction is due, not early.
+ *
+ * The API makes the same allowance for the same step, and has to: it drops
+ * frames older than the one it holds unless the step is larger than a
+ * measurement's lifetime (`HOST_LOAD_TTL_MS`, `runner-gateway.ts`). Half of this
+ * fix on one side of the socket is no fix at all.
+ */
+export declare function hostLoadHeartbeatDue(sinceLastSentMs: number, heartbeatMs: number): boolean;
+/**
+ * Is this sample worth a frame at all? The «a quiet runner says nothing» rule.
+ *
+ * Same shape as `publishSlots`: what the server already knows is not repeated.
+ * The alternative is 2 880 identical frames a day per machine, each one waking
+ * the gateway, a Redis write and every open dashboard socket.
+ *
+ * The memory threshold is 5 % of the machine's TOTAL memory, not 5 % of what
+ * is currently available. Two reasons, and both were the deciding one:
+ *
+ *  - a fraction of `memAvailable` shrinks as the machine fills, so the frames
+ *    would get chattiest exactly when the machine is least able to afford it —
+ *    5 % of the last 200 MB is a 10 MB trigger;
+ *  - `memTotal` is fixed per machine, so «the card moves when a GB moves» reads
+ *    the same on every server instead of meaning something different on each.
+ *
+ * Swap counts too, though the plan names only load and memory. It is one of the
+ * three verdicts behind «overloaded», and it is the only one with no other
+ * trigger: a machine that starts paging with its load and its `MemAvailable`
+ * both flat would otherwise wait up to five minutes for the heartbeat to say
+ * so, and paging is the state whose wall-clock cost is unbounded.
+ */
+export declare function hostLoadChangedEnough(previous: HostLoadFrame | null, next: HostLoadFrame, memTotalBytes?: number): boolean;
+//# sourceMappingURL=host-load.d.ts.map

package/dist/host-load.js

@@ -0,0 +1,223 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * What this machine can say about its own load, read straight from `/proc`.
+ *
+ * Until this existed, an overloaded dev server was visible in exactly one
+ * place: `sar` on the machine itself. The product could not say «this machine
+ * is on its knees», so it said nothing, and the first symptom a user saw was a
+ * session that had gone quiet (plan `agent-sessions-host-resources.md` §5.3).
+ *
+ * Two files and nothing else. That is a security property, not an
+ * implementation detail: this runner reports to a server, so what it may read
+ * for telemetry is listed here in full — `/proc/loadavg` and `/proc/meminfo`,
+ * both world-readable, neither containing a path, a command line, an
+ * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
+ *
+ * Mirror of `packages/shared/src/schemas/host-load.ts` and the `HOST_LOAD_*`
+ * block of `packages/shared/src/constants/runner.ts` — the DevBridge side is
+ * the source of truth, exactly like `levels.ts` mirrors the level thresholds
+ * and `protocol.ts` mirrors the API's wire types. Copied rather than imported
+ * on purpose: this package is published to npm on its own and installed by
+ * users who have no DevBridge workspace, so a `@devbridge/shared` import would
+ * make the published tarball unresolvable (see `recipe-schema.ts`).
+ *
+ * CHECKED: `host-load.test.ts` reads the shared file and compares every number
+ * below against it. A threshold edited on one side only would make the runner
+ * send frames the API throws away — or go silent while a card waits for one.
+ */
+/**
+ * How often the runner LOOKS at `/proc`. Not how often it sends.
+ *
+ * Fine enough that a card is never more than half a minute stale, coarse
+ * enough that reading two small files costs nothing measurable.
+ */
+export const HOST_LOAD_SAMPLE_INTERVAL_MS = 30_000;
+/**
+ * The heartbeat: an unchanged machine still reports this often.
+ *
+ * Without it a quiet runner would go silent and the API's key would expire,
+ * turning «nothing is happening» into «we have no idea» on the card. With it,
+ * silence really does mean the runner stopped talking.
+ *
+ * Bound to the API's `HOST_LOAD_TTL_MS` (120 s), and the order is the design:
+ * a heartbeat LONGER than the TTL means a healthy quiet machine shows «no
+ * data» for the gap between them. The first draft had 5 minutes against a
+ * 2-minute TTL — three silent minutes out of every five.
+ */
+export const HOST_LOAD_HEARTBEAT_MS = 60_000;
+/**
+ * How much load1 must move before an otherwise unchanged sample earns a frame.
+ *
+ * Same principle as `publishSlots`: a tick that would repeat what the server
+ * already knows is not sent at all. 0.5 is below the resolution at which a
+ * person reads the number and well above the noise of an idle machine.
+ */
+export const HOST_LOAD_MIN_DELTA_LOAD1 = 0.5;
+/** The same idea for memory, as a fraction — see `hostLoadChangedEnough`. */
+export const HOST_LOAD_MIN_DELTA_MEM_RATIO = 0.05;
+const PROC_DIR = '/proc';
+/** kB in `/proc/meminfo` means kibibytes, and has since the field was added. */
+const MEMINFO_UNIT_BYTES = 1024;
+/**
+ * `MemTotal:       16307180 kB` → `['MemTotal', 16307180 * 1024]`.
+ *
+ * The `kB` suffix is required rather than assumed. A handful of `/proc/meminfo`
+ * rows carry no unit at all (`HugePages_Total`), and multiplying one of those
+ * by 1024 because it happened to be named like the row we wanted would produce
+ * a number that is wrong by three orders of magnitude and looks perfectly
+ * plausible on a card.
+ */
+const MEMINFO_LINE = /^([A-Za-z0-9_()]+):\s+(\d+)\s+kB$/;
+function parseMeminfo(text) {
+    const values = new Map();
+    for (const line of text.split('\n')) {
+        const match = MEMINFO_LINE.exec(line.trim());
+        if (!match)
+            continue;
+        const [, key, amount] = match;
+        if (!key || amount === undefined)
+            continue;
+        const parsed = Number(amount);
+        if (!Number.isFinite(parsed))
+            continue;
+        values.set(key, parsed * MEMINFO_UNIT_BYTES);
+    }
+    return values;
+}
+/** `0.42 0.53 0.60 2/1234 56789` → the three windows, or `null` if it is not that. */
+function parseLoadavg(text) {
+    const parts = text.trim().split(/\s+/);
+    const windows = parts.slice(0, 3).map(Number);
+    if (windows.length < 3)
+        return null;
+    for (const value of windows) {
+        if (!Number.isFinite(value) || value < 0)
+            return null;
+    }
+    const [load1, load5, load15] = windows;
+    return { load1, load5, load15 };
+}
+/**
+ * Measure this machine, or say honestly that we cannot.
+ *
+ * `null` is a first-class answer and every caller must treat it as «send
+ * nothing». There is deliberately no `process.platform` check in front of it:
+ * the absence of the files IS the check, and it is the wider one — it also
+ * covers a Linux container with `/proc` masked or mounted `hidepid`, which a
+ * platform test would sail straight past into an exception. The runner is
+ * Linux-only by its installer, but «only runs on Linux» must never mean
+ * «crashes anywhere else»: this is called from a timer, and an exception here
+ * would take the whole session supervisor with it.
+ */
+export function readHostLoad(sources = {}) {
+    const procDir = sources.procDir ?? PROC_DIR;
+    try {
+        const load = parseLoadavg(fs.readFileSync(path.join(procDir, 'loadavg'), 'utf8'));
+        if (!load)
+            return null;
+        const meminfo = parseMeminfo(fs.readFileSync(path.join(procDir, 'meminfo'), 'utf8'));
+        const memAvailableBytes = meminfo.get('MemAvailable');
+        // No `MemAvailable` means a kernel older than 3.14 (2014). Reporting
+        // `MemFree` in its place would be worse than reporting nothing: on a
+        // healthy machine it is near zero by design, so every such card would
+        // permanently read «out of memory».
+        if (memAvailableBytes === undefined)
+            return null;
+        // Swap is reported only when BOTH halves are there. A kernel built without
+        // swap support has neither, and 0/0 is the truthful answer for it — but
+        // one half without the other is a shape we do not understand, and guessing
+        // `free = 0` for a real swap area would paint that machine as permanently
+        // paging, which is the one verdict this frame exists to make trustworthy.
+        const swapTotalRaw = meminfo.get('SwapTotal');
+        const swapFreeRaw = meminfo.get('SwapFree');
+        const swapKnown = swapTotalRaw !== undefined && swapFreeRaw !== undefined;
+        const swapTotalBytes = swapKnown ? swapTotalRaw : 0;
+        const swapFreeBytes = swapKnown ? swapFreeRaw : 0;
+        const cpuCount = sources.cpuCount ?? os.cpus().length;
+        // A frame the API's schema would reject is worse than no frame, and
+        // `os.cpus()` has been seen returning an empty array in containers. Nor may
+        // it be quietly replaced by 1: load1 is read as a ratio of this number, so
+        // a made-up core count would paint a working eight-core machine red.
+        if (!Number.isInteger(cpuCount) || cpuCount < 1)
+            return null;
+        const at = (sources.now?.() ?? new Date()).toISOString();
+        return {
+            ...load,
+            cpuCount,
+            memAvailableBytes,
+            swapTotalBytes,
+            swapFreeBytes,
+            at,
+        };
+    }
+    catch {
+        // ENOENT on a Mac, EACCES in a locked-down container, EIO on a machine
+        // that is already having a very bad day. All of them mean the same thing
+        // to the caller, and none of them is worth a log line every 30 seconds.
+        return null;
+    }
+}
+/**
+ * Is the heartbeat due, given how long ago the last frame actually went out?
+ *
+ * The second half of the answer is the whole reason this is a function: a
+ * backwards clock step makes «how long ago» NEGATIVE, and a machine whose load
+ * never moves would then say nothing for the entire offset — an hour of silence
+ * on a machine that may be on fire. A clock correction is due, not early.
+ *
+ * The API makes the same allowance for the same step, and has to: it drops
+ * frames older than the one it holds unless the step is larger than a
+ * measurement's lifetime (`HOST_LOAD_TTL_MS`, `runner-gateway.ts`). Half of this
+ * fix on one side of the socket is no fix at all.
+ */
+export function hostLoadHeartbeatDue(sinceLastSentMs, heartbeatMs) {
+    return sinceLastSentMs >= heartbeatMs || sinceLastSentMs < 0;
+}
+/**
+ * Is this sample worth a frame at all? The «a quiet runner says nothing» rule.
+ *
+ * Same shape as `publishSlots`: what the server already knows is not repeated.
+ * The alternative is 2 880 identical frames a day per machine, each one waking
+ * the gateway, a Redis write and every open dashboard socket.
+ *
+ * The memory threshold is 5 % of the machine's TOTAL memory, not 5 % of what
+ * is currently available. Two reasons, and both were the deciding one:
+ *
+ *  - a fraction of `memAvailable` shrinks as the machine fills, so the frames
+ *    would get chattiest exactly when the machine is least able to afford it —
+ *    5 % of the last 200 MB is a 10 MB trigger;
+ *  - `memTotal` is fixed per machine, so «the card moves when a GB moves» reads
+ *    the same on every server instead of meaning something different on each.
+ *
+ * Swap counts too, though the plan names only load and memory. It is one of the
+ * three verdicts behind «overloaded», and it is the only one with no other
+ * trigger: a machine that starts paging with its load and its `MemAvailable`
+ * both flat would otherwise wait up to five minutes for the heartbeat to say
+ * so, and paging is the state whose wall-clock cost is unbounded.
+ */
+export function hostLoadChangedEnough(previous, next, memTotalBytes = os.totalmem()) {
+    // Nothing said yet — the first measurement after a (re)connect is always news.
+    if (!previous)
+        return true;
+    if (Math.abs(next.load1 - previous.load1) >= HOST_LOAD_MIN_DELTA_LOAD1)
+        return true;
+    // A machine that cannot say how much memory it has still gets a working
+    // threshold: the sample's own availability is a poor denominator but a
+    // finite one, and the alternative is dividing by zero forever.
+    const memBase = memTotalBytes > 0 ? memTotalBytes : next.memAvailableBytes;
+    const memDelta = Math.abs(next.memAvailableBytes - previous.memAvailableBytes);
+    if (memBase > 0 && memDelta >= memBase * HOST_LOAD_MIN_DELTA_MEM_RATIO)
+        return true;
+    // Swap size itself can change (`swapon`), and that is news by the same rule.
+    if (next.swapTotalBytes !== previous.swapTotalBytes)
+        return true;
+    if (next.swapTotalBytes > 0) {
+        const swapDelta = Math.abs(next.swapFreeBytes - previous.swapFreeBytes);
+        if (swapDelta >= next.swapTotalBytes * HOST_LOAD_MIN_DELTA_MEM_RATIO)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=host-load.js.map