@cleocode/core 2026.6.13 → 2026.6.15

package/dist/resources/linux-backend.js

@@ -0,0 +1,259 @@
+/**
+ * Linux ResourceMonitor backend.
+ *
+ * Reads:
+ *   - `/proc/pressure/memory` — global PSI (some + full)
+ *   - `<cgroupSlicePath>/memory.pressure` — cleo.slice scoped PSI
+ *   - `/proc/meminfo` — MemAvailable
+ *   - `<walPath>` size stat — WAL growth signal (DHQ-050 starvation class)
+ *   - `/proc/<pid>/smaps_rollup` — per-child RSS (SEPARATE low-frequency path)
+ *
+ * ## Read-count discipline (Amendment 1)
+ *
+ * `sample()` calls the injected reader at most:
+ *   - 1× for `/proc/pressure/memory`
+ *   - 1× for the slice `memory.pressure` (if configured)
+ *   - 1× for `/proc/meminfo`
+ *   - N× stat calls for N configured WAL paths
+ *
+ * smaps_rollup reads are on a SEPARATE `sweepChildRss()` method and are
+ * structurally impossible to reach from the `sample()` hot path.
+ *
+ * ## oomd threshold facts (Amendment 4)
+ *
+ * systemd-oomd on Fedora defaults to 80%/20s on user@1000.service.
+ * Our hold/backoff thresholds (some avg10 >10% / full avg10 >5%) sit far
+ * below that line, ensuring cleo always throttles before oomd kills.
+ *
+ * @module resources/linux-backend
+ * @task T11994
+ * @epic T11992
+ */
+import { readFile, stat } from 'node:fs/promises';
+// ---------------------------------------------------------------------------
+// Parsing helpers (tested in isolation)
+// ---------------------------------------------------------------------------
+/**
+ * Parse a single PSI line.
+ *
+ * Format: `some avg10=0.42 avg60=0.31 avg300=0.20 total=1234567`
+ *
+ * Returns `null` when the line does not match the expected format.
+ */
+export function parsePressureLine(line) {
+    const avg10Match = /avg10=([\d.]+)/.exec(line);
+    const avg60Match = /avg60=([\d.]+)/.exec(line);
+    const avg300Match = /avg300=([\d.]+)/.exec(line);
+    const totalMatch = /total=(\d+)/.exec(line);
+    if (!avg10Match?.[1] || !avg60Match?.[1] || !avg300Match?.[1] || !totalMatch?.[1]) {
+        return null;
+    }
+    return {
+        avg10: parseFloat(avg10Match[1]),
+        avg60: parseFloat(avg60Match[1]),
+        avg300: parseFloat(avg300Match[1]),
+        totalUs: parseInt(totalMatch[1], 10),
+    };
+}
+/**
+ * Parse a PSI file (two lines: `some ...` and `full ...`).
+ *
+ * Returns `null` when the content is unreadable / unparseable — callers
+ * treat this as "pressure interface absent" (degraded mode).
+ */
+export function parsePsiFile(content) {
+    const lines = content
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+    let some = null;
+    let full = null;
+    for (const line of lines) {
+        if (line.startsWith('some ')) {
+            some = parsePressureLine(line);
+        }
+        else if (line.startsWith('full ')) {
+            full = parsePressureLine(line);
+        }
+    }
+    if (!some) {
+        return null;
+    }
+    return { some, full };
+}
+/**
+ * Parse `MemAvailable` from `/proc/meminfo`.
+ *
+ * Format: `MemAvailable:   42233788 kB`
+ *
+ * Returns `null` when the field is absent (non-Linux / old kernel).
+ * Reuses the same parsing pattern as `packages/core/src/llm/local-model-fit.ts:269`.
+ */
+export function parseMemAvailable(content) {
+    for (const line of content.split('\n')) {
+        if (line.startsWith('MemAvailable:')) {
+            // Format: "MemAvailable:   42233788 kB"
+            const match = /MemAvailable:\s+(\d+)\s+kB/.exec(line);
+            if (match?.[1]) {
+                return parseInt(match[1], 10) * 1024;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse a `/proc/<pid>/smaps_rollup` file for RSS and PSS.
+ *
+ * Relevant fields:
+ *   `Rss:       12345 kB`
+ *   `Pss:        9876 kB`
+ *
+ * Returns `null` when either field is absent.
+ */
+export function parseSmapsRollup(content) {
+    let rssKb = null;
+    let pssKb = null;
+    for (const line of content.split('\n')) {
+        if (line.startsWith('Rss:')) {
+            const m = /Rss:\s+(\d+)\s+kB/.exec(line);
+            if (m?.[1])
+                rssKb = parseInt(m[1], 10);
+        }
+        else if (line.startsWith('Pss:')) {
+            const m = /Pss:\s+(\d+)\s+kB/.exec(line);
+            if (m?.[1])
+                pssKb = parseInt(m[1], 10);
+        }
+    }
+    if (rssKb === null || pssKb === null)
+        return null;
+    return { rssBytes: rssKb * 1024, pssBytes: pssKb * 1024 };
+}
+// ---------------------------------------------------------------------------
+// Default injectable implementations
+// ---------------------------------------------------------------------------
+const defaultReadFile = (path, encoding) => readFile(path, encoding);
+const defaultStat = async (path) => {
+    try {
+        const s = await stat(path);
+        return { size: s.size };
+    }
+    catch {
+        return null;
+    }
+};
+// ---------------------------------------------------------------------------
+// Linux backend
+// ---------------------------------------------------------------------------
+/**
+ * Linux implementation of {@link ResourceBackend}.
+ *
+ * Uses injected `readFileFn` / `statFileFn` so unit tests can:
+ *   1. Fake file contents (threshold-crossing, degraded mode)
+ *   2. Count reads to assert the bounded-read contract (Amendment 1)
+ */
+export class LinuxResourceBackend {
+    globalPressurePath;
+    cgroupSlicePressurePath;
+    walPaths;
+    readFileFn;
+    statFileFn;
+    constructor(opts = {}) {
+        this.globalPressurePath = opts.globalPressurePath ?? '/proc/pressure/memory';
+        this.cgroupSlicePressurePath = opts.cgroupSlicePressurePath ?? null;
+        this.walPaths = opts.walPaths ?? [];
+        this.readFileFn = opts.readFileFn ?? defaultReadFile;
+        this.statFileFn = opts.statFileFn ?? defaultStat;
+    }
+    /**
+     * Take a bounded point-in-time resource sample.
+     *
+     * Read-count (bounded by Amendment 1):
+     *   - 1 read: `/proc/pressure/memory`
+     *   - 0–1 reads: slice `memory.pressure` (if configured)
+     *   - 1 read: `/proc/meminfo`
+     *   - N stat calls: one per WAL path in `walPaths`
+     *
+     * Never spawns a child process.
+     */
+    async sample() {
+        const sampledAtMs = Date.now();
+        // Read 1: global PSI
+        const globalPressure = await this._readPsi(this.globalPressurePath);
+        const pressureAvailable = globalPressure !== null;
+        // Read 2 (optional): slice PSI
+        let slicePressure = null;
+        if (this.cgroupSlicePressurePath) {
+            slicePressure = await this._readPsi(this.cgroupSlicePressurePath);
+        }
+        // Read 3: MemAvailable
+        const memAvailableBytes = await this._readMemAvailable();
+        // Read N: WAL stat observations
+        const walObservations = await this._readWalObservations();
+        return {
+            sampledAtMs,
+            pressureAvailable,
+            memAvailableBytes,
+            globalPressure,
+            slicePressure,
+            walObservations,
+        };
+    }
+    /**
+     * Sweep per-child RSS via `/proc/<pid>/smaps_rollup`.
+     *
+     * **STRUCTURALLY SEPARATED from sample()** — smaps_rollup reads are
+     * ms-scale per multi-GB process and must never appear in the hot path.
+     * Call on a separate low-frequency cadence (e.g. every 60s or on
+     * backoff→hold state transition).
+     *
+     * @param pids - PIDs to sweep. Dead/unknown PIDs are silently skipped.
+     */
+    async sweepChildRss(pids) {
+        const sampledAtMs = Date.now();
+        const entries = [];
+        for (const pid of pids) {
+            try {
+                const content = await this.readFileFn(`/proc/${pid}/smaps_rollup`, 'utf-8');
+                const parsed = parseSmapsRollup(content);
+                if (parsed) {
+                    entries.push({ pid, ...parsed });
+                }
+            }
+            catch {
+                // Dead or inaccessible PID — skip silently
+            }
+        }
+        return { sampledAtMs, entries };
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    async _readPsi(path) {
+        try {
+            const content = await this.readFileFn(path, 'utf-8');
+            return parsePsiFile(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async _readMemAvailable() {
+        try {
+            const content = await this.readFileFn('/proc/meminfo', 'utf-8');
+            return parseMemAvailable(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async _readWalObservations() {
+        const results = [];
+        for (const walPath of this.walPaths) {
+            const info = await this.statFileFn(walPath);
+            results.push({ walPath, sizeBytes: info?.size ?? null });
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=linux-backend.js.map

package/dist/resources/linux-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linux-backend.js","sourceRoot":"","sources":["../../src/resources/linux-backend.ts"],"names":[],"mappings":"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"}

package/dist/resources/monitor.d.ts

@@ -0,0 +1,230 @@
+/**
+ * ResourceMonitor — PSI + MemAvailable sensing, daemon-off capable.
+ *
+ * Two operational modes:
+ *
+ * 1. **Point-in-time sample** (`ResourceMonitor.sample()`): used inside the
+ *    governor acquire path when the daemon is off. Single call, bounded reads.
+ *
+ * 2. **Continuous loop** (`ResourceMonitor.startContinuous()`): used by the
+ *    daemon/supervisor. Polls at `pollIntervalMs` and emits `ok` → `hold` →
+ *    `backoff` state transitions with hysteresis.
+ *
+ * ## State machine
+ *
+ *   ok  ──── pressure > holdThreshold ──────→  hold
+ *   hold ─── pressure < holdThreshold - hyst ─→ ok
+ *   hold ─── pressure > backoffThreshold ─────→ backoff
+ *   backoff ─ pressure < holdThreshold - hyst ─→ ok
+ *
+ * Default thresholds (far below systemd-oomd's Fedora 80%/20s kill line):
+ *   - hold:    some avg10 > 10% OR full avg10 > 5%
+ *   - backoff: some avg10 > 20% OR full avg10 > 10%
+ *   - hysteresis: 3 percentage points (prevents thrash on threshold edge)
+ *
+ * ## Degraded mode
+ *
+ * When the PSI interface is absent (non-Linux, locked-down container,
+ * unprivileged environment), the monitor falls back to availability-only
+ * sampling: `pressureAvailable = false`, `state = 'ok'` unless
+ * `memAvailableBytes` is below `headroomMb`.
+ *
+ * ## oomd facts (Amendment 4)
+ *
+ * systemd-oomd on Fedora defaults to 80%/20s on user@1000.service (NOT
+ * the 50%/20s figure cited in older research). Our hold/backoff thresholds
+ * sit far below that line — cleo always throttles before oomd kills.
+ *
+ * ## WAL growth signal (Amendment 3)
+ *
+ * The monitor accepts an optional watch on SQLite `-wal` sidecar file sizes.
+ * A size above `walWarnThresholdBytes` is surfaced in the sample and can
+ * drive governor decisions independently of memory pressure.
+ *
+ * @module resources/monitor
+ * @task T11994
+ * @epic T11992
+ */
+import { EventEmitter } from 'node:events';
+import type { ResourceBackend, ResourceSample } from './backend.js';
+/**
+ * Memory pressure state transitions emitted by the continuous loop.
+ *
+ * - `ok`:      pressure below hold threshold — normal operation
+ * - `hold`:    pressure above hold threshold — slow down, avoid new allocs
+ * - `backoff`: pressure above backoff threshold — actively shed load
+ */
+export type PressureState = 'ok' | 'hold' | 'backoff';
+/**
+ * Emitted by {@link ResourceMonitor} when the pressure state changes.
+ */
+export interface StateTransition {
+    readonly from: PressureState;
+    readonly to: PressureState;
+    readonly sample: ResourceSample;
+    readonly reason: string;
+}
+/**
+ * Thresholds for the `some avg10` dimension (percentage points, 0–100).
+ */
+export interface SomePressureThresholds {
+    /** Enter `hold` state when `some avg10` exceeds this value. Default: 10. */
+    readonly holdSomeAvg10: number;
+    /** Enter `backoff` state when `some avg10` exceeds this value. Default: 20. */
+    readonly backoffSomeAvg10: number;
+}
+/**
+ * Thresholds for the `full avg10` dimension (percentage points, 0–100).
+ */
+export interface FullPressureThresholds {
+    /** Enter `hold` state when `full avg10` exceeds this value. Default: 5. */
+    readonly holdFullAvg10: number;
+    /** Enter `backoff` state when `full avg10` exceeds this value. Default: 10. */
+    readonly backoffFullAvg10: number;
+}
+/**
+ * Configuration for {@link ResourceMonitor}.
+ *
+ * All fields are optional — the defaults are calibrated to sit well below
+ * systemd-oomd's Fedora kill line of 80%/20s.
+ */
+export interface ResourceMonitorConfig {
+    /**
+     * `some avg10` pressure thresholds (percentage points, 0–100).
+     *
+     * Maps to the `resources.psi` config namespace (Amendment 5).
+     */
+    readonly psi?: Partial<SomePressureThresholds & FullPressureThresholds>;
+    /**
+     * Hysteresis band (percentage points).
+     *
+     * The monitor does NOT drop back to `ok` until pressure falls below
+     * `(holdThreshold - hysteresisPoints)` to prevent state thrashing.
+     *
+     * @defaultValue 3
+     */
+    readonly hysteresisPoints?: number;
+    /**
+     * Minimum free memory to consider the system healthy (bytes).
+     *
+     * Used in degraded mode (PSI absent) as the sole availability signal.
+     * Maps to the `resources.headroomMb` config namespace.
+     *
+     * @defaultValue 256 * 1024 * 1024 (256 MiB)
+     */
+    readonly headroomBytes?: number;
+    /**
+     * WAL file size above which a warning observation is surfaced.
+     *
+     * @defaultValue 256 * 1024 * 1024 (256 MiB)
+     */
+    readonly walWarnThresholdBytes?: number;
+    /**
+     * Poll interval for continuous mode (milliseconds).
+     *
+     * @defaultValue 1500
+     */
+    readonly pollIntervalMs?: number;
+    /**
+     * Platform backend. Defaults to {@link LinuxResourceBackend}.
+     *
+     * Inject a different backend for macOS parity or test fakes.
+     */
+    readonly backend?: ResourceBackend;
+}
+interface ResolvedThresholds {
+    readonly holdSomeAvg10: number;
+    readonly backoffSomeAvg10: number;
+    readonly holdFullAvg10: number;
+    readonly backoffFullAvg10: number;
+    readonly hysteresisPoints: number;
+    readonly headroomBytes: number;
+    readonly walWarnThresholdBytes: number;
+    readonly pollIntervalMs: number;
+}
+/**
+ * Evaluate the pressure state given a sample and resolved thresholds.
+ *
+ * In degraded mode (PSI absent), the state is `hold` only when free memory
+ * falls below `headroomBytes`.
+ *
+ * @internal
+ */
+export declare function evaluateState(sample: ResourceSample, thresholds: ResolvedThresholds, currentState: PressureState): {
+    state: PressureState;
+    reason: string;
+};
+/**
+ * ResourceMonitor event map for typed EventEmitter usage.
+ */
+interface ResourceMonitorEvents {
+    transition: [transition: StateTransition];
+    sample: [sample: ResourceSample];
+    error: [err: Error];
+}
+/**
+ * ResourceMonitor — PSI + MemAvailable sensing, daemon-off capable.
+ *
+ * @example Point-in-time (daemon-off governor acquire):
+ * ```ts
+ * const monitor = new ResourceMonitor();
+ * const sample = await monitor.sample();
+ * if (sample.memAvailableBytes !== null && sample.memAvailableBytes < 256 * 1024 * 1024) {
+ *   throw new Error('insufficient memory');
+ * }
+ * ```
+ *
+ * @example Continuous mode (daemon supervisor):
+ * ```ts
+ * const monitor = new ResourceMonitor({ pollIntervalMs: 1500 });
+ * monitor.on('transition', ({ from, to, reason }) => {
+ *   logger.warn(`pressure: ${from} → ${to} (${reason})`);
+ * });
+ * const stop = monitor.startContinuous();
+ * // later:
+ * stop();
+ * ```
+ */
+export declare class ResourceMonitor extends EventEmitter<ResourceMonitorEvents> {
+    private readonly thresholds;
+    private readonly backend;
+    private _state;
+    private _timer;
+    private _running;
+    constructor(cfg?: ResourceMonitorConfig);
+    /**
+     * Current pressure state (only meaningful after at least one sample).
+     */
+    get state(): PressureState;
+    /**
+     * `true` while the continuous loop is running.
+     */
+    get running(): boolean;
+    /**
+     * Take a single point-in-time resource sample.
+     *
+     * Safe to call with the daemon off (no child processes, bounded reads).
+     * Does NOT update `this.state` — use {@link startContinuous} for that.
+     */
+    sample(): Promise<ResourceSample>;
+    /**
+     * Start the continuous polling loop.
+     *
+     * Returns a `stop()` function. Calling `stop()` is idempotent.
+     *
+     * Emits:
+     *   - `'sample'` on every poll (even if state did not change)
+     *   - `'transition'` when `PressureState` changes
+     *   - `'error'` if the backend throws (loop continues regardless)
+     */
+    startContinuous(): () => void;
+    /**
+     * Stop the continuous polling loop. Idempotent.
+     */
+    stop(): void;
+    private _scheduleNext;
+    private _tick;
+    private _stopLoop;
+}
+export {};
+//# sourceMappingURL=monitor.d.ts.map

package/dist/resources/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../src/resources/monitor.ts"],"names":[],"mappings":"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"}