@n-dx/core 0.1.0

package/packages/hench/dist/process/limiter.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Cross-process concurrency limiter for hench.
+ *
+ * Prevents too many simultaneous `hench run` invocations from exhausting
+ * memory. Uses PID-based lock files in `.hench/locks/` to track active
+ * hench processes across terminals and sessions.
+ *
+ * Each `hench run` acquires a lock before starting work and releases it
+ * on exit. Stale locks (from crashed processes) are detected via OS-level
+ * PID liveness checks and cleaned up automatically.
+ *
+ * @module hench/process/limiter
+ */
+/**
+ * Thrown when the maximum concurrent hench process limit is reached.
+ *
+ * Contains metadata about active processes so the CLI can display a
+ * helpful message with actionable guidance.
+ */
+export declare class ProcessLimitReachedError extends Error {
+    /** Number of currently active hench processes. */
+    readonly activeCount: number;
+    /** Configured maximum concurrent processes. */
+    readonly maxConcurrent: number;
+    /** PIDs of currently active processes. */
+    readonly activePids: number[];
+    constructor(activeCount: number, maxConcurrent: number, activePids: number[]);
+}
+/**
+ * Manages cross-process concurrency for hench.
+ *
+ * Acquire a lock before starting a hench run; release it when done.
+ * The limiter checks the number of active hench processes (via PID lock
+ * files) and throws {@link ProcessLimitReachedError} if the limit is
+ * already reached.
+ *
+ * @example
+ * ```ts
+ * const limiter = new ProcessLimiter(henchDir, maxConcurrent);
+ * await limiter.acquire();
+ * try {
+ *   // ... run task
+ * } finally {
+ *   await limiter.release();
+ * }
+ * ```
+ */
+export declare class ProcessLimiter {
+    private readonly _henchDir;
+    private readonly _maxConcurrent;
+    private readonly _pid;
+    private _acquired;
+    constructor(henchDir: string, maxConcurrent: number);
+    /** Configured maximum concurrent processes. */
+    get maxConcurrent(): number;
+    /** Whether this limiter currently holds a lock. */
+    get acquired(): boolean;
+    /**
+     * Acquire a process slot.
+     *
+     * Checks the count of currently active hench processes. If the limit
+     * is already reached, throws {@link ProcessLimitReachedError} with
+     * metadata about the active processes.
+     *
+     * Creates a lock file for the current PID on success.
+     *
+     * @param taskId  Optional task ID for diagnostic display.
+     * @throws {ProcessLimitReachedError} when the limit is already reached.
+     */
+    acquire(taskId?: string): Promise<void>;
+    /**
+     * Release the process slot by removing the lock file.
+     *
+     * Safe to call multiple times (idempotent). Silently ignores
+     * missing lock files (e.g. if another process cleaned up stale locks).
+     */
+    release(): Promise<void>;
+    /**
+     * Get the count of currently active hench processes.
+     *
+     * Scans lock files and validates PIDs. Stale locks are cleaned up
+     * as a side effect.
+     */
+    activeCount(): Promise<number>;
+}

package/packages/hench/dist/process/limiter.js

