harnery 0.38.0 → 0.40.0

package/dist/core/resources/status.js

@@ -0,0 +1,536 @@
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { unknownPressureAssessment } from "../diagnostics/advice.js";
+import { PRESSURE_ASSESSMENT_SCHEMA_VERSION, PRESSURE_POLICY, } from "../diagnostics/contract.js";
+import { SUPERVISOR_PRESSURE_SCHEMA_VERSION, } from "../supervisor/contract.js";
+import { readSupervisorStatus } from "../supervisor/status.js";
+import { supervisorPaths } from "../supervisor/storage.js";
+import { RESOURCE_SNAPSHOT_SCHEMA_VERSION, } from "./contract.js";
+import { resourcePaths } from "./storage.js";
+export const RESOURCE_STATUS_STALE_MS = 15_000;
+export const RESOURCE_STATUS_MAX_BYTES = 4 * 1024 * 1024;
+export const RESOURCE_STATUS_PROCESS_LIMIT = 20;
+export const RESOURCE_HOST_STATUS_STALE_MS = 30_000;
+const FUTURE_TOLERANCE_MS = 1_000;
+/** A bounded cache-only read. Never samples the OS or starts the writer. */
+export function readResourceStatus(coordRoot, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const writerState = readWriterState(coordRoot, nowMs);
+    const published = readPublishedPressure(coordRoot, nowMs, writerState);
+    const result = {
+        schema_version: 2,
+        state: "unavailable",
+        reason: "snapshot_missing",
+        sampled_at: null,
+        sample_age_ms: null,
+        stale_after_ms: RESOURCE_STATUS_STALE_MS,
+        platform: null,
+        namespace: "unknown",
+        support: null,
+        writer: writerState,
+        assessment: published.assessment,
+        prior_hysteresis: published.prior_hysteresis,
+        assessment_capability: published.capability,
+        machine: null,
+        disks: [],
+        pressure: null,
+        oom: null,
+        io: null,
+        host: null,
+    };
+    let value;
+    try {
+        value = readBoundedJson(resourcePaths(coordRoot).snapshot);
+    }
+    catch (error) {
+        result.reason =
+            error.code === "ENOENT"
+                ? "snapshot_missing"
+                : error instanceof Error && error.message === "snapshot_too_large"
+                    ? "snapshot_too_large"
+                    : "snapshot_invalid";
+        return result;
+    }
+    if (!validSnapshot(value))
+        return { ...result, reason: "snapshot_invalid" };
+    const sampleMs = Date.parse(value.sampled_at);
+    if (!Number.isFinite(sampleMs) || sampleMs - nowMs > FUTURE_TOLERANCE_MS) {
+        return { ...result, reason: "snapshot_clock_invalid" };
+    }
+    result.sampled_at = value.sampled_at;
+    result.sample_age_ms = Math.max(0, nowMs - sampleMs);
+    result.platform = value.platform;
+    result.namespace = value.namespace;
+    result.support = {
+        state: value.support.state,
+        sampler: value.support.sampler,
+        ...reason(value.support.reason),
+    };
+    if (result.sample_age_ms > RESOURCE_STATUS_STALE_MS) {
+        return { ...result, state: "stale", reason: "snapshot_stale" };
+    }
+    if (value.support.state === "error" || value.support.state === "unsupported") {
+        return { ...result, reason: `sampler_${value.support.state}` };
+    }
+    result.state = "fresh";
+    result.reason = null;
+    result.machine = projectMachine(value.machine);
+    result.disks = (value.disks ?? []).map(projectDisk);
+    result.pressure = value.pressure
+        ? {
+            state: value.pressure.state,
+            ...reason(value.pressure.reason),
+            cpu: projectWindow(value.pressure.cpu),
+            memory: projectWindow(value.pressure.memory),
+            io: projectWindow(value.pressure.io),
+            memory_full: projectWindow(value.pressure.memory_full),
+            io_full: projectWindow(value.pressure.io_full),
+        }
+        : null;
+    result.oom = value.oom
+        ? {
+            state: value.oom.state,
+            total_kills: value.oom.total_kills,
+            kills_since_last_sample: value.oom.kills_since_last_sample,
+            last_kill_age_ms: value.oom.last_kill_age_ms,
+            ...reason(value.oom.reason),
+        }
+        : null;
+    result.io = value.io
+        ? {
+            state: value.io.state,
+            read_bytes_per_second: value.io.read_bytes_per_second,
+            write_bytes_per_second: value.io.write_bytes_per_second,
+            ...reason(value.io.reason),
+        }
+        : null;
+    if (value.host) {
+        const hostAge = nowMs - Date.parse(value.host.sampled_at);
+        result.host =
+            hostAge > RESOURCE_HOST_STATUS_STALE_MS || hostAge < -FUTURE_TOLERANCE_MS
+                ? {
+                    platform: "win32",
+                    sampled_at: value.host.sampled_at,
+                    state: "error",
+                    machine: null,
+                    disks: [],
+                    reason: "host_snapshot_stale",
+                }
+                : {
+                    platform: "win32",
+                    sampled_at: value.host.sampled_at,
+                    state: value.host.state,
+                    machine: value.host.machine ? projectMachine(value.host.machine) : null,
+                    disks: value.host.disks.map(projectDisk),
+                    ...reason(value.host.reason),
+                };
+    }
+    if (options.includeProcesses) {
+        result.processes = [...value.processes]
+            .sort((a, b) => b.rss_bytes - a.rss_bytes)
+            .slice(0, RESOURCE_STATUS_PROCESS_LIMIT)
+            .map((p) => ({
+            pid: p.pid,
+            name: text(p.name),
+            cpu_percent: p.cpu_percent,
+            rss_bytes: p.rss_bytes,
+            owner_kind: p.owner_kind,
+            owner_id: p.owner_id === null ? null : text(p.owner_id),
+        }));
+        result.processes_omitted =
+            value.omitted_process_count + value.processes.length - result.processes.length;
+    }
+    return result;
+}
+export function formatResourceSummary(status) {
+    const lead = status.assessment.summary;
+    if (status.state !== "fresh" || !status.machine) {
+        const age = status.sample_age_ms === null ? "" : ` (${Math.round(status.sample_age_ms / 1_000)}s old)`;
+        return `${lead} Measurements are ${status.state}${age}: ${status.reason?.replaceAll("_", " ") ?? "no measurements"}.`;
+    }
+    const m = status.machine;
+    const disk = status.disks
+        .filter((d) => d.available_bytes !== null)
+        .reduce((least, d) => !least || (d.available_bytes ?? Infinity) < (least.available_bytes ?? Infinity) ? d : least, null);
+    const cpu = m.cpu_percent === null ? "warming up" : `${Math.round(m.cpu_percent)}%`;
+    const ram = m.memory_available_bytes === null
+        ? "unknown"
+        : `${formatBytes(m.memory_available_bytes)} available`;
+    const diskText = disk ? `${formatBytes(disk.available_bytes)} available` : "unknown";
+    return `${lead} ${status.namespace}/${status.platform}: CPU ${cpu}, RAM ${ram}, disk ${diskText}; ${Math.round((status.sample_age_ms ?? 0) / 1_000)}s old${status.support?.state === "partial" ? "; partial" : ""}${!status.writer.running ? "; writer stopped" : ""}.`;
+}
+export function formatResourceStatus(status, bin) {
+    const a = status.assessment;
+    const lines = [formatResourceSummary(status)];
+    lines.push(`Assessment: ${a.state} at ${a.scope} scope; limiting resource ${a.limiting_resource}; trend ${a.trend}; evidence ${a.evidence_state}; recommended action ${a.recommended_action}.`);
+    lines.push(`Evidence age: ${a.sample_age_ms === null ? "unknown" : `${Math.round(a.sample_age_ms / 1_000)}s`}; assessment source ${status.assessment_capability.state}${status.assessment_capability.reason_code ? ` (${status.assessment_capability.reason_code})` : ""}.`);
+    for (const item of a.reasons)
+        lines.push(`Reason ${item.code}: ${item.summary}`);
+    for (const item of a.guidance)
+        lines.push(`Guidance for ${item.workload_class} work: ${item.summary}`);
+    if (a.contributors.length) {
+        lines.push("Contributors (who is using the resource, never the machine state):");
+        for (const item of a.contributors)
+            lines.push(`  ${formatContributor(item)}`);
+        if (a.omitted_contributor_count)
+            lines.push(`  ${a.omitted_contributor_count} other contributors omitted.`);
+    }
+    if (a.unattributed_memory_percent !== null)
+        lines.push(`Unattributed memory: ${Math.round(a.unattributed_memory_percent)}% of machine memory has no validated owner.`);
+    if (status.state !== "fresh" || !status.writer.running)
+        lines.push(`Start or inspect the writer with ${bin} supervisor start --keep-alive and ${bin} supervisor status.`);
+    if (status.host)
+        lines.push(`Windows host: ${status.host.state}${status.host.machine ? `; CPU ${status.host.machine.cpu_percent === null ? "warming up" : `${Math.round(status.host.machine.cpu_percent)}%`}, RAM ${status.host.machine.memory_available_bytes === null ? "unknown" : `${formatBytes(status.host.machine.memory_available_bytes)} available`}` : `; ${status.host.reason ?? "unavailable"}`}`);
+    for (const disk of status.disks)
+        lines.push(`Disk ${disk.path}: ${disk.available_bytes === null ? (disk.reason ?? disk.state) : `${formatBytes(disk.available_bytes)} available (${disk.used_percent === null ? "unknown" : `${Math.round(disk.used_percent)}%`} used)`}`);
+    if (status.pressure)
+        lines.push(`Pressure: ${status.pressure.state}${status.pressure.reason ? ` (${status.pressure.reason})` : ""}`);
+    for (const [name, window] of [
+        ["memory", status.pressure?.memory_full],
+        ["I/O", status.pressure?.io_full],
+    ]) {
+        if (!window)
+            continue;
+        const direction = window.avg10 > window.avg60 ? "rising" : window.avg10 < window.avg60 ? "falling" : "steady";
+        lines.push(`Full ${name} stalls: ${window.avg10}% / ${window.avg60}% / ${window.avg300}% (10s / 60s / 300s; ${direction}).`);
+    }
+    if (status.oom) {
+        const oom = status.oom;
+        lines.push(`OOM kills: ${oom.total_kills ?? "unknown"} total; ${oom.kills_since_last_sample ?? "unknown"} since previous sample${oom.last_kill_age_ms === null ? "" : `; last increase ${Math.round(oom.last_kill_age_ms / 1000)}s ago`}${oom.reason ? ` (${oom.reason})` : ""}.`);
+    }
+    if (status.io)
+        lines.push(`Disk I/O: ${status.io.state}; read ${status.io.read_bytes_per_second === null ? "unknown" : `${formatBytes(status.io.read_bytes_per_second)}/s`}, write ${status.io.write_bytes_per_second === null ? "unknown" : `${formatBytes(status.io.write_bytes_per_second)}/s`}`);
+    if (status.processes) {
+        lines.push("Processes (largest memory first):");
+        for (const p of status.processes)
+            lines.push(`  ${p.pid} ${p.name}: ${formatBytes(p.rss_bytes)}, CPU ${p.cpu_percent === null ? "unknown" : `${Math.round(p.cpu_percent)}%`}, ${p.owner_kind}${p.owner_id ? ` ${p.owner_id}` : ""}`);
+        if (status.processes_omitted)
+            lines.push(`  ${status.processes_omitted} other processes omitted.`);
+    }
+    return lines.join("\n");
+}
+/** Ownership is stated only when attribution is exact. */
+function formatContributor(item) {
+    const owner = item.attribution_confidence === "exact" && item.owner_id
+        ? `${item.owner_kind ?? "owner"} ${item.owner_id}`
+        : item.attribution_state === "unattributed"
+            ? "no validated owner"
+            : "owner not confirmed";
+    return `${item.finding_kind} ${item.scope_kind}:${item.scope_id} (${owner}): ${item.summary}`;
+}
+export const PRESSURE_RECORD_MAX_BYTES = 256 * 1024;
+/**
+ * Read the assessment the observer published. Bounded, cache only, and never a
+ * computation: a missing, stale, or malformed record yields `unknown` with the
+ * reason stated, because a gap in the evidence is not a measurement of health.
+ */
+export function readPublishedPressure(coordRoot, nowMs = Date.now(), writer) {
+    const sourceKind = "supervisor.pressure";
+    const observedAt = new Date(nowMs).toISOString();
+    const gap = (state, reasonCode, summary, stale = false) => ({
+        assessment: unknownPressureAssessment({
+            observedAt,
+            reasonCode: stale ? "snapshot_stale" : "evidence_unavailable",
+            summary,
+        }),
+        prior_hysteresis: null,
+        capability: { source_kind: sourceKind, state, reason_code: reasonCode },
+        record: null,
+    });
+    // A record can only be trusted while its writer is alive. Every surface makes
+    // the same check here so none of them reports a state the others do not.
+    if (!(writer ?? readWriterState(coordRoot, nowMs)).running) {
+        return gap("expired", "pressure_observer_not_running", "Local resource pressure cannot be determined because the resource observer is not running.");
+    }
+    const path = supervisorPaths(coordRoot).pressure;
+    let record;
+    try {
+        const age = nowMs - statSync(path).mtimeMs;
+        if (age > PRESSURE_POLICY.sample_staleness_ms || age < -FUTURE_TOLERANCE_MS) {
+            return gap("expired", "pressure_record_stale", `Local resource pressure cannot be determined because the published assessment is ${Math.round(Math.abs(age) / 1_000)} seconds old.`, true);
+        }
+        record = readBoundedJson(path, PRESSURE_RECORD_MAX_BYTES);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return gap("unsupported", "pressure_record_missing", "Local resource pressure cannot be determined because the observer has not published an assessment yet.");
+        }
+        if (error instanceof Error && error.message === "snapshot_too_large") {
+            return gap("error", "pressure_record_too_large", "Local resource pressure cannot be determined because the published assessment is larger than the read limit.");
+        }
+        return gap("malformed", "pressure_record_malformed", "Local resource pressure cannot be determined because the published assessment could not be parsed.");
+    }
+    if (!validPressureRecord(record)) {
+        return gap("malformed", "pressure_record_malformed", "Local resource pressure cannot be determined because the published assessment did not match the expected shape.");
+    }
+    return {
+        assessment: record.assessment,
+        prior_hysteresis: record.prior_hysteresis,
+        capability: { source_kind: sourceKind, state: "supported" },
+        record,
+    };
+}
+/** Whether the observer that writes both the snapshot and the record is alive. */
+function readWriterState(coordRoot, nowMs) {
+    try {
+        // Keep malformed service metadata from making the read expensive. The shared
+        // status reader retains ownership of PID/start-token liveness checks.
+        if (statSync(supervisorPaths(coordRoot).service).size > 65_536) {
+            return { running: false, stale: false };
+        }
+        const writer = readSupervisorStatus(coordRoot, nowMs);
+        const futureHeartbeat = writer.record && Date.parse(writer.record.heartbeat_at) > nowMs + FUTURE_TOLERANCE_MS;
+        return {
+            running: writer.running && !futureHeartbeat,
+            stale: writer.stale || !!futureHeartbeat,
+        };
+    }
+    catch {
+        // A missing writer must not break normal coordination.
+        return { running: false, stale: false };
+    }
+}
+function validPressureRecord(v) {
+    if (!object(v) ||
+        v.schema_version !== SUPERVISOR_PRESSURE_SCHEMA_VERSION ||
+        !string(v.published_at) ||
+        !string(v.observer_generation) ||
+        !validAssessment(v.assessment) ||
+        !(v.prior_hysteresis === null || validHysteresis(v.prior_hysteresis)))
+        return false;
+    return true;
+}
+function validAssessment(v) {
+    if (!object(v) ||
+        v.schema_version !== PRESSURE_ASSESSMENT_SCHEMA_VERSION ||
+        v.observer_only !== true ||
+        !["normal", "elevated", "critical", "unknown"].includes(v.state) ||
+        !["guest", "native", "windows-host"].includes(v.scope) ||
+        !["memory", "cpu", "io", "storage", "none", "unknown"].includes(v.limiting_resource) ||
+        !["rising", "steady", "falling", "unknown"].includes(v.trend) ||
+        !string(v.observed_at) ||
+        !nullable(v.sample_age_ms) ||
+        !["complete", "partial", "unavailable"].includes(v.evidence_state) ||
+        !boundedArray(v.evidence, PRESSURE_POLICY.limits.max_evidence) ||
+        !boundedArray(v.reasons, PRESSURE_POLICY.limits.max_reasons) ||
+        !boundedArray(v.contributors, PRESSURE_POLICY.limits.max_contributors) ||
+        !number(v.omitted_contributor_count) ||
+        !percent(v.unattributed_memory_percent) ||
+        !["proceed", "limit-heavy-work", "avoid-new-heavy-work", "unknown"].includes(v.recommended_action) ||
+        !string(v.summary) ||
+        !boundedArray(v.guidance, 8) ||
+        !validHysteresis(v.hysteresis) ||
+        !number(v.policy_version))
+        return false;
+    return (v.reasons.every((row) => object(row) && string(row.code) && string(row.summary)) &&
+        v.guidance.every((row) => object(row) && string(row.workload_class) && string(row.summary)) &&
+        v.contributors.every((row) => object(row) &&
+            string(row.finding_id) &&
+            string(row.finding_kind) &&
+            string(row.summary) &&
+            ["exact", "none"].includes(row.attribution_confidence)));
+}
+function validHysteresis(v) {
+    return (object(v) &&
+        ["normal", "elevated", "critical", "unknown"].includes(v.state) &&
+        string(v.state_since) &&
+        number(v.consecutive_clear_samples) &&
+        object(v.dimension_streaks) &&
+        (v.oom_baseline_total_kills === null || number(v.oom_baseline_total_kills)) &&
+        (v.oom_hold_until === null || string(v.oom_hold_until)) &&
+        (v.observer_generation === null || string(v.observer_generation)));
+}
+function boundedArray(v, max) {
+    return Array.isArray(v) && v.length <= max;
+}
+function readBoundedJson(path, maxBytes = RESOURCE_STATUS_MAX_BYTES) {
+    const fd = openSync(path, "r");
+    try {
+        const size = fstatSync(fd).size;
+        if (size > maxBytes)
+            throw new Error("snapshot_too_large");
+        const buffer = Buffer.alloc(Math.min(maxBytes + 1, size + 1));
+        const length = readSync(fd, buffer, 0, buffer.length, 0);
+        if (length > maxBytes)
+            throw new Error("snapshot_too_large");
+        return JSON.parse(buffer.subarray(0, length).toString("utf8"));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function object(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function number(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0;
+}
+function nullable(v) {
+    return v === null || number(v);
+}
+function percent(v) {
+    return v === null || (number(v) && v <= 100);
+}
+function support(v) {
+    return ["supported", "partial", "unsupported", "error"].includes(v);
+}
+function string(v) {
+    return typeof v === "string" && v.length <= 4096;
+}
+function validMachine(v) {
+    return (object(v) &&
+        percent(v.cpu_percent) &&
+        number(v.cpu_logical_count) &&
+        (v.cpu_available_parallelism === undefined || number(v.cpu_available_parallelism)) &&
+        (v.load_average === null ||
+            (Array.isArray(v.load_average) &&
+                v.load_average.length === 3 &&
+                v.load_average.every(number))) &&
+        [
+            "memory_total_bytes",
+            "memory_available_bytes",
+            "memory_used_bytes",
+            "swap_total_bytes",
+            "swap_used_bytes",
+        ].every((k) => nullable(v[k])) &&
+        percent(v.memory_percent) &&
+        nullable(v.process_count) &&
+        !(number(v.memory_total_bytes) &&
+            number(v.memory_available_bytes) &&
+            v.memory_available_bytes > v.memory_total_bytes));
+}
+function validDisk(v) {
+    return (object(v) &&
+        string(v.path) &&
+        support(v.state) &&
+        nullable(v.total_bytes) &&
+        nullable(v.available_bytes) &&
+        percent(v.used_percent) &&
+        (v.reason === undefined || string(v.reason)) &&
+        !(number(v.total_bytes) && number(v.available_bytes) && v.available_bytes > v.total_bytes));
+}
+function validWindow(v) {
+    return (v === null ||
+        (object(v) && ["avg10", "avg60", "avg300"].every((k) => number(v[k]) && v[k] <= 100)));
+}
+function validSnapshot(v) {
+    if (!object(v) ||
+        v.schema_version !== RESOURCE_SNAPSHOT_SCHEMA_VERSION ||
+        !string(v.sampled_at) ||
+        ![
+            "aix",
+            "android",
+            "darwin",
+            "freebsd",
+            "haiku",
+            "linux",
+            "openbsd",
+            "sunos",
+            "win32",
+            "cygwin",
+            "netbsd",
+        ].includes(v.platform) ||
+        !["host", "wsl", "unknown"].includes(v.namespace) ||
+        !object(v.support) ||
+        !support(v.support.state) ||
+        !["procfs", "darwin", "win32", "unsupported"].includes(v.support.sampler) ||
+        (v.support.reason !== undefined && !string(v.support.reason)) ||
+        !validMachine(v.machine) ||
+        !nullable(v.interval_ms) ||
+        !number(v.sample_duration_ms) ||
+        !number(v.collector_cpu_ms) ||
+        !number(v.omitted_process_count) ||
+        !Array.isArray(v.processes) ||
+        v.processes.length > 10000)
+        return false;
+    if (v.disks !== undefined &&
+        (!Array.isArray(v.disks) || v.disks.length > 64 || !v.disks.every(validDisk)))
+        return false;
+    if (v.pressure !== undefined &&
+        (!object(v.pressure) ||
+            !support(v.pressure.state) ||
+            !validWindow(v.pressure.cpu) ||
+            !validWindow(v.pressure.memory) ||
+            !validWindow(v.pressure.io) ||
+            !validWindow(v.pressure.memory_full) ||
+            !validWindow(v.pressure.io_full) ||
+            (v.pressure.reason !== undefined && !string(v.pressure.reason))))
+        return false;
+    if (v.oom !== undefined &&
+        (!object(v.oom) ||
+            !support(v.oom.state) ||
+            !["total_kills", "kills_since_last_sample"].every((key) => v.oom !== null &&
+                object(v.oom) &&
+                (v.oom[key] === null || (number(v.oom[key]) && Number.isSafeInteger(v.oom[key])))) ||
+            !nullable(v.oom.last_kill_age_ms) ||
+            (v.oom.reason !== undefined && !string(v.oom.reason))))
+        return false;
+    if (v.io !== undefined &&
+        (!object(v.io) ||
+            !support(v.io.state) ||
+            !nullable(v.io.read_bytes_per_second) ||
+            !nullable(v.io.write_bytes_per_second) ||
+            (v.io.reason !== undefined && !string(v.io.reason))))
+        return false;
+    if (v.host !== undefined &&
+        (!object(v.host) ||
+            v.host.platform !== "win32" ||
+            !support(v.host.state) ||
+            !string(v.host.sampled_at) ||
+            !Number.isFinite(Date.parse(v.host.sampled_at)) ||
+            (v.host.machine !== null && !validMachine(v.host.machine)) ||
+            !Array.isArray(v.host.disks) ||
+            v.host.disks.length > 64 ||
+            !v.host.disks.every(validDisk) ||
+            (v.host.reason !== undefined && !string(v.host.reason))))
+        return false;
+    return v.processes.every((p) => object(p) &&
+        Number.isSafeInteger(p.pid) &&
+        number(p.pid) &&
+        string(p.name) &&
+        nullable(p.cpu_percent) &&
+        number(p.rss_bytes) &&
+        ["agent", "service", "unattributed"].includes(p.owner_kind) &&
+        (p.owner_id === null || string(p.owner_id)));
+}
+function projectMachine(m) {
+    return {
+        cpu_percent: m.cpu_percent,
+        cpu_logical_count: m.cpu_logical_count,
+        ...(m.cpu_available_parallelism === undefined
+            ? {}
+            : { cpu_available_parallelism: m.cpu_available_parallelism }),
+        load_average: m.load_average,
+        memory_total_bytes: m.memory_total_bytes,
+        memory_available_bytes: m.memory_available_bytes,
+        memory_used_bytes: m.memory_used_bytes,
+        memory_percent: m.memory_percent,
+        swap_total_bytes: m.swap_total_bytes,
+        swap_used_bytes: m.swap_used_bytes,
+        process_count: m.process_count,
+    };
+}
+function projectDisk(d) {
+    return {
+        path: text(d.path),
+        state: d.state,
+        total_bytes: d.total_bytes,
+        available_bytes: d.available_bytes,
+        used_percent: d.used_percent,
+        ...reason(d.reason),
+    };
+}
+function projectWindow(v) {
+    return v ? { avg10: v.avg10, avg60: v.avg60, avg300: v.avg300 } : null;
+}
+function text(s) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Cache strings must not inject terminal control sequences.
+    return s.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 240);
+}
+function reason(s) {
+    return s === undefined ? {} : { reason: text(s) };
+}
+function formatBytes(bytes) {
+    return bytes >= 1024 ** 3
+        ? `${(bytes / 1024 ** 3).toFixed(1)} GiB`
+        : `${Math.round(bytes / 1024 ** 2)} MiB`;
+}

package/dist/core/resources/system.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceDiskSample, ResourceIoSample, ResourceOomSample, ResourcePressureSample, ResourceVmstatSample } from "./contract.js";
+interface FileSystemCapacity {
+    bsize: number | bigint;
+    blocks: number | bigint;
+    bavail: number | bigint;
+    bfree: number | bigint;
+}
+export interface SystemResourceOptions {
+    platform?: NodeJS.Platform;
+    procRoot?: string;
+    sysRoot?: string;
+    nowMs?: number;
+    namespace?: string;
+    tmpPath?: string;
+    statfs?: (path: string) => FileSystemCapacity;
+    filesystemId?: (path: string) => string | number | bigint;
+}
+/** Collect only the workspace and temporary volume; never walk their contents. */
+export declare function collectSystemResources(coordRoot: string, options?: SystemResourceOptions): {
+    disks: ResourceDiskSample[];
+    pressure: ResourcePressureSample;
+    io: ResourceIoSample;
+    oom: ResourceOomSample;
+    vmstat: ResourceVmstatSample;
+};
+export {};
+//# sourceMappingURL=system.d.ts.map

package/dist/core/resources/system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../../src/core/resources/system.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EAGtB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAEvB,UAAU,kBAAkB;IAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAC9C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CAC3D;AAwCD,kFAAkF;AAClF,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,qBAA0B,GAClC;IACD,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,EAAE,EAAE,gBAAgB,CAAC;IACrB,GAAG,EAAE,iBAAiB,CAAC;IACvB,MAAM,EAAE,oBAAoB,CAAC;CAC9B,CA6CA"}