@aron98/load-lock 0.1.2 → 1.0.0

package/dist/dashboard/feed.js

@@ -0,0 +1,256 @@
+import { buildDashboardView } from "./view.js";
+const DEFAULTS = {
+    eventHistory: 60,
+    slowRefreshMs: 15_000,
+    refreshDebounceMs: 40,
+    inspectEveryMs: 60_000,
+    reconnectBaseMs: 250,
+};
+export class DashboardFeed {
+    client;
+    opts;
+    events = [];
+    latestEventId = 0;
+    status = null;
+    inspect = null;
+    inspectAt = 0;
+    lastSyncAt = 0;
+    state = "connecting";
+    restartNote;
+    daemonStartedAt = 0;
+    refreshTimer = null;
+    slowTimer = null;
+    stopped = false;
+    unsub = null;
+    connecting = null;
+    viewSeq = 0;
+    /** Fired whenever the rendered view might have changed (state or data). */
+    onChange;
+    /** Fired on connection-state transitions. */
+    onState;
+    constructor(client, opts = {}) {
+        this.client = client;
+        this.opts = { ...DEFAULTS, ...opts };
+    }
+    currentState() {
+        return this.state;
+    }
+    setState(s) {
+        if (this.state === s)
+            return;
+        this.state = s;
+        try {
+            this.onState?.(s);
+        }
+        catch {
+            /* consumer error */
+        }
+        this.emitChange();
+    }
+    emitChange() {
+        this.viewSeq++;
+        try {
+            this.onChange?.();
+        }
+        catch {
+            /* consumer error */
+        }
+    }
+    /** Connect, subscribe, and pull an initial full snapshot. */
+    async start() {
+        this.stopped = false;
+        this.unsub =
+            typeof this.client.onDisconnect === "function"
+                ? (this.client.onDisconnect(() => void this.handleDisconnect()) ?? undefined)
+                : null;
+        await this.connectAndSync();
+        this.slowTimer =
+            this.opts.slowRefreshMs > 0
+                ? setInterval(() => {
+                    if (this.state === "live")
+                        void this.refresh().catch(() => { });
+                }, this.opts.slowRefreshMs)
+                : null;
+        this.slowTimer?.unref?.();
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        if (this.slowTimer)
+            clearInterval(this.slowTimer);
+        this.refreshTimer = null;
+        this.slowTimer = null;
+        this.unsub?.();
+        this.unsub = null;
+        this.client.close();
+    }
+    async connectAndSync() {
+        this.setState("connecting");
+        await this.client.connect();
+        await this.client.watch("*", (ev) => this.handleEvent(ev));
+        await this.resync();
+        this.setState("live");
+    }
+    /**
+     * Full snapshot: status + events since cursor (+ inspect if stale).
+     * Detects daemon restarts two ways — event ids going backwards, or the
+     * daemon's own startedAt changing — then resets the cursor and re-pulls
+     * history (ids are durable per daemon lifetime, not across restarts).
+     */
+    async resync() {
+        if (this.stopped)
+            return;
+        const [status, evRes] = await Promise.all([
+            this.client.request("status", {}),
+            this.client.request("events", { sinceEventId: this.latestEventId }),
+        ]);
+        const daemonStartChanged = status.daemon != null && this.daemonStartedAt !== 0 && status.daemon.startedAt !== this.daemonStartedAt;
+        this.status = status;
+        this.daemonStartedAt = status.daemon?.startedAt ?? 0;
+        this.mergeEvents(evRes.events, evRes.latestEventId);
+        let restartNote;
+        if (daemonStartChanged || evRes.latestEventId < this.latestEventId) {
+            // Daemon restarted: ids restarted from scratch. Reset and re-pull.
+            restartNote = `daemon restarted (pid ${status.daemon?.pid ?? "?"}); event history re-synced`;
+            this.events = [];
+            this.latestEventId = 0;
+            const fresh = await this.client.request("events", { sinceEventId: 0 });
+            this.mergeEvents(fresh.events, fresh.latestEventId);
+        }
+        this.restartNote = restartNote;
+        if (this.inspectAt === 0 || Date.now() - this.inspectAt > this.opts.inspectEveryMs) {
+            await this.refreshInspect();
+        }
+        this.lastSyncAt = Date.now();
+        this.emitChange();
+    }
+    /** Status-only pull (used after event bursts; keeps inspect cached). */
+    async refresh() {
+        if (this.stopped)
+            return;
+        try {
+            this.status = await this.client.request("status", {});
+        }
+        catch (e) {
+            if (e?.code === "unavailable") {
+                void this.handleDisconnect();
+                return;
+            }
+            throw e;
+        }
+        if (Date.now() - this.inspectAt > this.opts.inspectEveryMs)
+            await this.refreshInspect();
+        this.lastSyncAt = Date.now();
+        this.emitChange();
+    }
+    async refreshInspect() {
+        try {
+            this.inspect = await this.client.request("inspect", {});
+            this.inspectAt = Date.now();
+        }
+        catch {
+            /* inspect is best-effort; status carries the essential state */
+        }
+    }
+    handleEvent(raw) {
+        // The daemon confirms a watch subscription with a `watch_started` push
+        // (not a MachineEvent): {event:true, type, latestEventId}.
+        if (raw.type === "watch_started") {
+            // Confirmation push carrying the daemon's current event-id upper
+            // bound. Deliberately NOT adopted as our cursor: the cursor only
+            // advances when events are actually observed (pushed or pulled),
+            // so the initial `events since 0` fetches full history and a
+            // reconnect pulls the whole gap since the last seen id. Adopting
+            // the bound here would skip everything between cursor and now.
+            // Daemon restarts (bound going backwards) are caught in resync()
+            // by comparing the pulled latestEventId against our cursor.
+            return;
+        }
+        const ev = raw;
+        if (typeof ev.id === "number" && ev.id > this.latestEventId) {
+            this.latestEventId = ev.id;
+            this.events.push(ev);
+            if (this.events.length > this.opts.eventHistory) {
+                this.events.splice(0, this.events.length - this.opts.eventHistory);
+            }
+        }
+        // Coalesce bursts: one status pull per debounce window.
+        if (!this.refreshTimer) {
+            this.refreshTimer = setTimeout(() => {
+                this.refreshTimer = null;
+                void this.refresh().catch(() => {
+                    /* reconnect loop owns recovery */
+                });
+            }, this.opts.refreshDebounceMs);
+            this.refreshTimer.unref?.();
+        }
+        this.emitChange();
+    }
+    mergeEvents(evs, latestEventId) {
+        const seen = new Set(this.events.map((e) => e.id));
+        for (const e of evs) {
+            if (seen.has(e.id))
+                continue;
+            seen.add(e.id);
+            this.events.push(e);
+        }
+        this.events.sort((a, b) => a.id - b.id);
+        if (this.events.length > this.opts.eventHistory) {
+            this.events.splice(0, this.events.length - this.opts.eventHistory);
+        }
+        if (latestEventId > this.latestEventId)
+            this.latestEventId = latestEventId;
+    }
+    handleDisconnect() {
+        if (this.stopped || this.state === "reconnecting")
+            return;
+        this.setState("reconnecting");
+        void this.reconnectLoop();
+    }
+    async reconnectLoop() {
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = (async () => {
+            let attempt = 0;
+            while (!this.stopped) {
+                const wait = Math.min(this.opts.reconnectBaseMs * 2 ** Math.min(attempt, 5), 8_000);
+                if (attempt > 0)
+                    await new Promise((r) => setTimeout(r, wait));
+                attempt++;
+                try {
+                    await this.connectAndSync();
+                    this.connecting = null;
+                    return;
+                }
+                catch {
+                    this.setState("reconnecting");
+                }
+            }
+            this.connecting = null;
+        })();
+        return this.connecting;
+    }
+    /**
+     * Admin force-release. Callers MUST gate this behind their own explicit
+     * confirm step — the feed itself never initiates destructive actions.
+     * Returns the reclaimed request's one-line description for toasts.
+     */
+    async forceRelease(requestId) {
+        await this.client.request("admin_release", { requestId });
+        await this.refresh().catch(() => { });
+    }
+    /** Render-ready snapshot; countdowns are computed at `now`. */
+    view(now = Date.now()) {
+        return buildDashboardView({
+            status: this.status,
+            inspect: this.inspect,
+            events: this.events,
+            latestEventId: this.latestEventId,
+            state: this.state,
+            lastSyncAt: this.lastSyncAt,
+            daemonRestartNote: this.restartNote,
+            now,
+        });
+    }
+}