@@ -0,0 +1,215 @@
+/**
+ * Cross-process concurrency limiter for hench.
+ *
+ * Prevents too many simultaneous `hench run` invocations from exhausting
+ * memory. Uses PID-based lock files in `.hench/locks/` to track active
+ * hench processes across terminals and sessions.
+ *
+ * Each `hench run` acquires a lock before starting work and releases it
+ * on exit. Stale locks (from crashed processes) are detected via OS-level
+ * PID liveness checks and cleaned up automatically.
+ *
+ * @module hench/process/limiter
+ */
+import { readdir, writeFile, unlink, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const LOCKS_DIR = "locks";
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when the maximum concurrent hench process limit is reached.
+ *
+ * Contains metadata about active processes so the CLI can display a
+ * helpful message with actionable guidance.
+ */
+export class ProcessLimitReachedError extends Error {
+    /** Number of currently active hench processes. */
+    activeCount;
+    /** Configured maximum concurrent processes. */
+    maxConcurrent;
+    /** PIDs of currently active processes. */
+    activePids;
+    constructor(activeCount, maxConcurrent, activePids) {
+        const msg = `Concurrent process limit reached: ${activeCount}/${maxConcurrent} hench processes running. ` +
+            `Wait for a running process to finish, or increase the limit with: ` +
+            `hench config guard.maxConcurrentProcesses <number>`;
+        super(msg);
+        this.name = "ProcessLimitReachedError";
+        this.activeCount = activeCount;
+        this.maxConcurrent = maxConcurrent;
+        this.activePids = activePids;
+    }
+}
+// ---------------------------------------------------------------------------
+// PID liveness check
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a process with the given PID is still alive.
+ *
+ * Uses `process.kill(pid, 0)` which sends signal 0 (no actual signal)
+ * to test for process existence. This works on all POSIX systems and
+ * Windows (Node.js abstracts the platform difference).
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Lock file helpers
+// ---------------------------------------------------------------------------
+function locksDir(henchDir) {
+    return join(henchDir, LOCKS_DIR);
+}
+function lockFilePath(henchDir, pid) {
+    return join(locksDir(henchDir), `${pid}.lock`);
+}
+async function ensureLocksDir(henchDir) {
+    await mkdir(locksDir(henchDir), { recursive: true });
+}
+/**
+ * Read all lock files and return only those with live PIDs.
+ * Stale lock files (from crashed processes) are removed automatically.
+ */
+async function getActiveLocks(henchDir) {
+    const dir = locksDir(henchDir);
+    await ensureLocksDir(henchDir);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const lockFiles = entries.filter((f) => f.endsWith(".lock"));
+    const active = [];
+    for (const file of lockFiles) {
+        const filePath = join(dir, file);
+        try {
+            const raw = await readFile(filePath, "utf-8");
+            const data = JSON.parse(raw);
+            if (isPidAlive(data.pid)) {
+                active.push(data);
+            }
+            else {
+                // Stale lock — process no longer running, clean it up
+                await unlink(filePath).catch(() => { });
+            }
+        }
+        catch {
+            // Corrupted lock file — remove it
+            await unlink(filePath).catch(() => { });
+        }
+    }
+    return active;
+}
+// ---------------------------------------------------------------------------
+// ProcessLimiter
+// ---------------------------------------------------------------------------
+/**
+ * Manages cross-process concurrency for hench.
+ *
+ * Acquire a lock before starting a hench run; release it when done.
+ * The limiter checks the number of active hench processes (via PID lock
+ * files) and throws {@link ProcessLimitReachedError} if the limit is
+ * already reached.
+ *
+ * @example
+ * ```ts
+ * const limiter = new ProcessLimiter(henchDir, maxConcurrent);
+ * await limiter.acquire();
+ * try {
+ *   // ... run task
+ * } finally {
+ *   await limiter.release();
+ * }
+ * ```
+ */
+export class ProcessLimiter {
+    _henchDir;
+    _maxConcurrent;
+    _pid;
+    _acquired = false;
+    constructor(henchDir, maxConcurrent) {
+        if (maxConcurrent < 1) {
+            throw new RangeError("ProcessLimiter maxConcurrent must be >= 1");
+        }
+        this._henchDir = henchDir;
+        this._maxConcurrent = maxConcurrent;
+        this._pid = process.pid;
+    }
+    /** Configured maximum concurrent processes. */
+    get maxConcurrent() {
+        return this._maxConcurrent;
+    }
+    /** Whether this limiter currently holds a lock. */
+    get acquired() {
+        return this._acquired;
+    }
+    /**
+     * Acquire a process slot.
+     *
+     * Checks the count of currently active hench processes. If the limit
+     * is already reached, throws {@link ProcessLimitReachedError} with
+     * metadata about the active processes.
+     *
+     * Creates a lock file for the current PID on success.
+     *
+     * @param taskId  Optional task ID for diagnostic display.
+     * @throws {ProcessLimitReachedError} when the limit is already reached.
+     */
+    async acquire(taskId) {
+        if (this._acquired) {
+            throw new Error("ProcessLimiter.acquire() called while already holding a lock");
+        }
+        await ensureLocksDir(this._henchDir);
+        const active = await getActiveLocks(this._henchDir);
+        if (active.length >= this._maxConcurrent) {
+            throw new ProcessLimitReachedError(active.length, this._maxConcurrent, active.map((l) => l.pid));
+        }
+        // Write lock file for this process
+        const data = {
+            pid: this._pid,
+            startedAt: new Date().toISOString(),
+            ...(taskId ? { taskId } : {}),
+        };
+        await writeFile(lockFilePath(this._henchDir, this._pid), JSON.stringify(data, null, 2), "utf-8");
+        this._acquired = true;
+    }
+    /**
+     * Release the process slot by removing the lock file.
+     *
+     * Safe to call multiple times (idempotent). Silently ignores
+     * missing lock files (e.g. if another process cleaned up stale locks).
+     */
+    async release() {
+        if (!this._acquired)
+            return;
+        try {
+            await unlink(lockFilePath(this._henchDir, this._pid));
+        }
+        catch {
+            // Lock file already gone — that's fine
+        }
+        this._acquired = false;
+    }
+    /**
+     * Get the count of currently active hench processes.
+     *
+     * Scans lock files and validates PIDs. Stale locks are cleaned up
+     * as a side effect.
+     */
+    async activeCount() {
+        const active = await getActiveLocks(this._henchDir);
+        return active.length;
+    }
+}
+//# sourceMappingURL=limiter.js.map

package/packages/hench/dist/process/limiter.js.map

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

package/packages/hench/dist/process/memory-monitor.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Cross-platform system memory monitoring for pre-spawn checks.
+ *
+ * Provides real-time memory usage detection across macOS, Linux, and Windows
+ * by using platform-specific APIs when available and falling back to
+ * `os.freemem()`/`os.totalmem()` as a baseline.
+ *
+ * Key differences from {@link MemoryThrottle}:
+ * - **MemoryThrottle** is the entry-gate decision engine (delay/reject at run start)
+ * - **SystemMemoryMonitor** provides accurate cross-platform memory readings
+ *   and a lightweight pre-spawn check for the tool dispatch path
+ *
+ * Integration points:
+ * - Implements `SystemMemoryReader` for use as a `MemoryThrottle` backend
+ * - Standalone `checkBeforeSpawn()` for per-tool-call memory gating
+ * - `snapshot()` for API/dashboard exposure
+ *
+ * Platform behavior:
+ * - **Linux**: reads `/proc/meminfo` for `MemAvailable` (accounts for
+ *   page cache and reclaimable slab memory the kernel can reclaim)
+ * - **macOS**: uses `os.freemem()` (Darwin's `vm_stat` free pages)
+ * - **Windows**: uses `os.freemem()` (Win32 `GlobalMemoryStatusEx`)
+ *
+ * @module hench/process/memory-monitor
+ */
+import type { SystemMemoryReader } from "./memory-throttle.js";
+/**
+ * Configuration for the system memory monitor.
+ */
+export interface MemoryMonitorConfig {
+    /** Enable pre-spawn memory checks. When false, all checks are bypassed. */
+    enabled: boolean;
+    /** Memory usage percentage above which spawning is blocked (0–100). */
+    spawnThreshold: number;
+}
+/** Default memory monitor configuration. */
+export declare const DEFAULT_MEMORY_MONITOR_CONFIG: MemoryMonitorConfig;
+/**
+ * Detailed cross-platform memory snapshot.
+ * Suitable for JSON serialization and API/dashboard exposure.
+ */
+export interface SystemMemorySnapshot {
+    /** Operating system platform. */
+    platform: NodeJS.Platform;
+    /** Total system memory in bytes. */
+    totalBytes: number;
+    /** Free memory in bytes (OS-reported, does not account for cache). */
+    freeBytes: number;
+    /**
+     * Available memory in bytes.
+     * On Linux, this is `MemAvailable` from `/proc/meminfo` (accounts for
+     * buffers/cache). On other platforms, falls back to `freeBytes`.
+     */
+    availableBytes: number;
+    /** Memory usage as a percentage (0–100), based on available memory. */
+    usagePercent: number;
+    /** Total memory in MB. */
+    totalMB: number;
+    /** Free memory in MB. */
+    freeMB: number;
+    /** Available memory in MB. */
+    availableMB: number;
+    /** ISO timestamp of this snapshot. */
+    timestamp: string;
+}
+/**
+ * Result of a pre-spawn memory check.
+ */
+export interface SpawnMemoryCheck {
+    /** Whether spawning is allowed. */
+    allowed: boolean;
+    /** Current memory usage percentage. */
+    usagePercent: number;
+    /** Configured spawn threshold. */
+    spawnThreshold: number;
+    /** Available memory in MB. */
+    availableMB: number;
+    /** Total memory in MB. */
+    totalMB: number;
+    /** Human-readable reason when blocked. Undefined when allowed. */
+    reason?: string;
+}
+/**
+ * Optional overrides for deterministic testing.
+ * When provided, these replace the real OS and filesystem calls.
+ */
+export interface MemoryMonitorOverrides {
+    /** Override detected platform. */
+    platform?: NodeJS.Platform;
+    /** Override `os.freemem()`. */
+    freemem?: () => number;
+    /** Override `os.totalmem()`. */
+    totalmem?: () => number;
+    /** Override Linux `/proc/meminfo` reader. */
+    readLinuxAvailable?: () => Promise<number | undefined>;
+    /** Override macOS `vm_stat` reader. */
+    readDarwinAvailable?: () => Promise<number | undefined>;
+}
+/**
+ * Cross-platform system memory monitor.
+ *
+ * Provides accurate memory readings and a pre-spawn check that can be
+ * called before every child process creation in the tool dispatch path.
+ *
+ * Implements {@link SystemMemoryReader} so it can also serve as the
+ * backend for {@link MemoryThrottle}, ensuring consistent memory readings
+ * across both the entry-gate check and per-spawn checks.
+ *
+ * @example
+ * ```ts
+ * const monitor = new SystemMemoryMonitor({ spawnThreshold: 85 });
+ *
+ * // Quick pre-spawn check
+ * const check = await monitor.checkBeforeSpawn();
+ * if (!check.allowed) {
+ *   console.warn(`Spawn blocked: ${check.reason}`);
+ * }
+ *
+ * // Full snapshot for dashboard/API
+ * const snap = await monitor.snapshot();
+ * console.log(`Memory: ${snap.usagePercent}% used`);
+ *
+ * // As SystemMemoryReader for MemoryThrottle
+ * const throttle = new MemoryThrottle(throttleConfig, monitor);
+ * ```
+ */
+export declare class SystemMemoryMonitor implements SystemMemoryReader {
+    private readonly _config;
+    private readonly _platform;
+    private readonly _freemem;
+    private readonly _totalmem;
+    private readonly _readLinuxAvailable;
+    private readonly _readDarwinAvailable;
+    constructor(config?: Partial<MemoryMonitorConfig>, overrides?: MemoryMonitorOverrides);
+    /** Current configuration (read-only copy). */
+    get config(): Readonly<MemoryMonitorConfig>;
+    /** Detected platform. */
+    get detectedPlatform(): NodeJS.Platform;
+    /** Free system memory in bytes. Synchronous (uses OS module). */
+    freemem(): number;
+    /** Total system memory in bytes. */
+    totalmem(): number;
+    /**
+     * Take a detailed cross-platform memory snapshot.
+     *
+     * On Linux, reads `/proc/meminfo` for accurate available memory.
+     * On other platforms, falls back to `os.freemem()`.
+     */
+    snapshot(): Promise<SystemMemorySnapshot>;
+    /**
+     * Check whether system memory allows spawning a new child process.
+     *
+     * This is the primary integration point for the tool dispatch path.
+     * Called before every process-spawning tool (`run_command`, `git`)
+     * to prevent system-wide memory pressure.
+     *
+     * When disabled (via config), always returns `{ allowed: true }`.
+     *
+     * @returns Structured result with the decision and current memory state.
+     */
+    checkBeforeSpawn(): Promise<SpawnMemoryCheck>;
+}