@aron98/load-lock 0.0.0-stage → 0.1.0

package/dist/shared/client.js

@@ -0,0 +1,227 @@
+/**
+ * NDJSON-over-UDS client for the load-lock daemon, shared by the CLI, the
+ * MCP server, and harness hook scripts. The OpenCode plugin ships a
+ * self-contained copy of this logic (see adapters/opencode).
+ *
+ * Auto-spawn: if the daemon socket is absent, exactly one client becomes the
+ * spawner (serialized by a mkdir-based lock — atomic on POSIX) and starts a
+ * detached daemon; losers wait for the socket to appear. The freshly spawned
+ * daemon itself re-checks the socket before binding, so a double-spawn is
+ * harmless (the loser exits).
+ */
+import { connect } from "node:net";
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { ProtocolError } from "./protocol.js";
+import { socketPath as defaultSocket, stateDir as defaultStateDir } from "../core/persist.js";
+export class LLClient {
+    sock = null;
+    nextId = 1;
+    pending = new Map();
+    eventCb = null;
+    buf = "";
+    opts;
+    constructor(opts = {}) {
+        this.opts = { spawnDaemon: opts.spawnDaemon ?? true, socket: opts.socket ?? "", stateDir: opts.stateDir };
+    }
+    socketPath() {
+        return this.opts.socket || defaultSocket();
+    }
+    stateDirPath() {
+        return this.opts.stateDir || defaultStateDir();
+    }
+    async connect() {
+        try {
+            await this.tryConnect();
+            return;
+        }
+        catch {
+            /* fall through to spawn */
+        }
+        if (!this.opts.spawnDaemon) {
+            throw new ProtocolError("unavailable", `load-lock daemon is not running on ${this.socketPath()}`);
+        }
+        await ensureDaemon(this.stateDirPath(), this.socketPath());
+        await this.tryConnect();
+    }
+    tryConnect() {
+        return new Promise((resolve, reject) => {
+            const sock = connect(this.socketPath());
+            sock.once("connect", () => {
+                this.attach(sock);
+                resolve();
+            });
+            sock.once("error", (err) => {
+                sock.destroy();
+                reject(err);
+            });
+        });
+    }
+    attach(sock) {
+        this.sock = sock;
+        sock.on("data", (chunk) => {
+            this.buf += chunk.toString("utf8");
+            let idx;
+            while ((idx = this.buf.indexOf("\n")) !== -1) {
+                const line = this.buf.slice(0, idx);
+                this.buf = this.buf.slice(idx + 1);
+                if (!line.trim())
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.event === true) {
+                    this.eventCb?.(msg);
+                    continue;
+                }
+                const p = this.pending.get(msg.id);
+                if (p) {
+                    this.pending.delete(msg.id);
+                    if (msg.ok)
+                        p.resolve(msg.result);
+                    else
+                        p.reject(new ProtocolError(msg.error?.code ?? "internal", msg.error?.message ?? "daemon error", msg.error?.details));
+                }
+            }
+        });
+        sock.on("error", () => {
+            this.failAll(new ProtocolError("unavailable", "daemon connection lost"));
+            this.sock = null;
+        });
+        sock.on("close", () => {
+            this.failAll(new ProtocolError("unavailable", "daemon connection closed"));
+            this.sock = null;
+        });
+    }
+    failAll(err) {
+        for (const p of this.pending.values())
+            p.reject(err);
+        this.pending.clear();
+    }
+    ensureSock() {
+        if (!this.sock || this.sock.destroyed)
+            throw new ProtocolError("unavailable", "not connected");
+        return this.sock;
+    }
+    /** Issue one RPC. Reconnects once if the connection was lost. */
+    async request(method, params = {}, timeoutMs = 20_000) {
+        if (!this.sock || this.sock.destroyed)
+            await this.connect();
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new ProtocolError("unavailable", `timeout waiting for daemon response to ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            const sock = this.ensureSock();
+            sock.write(JSON.stringify({ id, method, params }) + "\n");
+        });
+    }
+    /** Subscribe to daemon events targeted at agentId (or "*" for all). */
+    async watch(agentId, onEvent) {
+        this.eventCb = onEvent;
+        await this.request("watch", { agentId });
+    }
+    close() {
+        this.sock?.destroy();
+        this.sock = null;
+    }
+}
+// ------------------------------------------------------------------- spawning
+function daemonMainPath() {
+    if (process.env.LOAD_LOCK_DAEMON_BIN)
+        return process.env.LOAD_LOCK_DAEMON_BIN;
+    const here = dirname(fileURLToPath(import.meta.url)); // .../dist/shared
+    return join(here, "..", "core", "daemon-main.js");
+}
+/** Idempotently ensure a daemon is running and listening on `sockPath`. */
+export async function ensureDaemon(stateDir, sockPath) {
+    if (await probe(sockPath))
+        return;
+    const lockDir = join(stateDir, "spawn.lock");
+    mkdirSync(stateDir, { recursive: true });
+    let holding = false;
+    for (let i = 0; i < 60; i++) {
+        try {
+            mkdirSync(lockDir); // atomic on POSIX
+            holding = true;
+            writeFileSync(join(lockDir, "info"), JSON.stringify({ pid: process.pid, ts: Date.now() }));
+            break;
+        }
+        catch {
+            // Someone else is spawning. Clean up stale locks (older than 15s).
+            try {
+                const st = existsSync(join(lockDir, "info")) ? JSON.parse(readFileSync(join(lockDir, "info"), "utf8")) : null;
+                if (!st || Date.now() - st.ts > 15_000)
+                    rmSync(lockDir, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore */
+            }
+            if (await probe(sockPath))
+                return;
+            await delay(250);
+        }
+    }
+    try {
+        if (holding) {
+            // Re-check: another spawn may have won the race while we waited.
+            if (!(await probe(sockPath))) {
+                const child = spawn(process.execPath, [daemonMainPath(), "--state-dir", stateDir, "--socket", sockPath], {
+                    detached: true,
+                    stdio: "ignore",
+                    env: { ...process.env, LOAD_LOCK_DAEMON_SPAWNED: "1" },
+                });
+                child.unref();
+            }
+        }
+        for (let i = 0; i < 40; i++) {
+            if (await probe(sockPath))
+                return;
+            await delay(250);
+        }
+        throw new ProtocolError("unavailable", "load-lock daemon did not come up within 10s; run `load-lock doctor`");
+    }
+    finally {
+        if (holding)
+            rmSync(lockDir, { recursive: true, force: true });
+    }
+}
+function probe(sockPath) {
+    return new Promise((resolve) => {
+        const s = connect(sockPath);
+        s.once("connect", () => {
+            s.end();
+            resolve(true);
+        });
+        s.once("error", () => resolve(false));
+    });
+}
+/** One-shot helper: connect (auto-spawning), run fn, close. */
+export async function withClient(fn, opts = {}) {
+    const c = new LLClient(opts);
+    try {
+        await c.connect();
+        return await fn(c);
+    }
+    finally {
+        c.close();
+    }
+}

package/dist/shared/protocol.d.ts

@@ -0,0 +1,333 @@
+/**
+ * load-lock shared wire protocol types.
+ *
+ * Transport: newline-delimited JSON (NDJSON) over a Unix domain socket.
+ * Each line is one request or one response; watch connections additionally
+ * receive unsolicited event lines.
+ *
+ * Request:  {"id": <number>, "method": "<name>", "params": {...}}
+ * Response: {"id": <number>, "ok": true, "result": {...}}
+ *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
+ * Watch push: {"event": true, ...event fields...}
+ */
+export declare const DAEMON_PROTOCOL_VERSION = 1;
+export type ErrorCode = "invalid" | "not_found" | "stale_token" | "offer_expired" | "wrong_state" | "version_conflict" | "denied" | "unavailable" | "internal";
+export declare class ProtocolError extends Error {
+    code: ErrorCode;
+    details?: unknown;
+    constructor(code: ErrorCode, message: string, details?: unknown);
+}
+export interface PoolConfig {
+    /** Maximum total weight admitted concurrently (permits + outstanding offers). */
+    capacity: number;
+}
+export interface MachineConfig {
+    /** Monotonically increasing; used for compare-and-swap configure(). */
+    version: number;
+    pools: Record<string, PoolConfig>;
+    /** Claim window for offers, in milliseconds. */
+    offerTimeoutMs: number;
+    /** Upper bound for bounded blocking waits in acquire (advisory). */
+    maxWaitMs: number;
+    /**
+     * Start deadline: after a permit is claimed/granted, execution must begin
+     * (run_with_permit / attach_pid / mark_started) within this window, or the
+     * permit is reclaimed automatically. Covers "claimed but never started".
+     */
+    startTimeoutMs: number;
+    /**
+     * Lease for running permits that have NO process association: renewed by
+     * automatic adapter heartbeats; expires when the owning agent is gone.
+     * Tracked permits are never leased — they are released on confirmed job
+     * death instead. See docs/ARCHITECTURE.md for the explicit tradeoff.
+     */
+    untrackedLeaseMs: number;
+    /**
+     * Free-form heavy-vs-light guidance text agents can publish for humans
+     * and other agents (e.g. "cargo build+test count as heavy; prefer 2 test threads").
+     */
+    guidance: {
+        heavyWorkHeuristic?: string;
+        notes?: string;
+        agents?: Record<string, {
+            parallelism?: string;
+            note?: string;
+            updatedBy?: string;
+            updatedAt?: number;
+        }>;
+    };
+}
+export interface ConfigChange {
+    pools?: Record<string, PoolConfig>;
+    offerTimeoutMs?: number;
+    maxWaitMs?: number;
+    startTimeoutMs?: number;
+    untrackedLeaseMs?: number;
+    guidance?: {
+        heavyWorkHeuristic?: string;
+        notes?: string;
+        agent?: {
+            id: string;
+            parallelism?: string;
+            note?: string;
+        };
+    };
+}
+export interface ConfigHistoryEntry {
+    ts: number;
+    author: string;
+    reason: string;
+    changes: ConfigChange;
+    resultingVersion: number;
+}
+export interface PersistedState {
+    config: MachineConfig;
+    history: ConfigHistoryEntry[];
+}
+export type EntryState = "queued" | "offered" | "held" | "paused" | "released" | "cancelled";
+/**
+ * Lifecycle phase of a held permit.
+ *
+ *  claimed          -> claimed, execution not yet started; start deadline ticking
+ *  running_tracked  -> associated with a real process (pid + start time, and
+ *                      usually a process group); released on confirmed death
+ *  running_untracked-> agent said "I started work" but no process association;
+ *                      heartbeat-renewed lease applies (documented tradeoff)
+ */
+export type PermitPhase = "claimed" | "running_tracked" | "running_untracked";
+export interface EntrySnapshot {
+    requestId: string;
+    pool: string;
+    agentId: string;
+    agentLabel?: string;
+    cwd?: string;
+    opKey: string;
+    reason: string;
+    weight: number;
+    state: EntryState;
+    /** Present when state === "held". */
+    phase?: PermitPhase;
+    since: number;
+    /** 1-based FIFO position, only for queued entries. */
+    position?: number;
+    pid?: number;
+    pgid?: number;
+    pidStartTime?: string;
+    offerExpiresAt?: number;
+    startDeadline?: number;
+    leaseDeadline?: number;
+    lastSeen?: number;
+    heldFor?: number;
+}
+/** Owner-scoped snapshot: includes tokens. Never returned to non-owners. */
+export interface OwnerEntrySnapshot extends EntrySnapshot {
+    offerToken?: string;
+    permitToken?: string;
+}
+export interface JournalEntry {
+    requestId: string;
+    pool: string;
+    agentId: string;
+    agentLabel?: string;
+    cwd?: string;
+    opKey: string;
+    reason: string;
+    weight: number;
+    permitToken: string;
+    phase: PermitPhase;
+    pid?: number;
+    pgid?: number;
+    pidStartTime?: string;
+    claimedAt: number;
+    startedAt?: number;
+    leaseDeadline?: number;
+}
+export interface PoolStatus {
+    pool: string;
+    capacity: number;
+    used: number;
+    holders: EntrySnapshot[];
+    offers: EntrySnapshot[];
+    queue: EntrySnapshot[];
+    paused: EntrySnapshot[];
+}
+export interface StatusResult {
+    daemon: {
+        pid: number;
+        startedAt: number;
+        protocolVersion: number;
+    };
+    config: {
+        version: number;
+        pools: Record<string, PoolConfig>;
+        offerTimeoutMs: number;
+        maxWaitMs: number;
+        startTimeoutMs: number;
+        untrackedLeaseMs: number;
+    };
+    pools: PoolStatus[];
+    events: {
+        latestEventId: number;
+    };
+}
+export interface CpuInfo {
+    logicalCores: number;
+    model?: string;
+    loadavg: [number, number, number];
+    cgroupVersion?: string;
+    cgroupCpuQuota?: number | null;
+    cgroupCpuPeriod?: number | null;
+    effectiveCores: number;
+    loadPerEffectiveCore: number;
+}
+export interface MemInfo {
+    totalBytes: number;
+    availableBytes: number;
+    freeBytes: number;
+    cgroupMemoryLimitBytes?: number | null;
+    cgroupMemoryUsageBytes?: number | null;
+    effectiveLimitBytes: number;
+}
+export interface InspectResult {
+    cpu: CpuInfo;
+    memory: MemInfo;
+    pressure: {
+        note: string;
+        loadPressure: "low" | "moderate" | "high";
+        memPressure: "low" | "moderate" | "high";
+    };
+    loadLock: {
+        pools: Record<string, PoolConfig>;
+        suggestion: string;
+    };
+}
+export type EventType = "daemon_started" | "daemon_recovered" | "granted" | "queued" | "offered" | "claimed" | "started" | "released" | "auto_released" | "reclaimed" | "offer_expired" | "declined" | "paused" | "rejoined" | "cancelled" | "config_changed";
+export interface MachineEvent {
+    id: number;
+    ts: number;
+    type: EventType;
+    pool?: string;
+    /** Target agent for routing; "*" for broadcasts (config changes). */
+    targetAgent?: string;
+    entry?: EntrySnapshot;
+    /** Present on `offered` events delivered to the owner: the claim token. */
+    offerToken?: string;
+    detail?: string;
+}
+export interface AcquireParams {
+    pool?: string;
+    agentId: string;
+    agentLabel?: string;
+    cwd?: string;
+    opKey: string;
+    reason: string;
+    weight?: number;
+    subscribeIfBusy?: boolean;
+    waitMs?: number;
+    pid?: number;
+    pidStartTime?: string;
+}
+export type AcquireResult = {
+    state: "granted";
+    entry: OwnerEntrySnapshot;
+} | {
+    state: "offered";
+    entry: OwnerEntrySnapshot;
+} | {
+    state: "queued";
+    entry: OwnerEntrySnapshot;
+} | {
+    state: "paused";
+    entry: OwnerEntrySnapshot;
+} | {
+    state: "denied";
+    entry: null;
+};
+export interface ClaimParams {
+    offerToken: string;
+}
+export interface ClaimResult {
+    entry: OwnerEntrySnapshot;
+}
+export interface ReleaseParams {
+    permitToken: string;
+    outcome?: "success" | "failure" | "terminated" | "done";
+}
+export interface ReleaseResult {
+    entry: EntrySnapshot;
+    /** True if this call actually performed the release (false = already terminal). */
+    releasedNow: boolean;
+}
+export interface CancelParams {
+    requestId: string;
+    admin?: boolean;
+}
+export interface CancelResult {
+    entry: EntrySnapshot;
+}
+export interface DeclineParams {
+    offerToken: string;
+}
+export interface RejoinParams {
+    requestId: string;
+}
+/** Start job: associate a claimed permit with a real process. Atomic wrt reclamation. */
+export interface StartJobParams {
+    permitToken: string;
+    pid: number;
+    pgid?: number;
+}
+/** Mark started without process association: untracked lease applies. */
+export interface MarkStartedParams {
+    permitToken: string;
+}
+export interface HeartbeatParams {
+    agentId: string;
+}
+export interface PendingParams {
+    agentId: string;
+}
+export interface PendingResult {
+    offers: OwnerEntrySnapshot[];
+    queue: OwnerEntrySnapshot[];
+    paused: OwnerEntrySnapshot[];
+    held: OwnerEntrySnapshot[];
+}
+export interface StatusParams {
+    pool?: string;
+}
+export interface GetConfigResult {
+    config: MachineConfig;
+    history: ConfigHistoryEntry[];
+}
+export interface ConfigureParams {
+    expectedVersion: number;
+    changes: ConfigChange;
+    reason: string;
+    author: string;
+}
+export interface ConfigureResult {
+    config: MachineConfig;
+    history: ConfigHistoryEntry[];
+}
+export interface EventsParams {
+    agentId?: string;
+    sinceEventId?: number;
+    limit?: number;
+}
+export interface EventsResult {
+    events: MachineEvent[];
+    latestEventId: number;
+}
+/** Recovery diagnostics: held permits with holder + job information. */
+export interface HolderDiag {
+    entry: EntrySnapshot;
+    diagnostics: {
+        tracked: boolean;
+        processAlive?: boolean | null;
+        phaseAgeMs: number;
+        lastSeenAgeMs?: number;
+        longHold: boolean;
+        note: string;
+    };
+}

package/dist/shared/protocol.js

@@ -0,0 +1,22 @@
+/**
+ * load-lock shared wire protocol types.
+ *
+ * Transport: newline-delimited JSON (NDJSON) over a Unix domain socket.
+ * Each line is one request or one response; watch connections additionally
+ * receive unsolicited event lines.
+ *
+ * Request:  {"id": <number>, "method": "<name>", "params": {...}}
+ * Response: {"id": <number>, "ok": true, "result": {...}}
+ *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
+ * Watch push: {"event": true, ...event fields...}
+ */
+export const DAEMON_PROTOCOL_VERSION = 1;
+export class ProtocolError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/test/core.test.d.ts

@@ -0,0 +1 @@
+export {};