package/dist/dashboard/frame.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Plain-text frame renderer for `load-lock top` — and for any other
+ * terminal surface that wants the same dashboard without a TUI toolkit.
+ * Pure function: view-model in, string[] out (one line per row).
+ *
+ * Deliberately zero-dependency (ANSI handled by the caller): this keeps
+ * the published package lightweight and makes the layout unit-testable.
+ */
+import { type DashboardView } from "./view.js";
+export declare function utilizationBar(frac: number, width?: number): string;
+/** Render one full frame; `width`/`height` bound the output (rows last). */
+export declare function renderFrame(view: DashboardView, width?: number, height?: number): string[];

package/dist/dashboard/frame.js

@@ -0,0 +1,94 @@
+/**
+ * Plain-text frame renderer for `load-lock top` — and for any other
+ * terminal surface that wants the same dashboard without a TUI toolkit.
+ * Pure function: view-model in, string[] out (one line per row).
+ *
+ * Deliberately zero-dependency (ANSI handled by the caller): this keeps
+ * the published package lightweight and makes the layout unit-testable.
+ */
+import { fmtBytes, fmtClock, fmtDuration, } from "./view.js";
+const STATE_LABEL = {
+    live: "LIVE",
+    connecting: "CONNECTING",
+    reconnecting: "RECONNECTING",
+    down: "DAEMON DOWN",
+};
+export function utilizationBar(frac, width = 10) {
+    const w = Math.max(3, width);
+    const filled = Math.round(Math.min(1, Math.max(0, frac)) * w);
+    return `${"#".repeat(filled)}${"-".repeat(w - filled)}`;
+}
+function holderLines(pool, out) {
+    for (const h of pool.holders) {
+        const id = h.requestId.slice(0, 14);
+        let meta = h.phaseLabel;
+        if (h.phase === "claimed" && h.startDeadlineInMs !== undefined)
+            meta += ` · must start in ${fmtDuration(h.startDeadlineInMs)}`;
+        if (h.phase === "running_tracked" && h.pid !== undefined)
+            meta += ` · pid ${h.pid}` + (h.pgid !== undefined && h.pgid !== h.pid ? ` · pgid ${h.pgid}` : "");
+        if (h.phase === "running_untracked" && h.leaseDeadlineInMs !== undefined)
+            meta += ` · lease ends in ${fmtDuration(h.leaseDeadlineInMs)}`;
+        out(`  HELD   ${h.agent} (${id}) · ${meta} · age ${fmtDuration(h.heldMs)}`);
+        out(`         reason: ${h.reason}`);
+    }
+    for (const o of pool.offers) {
+        const id = o.requestId.slice(0, 14);
+        const window = o.claimInMs >= 0 ? `claim within ${fmtDuration(o.claimInMs)}` : "claim window elapsed (pause pending)";
+        out(`  OFFER  ${o.agent} (${id}) · ${window} · expires ${fmtClock(o.expiresAt)}`);
+        out(`         reason: ${o.reason}`);
+    }
+    for (const q of pool.queue) {
+        out(`  QUEUE  #${q.position}  ${q.agent} — ${q.reason} (waiting ${fmtDuration(q.waitMs)})`);
+    }
+    for (const p of pool.paused) {
+        out(`  PAUSED ${p.agent} — ${p.reason} (paused ${fmtDuration(p.pausedMs)} · rejoin required)`);
+    }
+}
+/** Render one full frame; `width`/`height` bound the output (rows last). */
+export function renderFrame(view, width = 100, height = 40) {
+    const W = Math.max(48, Math.min(width, 240));
+    const lines = [];
+    const push = (s) => {
+        if (s.length > W)
+            lines.push(s.slice(0, W - 1) + "…");
+        else
+            lines.push(s);
+    };
+    const state = STATE_LABEL[view.state] ?? String(view.state);
+    const syncAge = view.lastSyncAt ? fmtDuration(Math.max(0, view.now - view.lastSyncAt)) : "never";
+    push(`load-lock top — machine-wide heavy-work budget   ${state}   synced ${syncAge} ago`);
+    if (view.daemon) {
+        push(`daemon pid ${view.daemon.pid} · uptime ${fmtDuration(view.daemon.uptimeMs)} · config v${view.daemon.configVersion} · protocol v${view.daemon.protocolVersion} · events through #${view.latestEventId}`);
+    }
+    else {
+        push(`daemon: unreachable — it auto-spawns on the next load-lock command`);
+    }
+    if (view.daemonRestartNote)
+        push(`note: ${view.daemonRestartNote}`);
+    if (view.machine) {
+        const m = view.machine;
+        const cg = m.cgroupCpuQuota != null ? ` · cgroup ${m.cgroupVersion ?? ""} quota ${m.cgroupCpuQuota / 100} CPU` : "";
+        push(`MACHINE  ${m.logicalCores} cores (effective ${m.effectiveCores}${cg}) · load ${m.loadavg.map((n) => n.toFixed(2)).join(" ")} = ${m.loadPerEffectiveCore.toFixed(2)}/core · mem ${fmtBytes(m.memTotalBytes)} total, ${fmtBytes(m.memAvailableBytes)} avail (limit ${fmtBytes(m.memEffectiveLimitBytes)})`);
+        push(`         pressure: cpu ${m.loadPressure}, mem ${m.memPressure} — ${m.note}`);
+    }
+    push("");
+    if (!view.pools.length)
+        push(`no pools configured`);
+    for (const p of view.pools) {
+        push(`POOL ${p.pool}  [${utilizationBar(p.utilization)}]  ${p.used}/${p.capacity} used (held ${p.heldWeight}, offered ${p.offeredWeight}, free ${p.free}) · queue ${p.queue.length} · paused ${p.paused.length}`);
+        holderLines(p, push);
+    }
+    push("");
+    push(`EVENTS (newest first)`);
+    if (!view.events.length)
+        push(`  (no events yet)`);
+    for (const e of view.events.slice(0, 12)) {
+        push(`  #${e.id} ${fmtClock(e.ts)}  ${e.text}`);
+    }
+    push("");
+    push(`q quit · r resync · read-only viewer — light work, never acquires a permit`);
+    push(`force-release is an admin action gated behind an explicit confirm (not available here; use the OpenCode panel or load-lock recover force-release)`);
+    if (lines.length > Math.max(1, height))
+        return lines.slice(0, Math.max(1, height));
+    return lines;
+}

package/dist/dashboard/view.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Dashboard view-model: pure shaping of daemon data (status / inspect /
+ * durable events) into the cards every dashboard surface renders.
+ *
+ * Shared by `load-lock top` (src/cli/top.ts) and the OpenCode TUI plugin
+ * (src/adapters/opencode/tui.tsx) so both show exactly the same state and
+ * only differ in rendering. Everything here is pure and synchronous —
+ * "now" is always an explicit parameter, which makes countdowns testable.
+ */
+import type * as P from "../shared/protocol.js";
+/** Connection state of the dashboard's daemon feed. */
+export type FeedState = "connecting" | "live" | "reconnecting" | "down";
+export interface HolderCard {
+    requestId: string;
+    pool: string;
+    agent: string;
+    agentId: string;
+    reason: string;
+    weight: number;
+    phase: P.PermitPhase;
+    /** "claimed (must start)", "running (tracked)", "running (untracked)" */
+    phaseLabel: string;
+    pid?: number;
+    pgid?: number;
+    /** How long the permit has been held (now - claimedAt proxy). */
+    heldMs: number;
+    /** Only for phase "claimed": ms until the start deadline reclaims it. */
+    startDeadlineInMs?: number;
+    /** Only for phase "running_untracked": ms until the lease lapses. */
+    leaseDeadlineInMs?: number;
+}
+export interface OfferCard {
+    requestId: string;
+    pool: string;
+    agent: string;
+    agentId: string;
+    reason: string;
+    weight: number;
+    /** ms remaining in the claim window (can be slightly negative pre-event). */
+    claimInMs: number;
+    expiresAt: number;
+}
+export interface QueueCard {
+    requestId: string;
+    pool: string;
+    agent: string;
+    agentId: string;
+    reason: string;
+    weight: number;
+    position: number;
+    /** How long the request has been queued. */
+    waitMs: number;
+}
+export interface PausedCard {
+    requestId: string;
+    pool: string;
+    agent: string;
+    agentId: string;
+    reason: string;
+    weight: number;
+    /** How long it has been paused. */
+    pausedMs: number;
+}
+export interface PoolView {
+    pool: string;
+    capacity: number;
+    used: number;
+    heldWeight: number;
+    offeredWeight: number;
+    free: number;
+    utilization: number;
+    holders: HolderCard[];
+    offers: OfferCard[];
+    queue: QueueCard[];
+    paused: PausedCard[];
+}
+export interface EventLine {
+    id: number;
+    ts: number;
+    agoMs: number;
+    type: P.EventType;
+    pool?: string;
+    text: string;
+}
+export interface MachineView {
+    cpuModel?: string;
+    logicalCores: number;
+    effectiveCores: number;
+    cgroupVersion?: string;
+    cgroupCpuQuota?: number | null;
+    loadavg: [number, number, number];
+    loadPerEffectiveCore: number;
+    memTotalBytes: number;
+    memAvailableBytes: number;
+    memEffectiveLimitBytes: number;
+    loadPressure: "low" | "moderate" | "high";
+    memPressure: "low" | "moderate" | "high";
+    note: string;
+    suggestion?: string;
+}
+export interface DaemonView {
+    pid: number;
+    startedAt: number;
+    uptimeMs: number;
+    protocolVersion: number;
+    configVersion: number;
+}
+/** The complete render-ready snapshot of the machine-wide budget. */
+export interface DashboardView {
+    now: number;
+    state: FeedState;
+    /** False right after a daemon restart was detected (history was reset). */
+    daemonRestartNote?: string;
+    daemon: DaemonView | null;
+    pools: PoolView[];
+    events: EventLine[];
+    latestEventId: number;
+    machine: MachineView | null;
+    lastSyncAt: number;
+}
+/** Compact human duration: "412ms", "3s", "4m 12s", "2h 05m", "3d 4h". */
+export declare function fmtDuration(ms: number): string;
+/** Byte counts: "12.4Gi", "512Mi", "3.4Ki". */
+export declare function fmtBytes(bytes: number): string;
+/** Local clock time HH:MM:SS. */
+export declare function fmtClock(ts: number): string;
+/** One-line label for a permit phase. */
+export declare function phaseLabel(p: P.PermitPhase): string;
+/** Truncate with ellipsis, keeping the head (ids, reasons). */
+export declare function trunc(s: string, max: number): string;
+export declare function agentName(e: {
+    agentLabel?: string;
+    agentId: string;
+}): string;
+/** One-line human sentence for a daemon event (durable ids are kept). */
+export declare function eventText(ev: P.MachineEvent): string;
+export interface DashboardInputs {
+    status: P.StatusResult | null;
+    inspect: P.InspectResult | null;
+    /** Chronological (oldest first). The feed keeps the newest N. */
+    events: P.MachineEvent[];
+    latestEventId: number;
+    state: FeedState;
+    lastSyncAt: number;
+    daemonRestartNote?: string;
+    now: number;
+}
+export declare function buildDashboardView(inps: DashboardInputs): DashboardView;