@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/daemon/crtrd.js

@@ -0,0 +1,200 @@
+// crtrd — the thin supervisor daemon. One instance per canvas.
+//
+// Sole responsibility: supervise tmux window exit and revive nodes. No
+// orchestration logic lives here. The daemon is a process-lifecycle watcher.
+//
+// Model
+//   • Poll every intervalMs (default 2000ms).
+//   • For each active|idle node: check whether its tmux window is still alive.
+//   • Window alive → healthy, skip.
+//   • Window gone + intent==='refresh' → fresh respawn (node asked to yield).
+//   • Window gone + intent==='idle-release' → node freed its own pane while
+//     dormant; clear the stale window ref and revive (resume) when its inbox
+//     gains an unseen entry.
+//   • Window gone + any other intent → crash: mark 'dead'.
+//   • Nodes with no tmux placement (inline roots) are skipped.
+//
+// Single-instance guarantee
+//   A PID file at crtrHome()/crtrd.pid prevents double-runs. On start, if the
+//   file exists and the recorded pid is alive, we refuse to start (exit 0).
+//   On stop (SIGINT/SIGTERM/exit) we remove the file.
+import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { crtrHome } from '../core/canvas/paths.js';
+import { listNodes, setStatus, getNode, updateNode, } from '../core/canvas/index.js';
+import { windowAlive } from '../core/runtime/tmux.js';
+import { reviveNode } from '../core/runtime/revive.js';
+import { readInboxSince, readCursor } from '../core/feed/inbox.js';
+const DEFAULT_INTERVAL_MS = 2000;
+// ---------------------------------------------------------------------------
+// Pidfile
+// ---------------------------------------------------------------------------
+function pidfilePath() {
+    return join(crtrHome(), 'crtrd.pid');
+}
+function writePidfile() {
+    // Ensure the canvas home exists before writing.
+    mkdirSync(crtrHome(), { recursive: true });
+    writeFileSync(pidfilePath(), String(process.pid), 'utf8');
+}
+function removePidfile() {
+    try {
+        rmSync(pidfilePath());
+    }
+    catch {
+        // Already gone — nothing to do.
+    }
+}
+/** Read the pid stored in the pidfile, or null if absent / malformed. */
+export function readPidfile() {
+    const p = pidfilePath();
+    if (!existsSync(p))
+        return null;
+    const raw = readFileSync(p, 'utf8').trim();
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** True if a process with `pid` is currently alive (signal-0 probe). */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a crtrd process is already running (pidfile exists + pid alive). */
+export function isDaemonRunning() {
+    const pid = readPidfile();
+    return pid !== null && isPidAlive(pid);
+}
+// ---------------------------------------------------------------------------
+// Supervisor tick
+// ---------------------------------------------------------------------------
+async function superviseTick() {
+    let rows;
+    try {
+        rows = listNodes({ status: ['active', 'idle'] });
+    }
+    catch (err) {
+        process.stderr.write(`[crtrd] listNodes error: ${err.message}\n`);
+        return;
+    }
+    for (const row of rows) {
+        try {
+            // listNodes returns the lightweight NodeRow; we need the full NodeMeta
+            // for tmux_session, window, intent, and pi_session_id.
+            const meta = getNode(row.node_id);
+            if (meta === null)
+                continue; // vanished between list and get
+            // Nodes without tmux placement are inline roots — not daemon-managed.
+            if (meta.tmux_session == null || meta.window == null)
+                continue;
+            if (windowAlive(meta.tmux_session, meta.window))
+                continue; // healthy
+            // Window is gone. Branch on why.
+            if (meta.intent === 'refresh') {
+                // The node set intent=refresh before stopping — a clean yield. Respawn
+                // fresh so it re-reads its roadmap/context dir.
+                process.stderr.write(`[crtrd] revive ${row.node_id} (refresh-yield)\n`);
+                reviveNode(row.node_id, { resume: false });
+            }
+            else if (meta.intent === 'idle-release') {
+                // The node freed its own window on purpose while dormant. Drop the stale
+                // window ref and keep it 'idle'; the inbox-poll pass below revives it
+                // (resume) the moment a subscribed worker delivers.
+                updateNode(row.node_id, { window: null });
+            }
+            else {
+                // Window vanished without the node completing or refreshing — a crash.
+                process.stderr.write(`[crtrd] dead ${row.node_id} (window gone, intent=${String(meta.intent)})\n`);
+                setStatus(row.node_id, 'dead');
+            }
+        }
+        catch (err) {
+            // One bad node must never kill the loop.
+            process.stderr.write(`[crtrd] error supervising ${row.node_id}: ${err.message}\n`);
+        }
+    }
+    // Second pass: revive idle-released nodes whose inbox has unseen entries.
+    // The in-process inbox-watcher dies with pi, so the daemon owns wake-on-message
+    // for dormant nodes. readCursor is the cursor the watcher persisted before
+    // exit; any entry past it is undelivered work — resume the node to handle it.
+    for (const row of rows) {
+        try {
+            const meta = getNode(row.node_id);
+            if (meta === null)
+                continue;
+            if (meta.status !== 'idle' || meta.intent !== 'idle-release')
+                continue;
+            // If a window is somehow alive, the in-process watcher owns delivery.
+            if (meta.window != null && windowAlive(meta.tmux_session ?? '', meta.window)) {
+                continue;
+            }
+            const entries = readInboxSince(row.node_id, readCursor(row.node_id));
+            if (entries.length > 0) {
+                process.stderr.write(`[crtrd] revive ${row.node_id} (idle-release, inbox)\n`);
+                reviveNode(row.node_id, { resume: true });
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[crtrd] error polling inbox ${row.node_id}: ${err.message}\n`);
+        }
+    }
+}
+/** Start the supervisor loop.
+ *
+ *  If a live crtrd is already running (pidfile + pid alive), exits immediately
+ *  (exit 0 — idempotent, not an error). Otherwise, writes the pidfile, sets up
+ *  signal handlers, and enters the poll loop.
+ *
+ *  Returns a teardown callback that stops the loop and removes the pidfile.
+ *  (Mainly useful for tests; in production the daemon runs until signaled.) */
+export function runDaemon(opts = {}) {
+    if (isDaemonRunning()) {
+        const pid = readPidfile();
+        process.stderr.write(`[crtrd] already running (pid ${pid ?? '?'})\n`);
+        process.exit(0);
+    }
+    const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+    writePidfile();
+    process.stderr.write(`[crtrd] started (pid ${process.pid}, interval ${interval}ms)\n`);
+    let running = true;
+    // Cleanup — idempotent.
+    const cleanup = () => {
+        removePidfile();
+    };
+    process.on('SIGINT', () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.on('exit', () => {
+        cleanup();
+    });
+    // Recursive setTimeout keeps ticks sequential and avoids overlap on slow
+    // canvases (a timer that fires while a prior tick is awaiting is dropped).
+    const scheduleTick = () => {
+        if (!running)
+            return;
+        superviseTick()
+            .catch((err) => {
+            process.stderr.write(`[crtrd] tick error: ${err.message}\n`);
+        })
+            .finally(() => {
+            if (running)
+                setTimeout(scheduleTick, interval);
+        });
+    };
+    const initialTimer = setTimeout(scheduleTick, interval);
+    return () => {
+        running = false;
+        clearTimeout(initialTimer);
+        cleanup();
+    };
+}
+export default runDaemon;

package/dist/daemon/manage.d.ts

@@ -0,0 +1,17 @@
+export interface SpawnDaemonResult {
+    /** True when a new daemon process was spawned. */
+    started: boolean;
+    /** PID of the newly spawned process, if started. */
+    pid?: number;
+    /** PID of the already-running daemon, if it was already up. */
+    existing_pid?: number;
+}
+/** Spawn crtrd detached. Returns immediately; the child outlives this process.
+ *
+ *  If the daemon is already running, returns {started:false, existing_pid}.
+ *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
+export declare function spawnDaemon(): SpawnDaemonResult;
+/** Start the daemon if it is not already running. No-op if already up.
+ *  Silently swallows spawn errors (the canvas still works without the daemon;
+ *  nodes just won't be auto-revived). */
+export declare function ensureDaemon(): void;

package/dist/daemon/manage.js

@@ -0,0 +1,57 @@
+// Daemon management helpers — importable without the full command tree.
+//
+// spawnDaemon() is the low-level spawn call shared by `crtr canvas daemon start` and
+// ensureDaemon(). ensureDaemon() is the silent "start if not running" front-
+// door helper called by the canvas runtime before spawning child nodes.
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync } from 'node:fs';
+import { crtrHome } from '../core/canvas/paths.js';
+import { isDaemonRunning, readPidfile } from './crtrd.js';
+// ---------------------------------------------------------------------------
+// Entry point resolution
+// ---------------------------------------------------------------------------
+/** Resolve the absolute path to the crtrd-cli entry point.
+ *
+ *  At runtime this file is dist/daemon/manage.js; the entry lives at
+ *  dist/daemon/crtrd-cli.js (sibling in the same directory). */
+function resolveCrtrdEntry() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, 'crtrd-cli.js');
+}
+/** Spawn crtrd detached. Returns immediately; the child outlives this process.
+ *
+ *  If the daemon is already running, returns {started:false, existing_pid}.
+ *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
+export function spawnDaemon() {
+    if (isDaemonRunning()) {
+        return { started: false, existing_pid: readPidfile() ?? undefined };
+    }
+    // Ensure the canvas home directory exists so the daemon can write its pidfile.
+    mkdirSync(crtrHome(), { recursive: true });
+    const entry = resolveCrtrdEntry();
+    const child = spawn(process.execPath, [entry], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    const pid = child.pid;
+    child.unref();
+    return { started: true, pid };
+}
+// ---------------------------------------------------------------------------
+// ensureDaemon — fire-and-forget front-door helper
+// ---------------------------------------------------------------------------
+/** Start the daemon if it is not already running. No-op if already up.
+ *  Silently swallows spawn errors (the canvas still works without the daemon;
+ *  nodes just won't be auto-revived). */
+export function ensureDaemon() {
+    try {
+        if (!isDaemonRunning())
+            spawnDaemon();
+    }
+    catch {
+        // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
+        // pre-build) must not break the calling command.
+    }
+}

package/dist/pi-extensions/canvas-inbox-watcher.d.ts

@@ -0,0 +1,16 @@
+type PiEvents = 'session_start' | 'turn_end' | 'agent_start' | 'agent_end' | 'session_shutdown';
+interface PiLike {
+    on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
+    sendUserMessage: (content: string, options?: {
+        deliverAs?: 'steer' | 'followUp';
+    }) => void;
+}
+/**
+ * Register the canvas inbox watcher on `pi`.
+ *
+ * CRTR_NODE_ID is re-read each tick so late-injected env (edge case) is
+ * handled gracefully. Returns a disposer for testability; pi ignores it —
+ * the module-level liveTimer guard is the actual stacking prevention.
+ */
+export declare function registerCanvasInboxWatcher(pi: PiLike): () => void;
+export default registerCanvasInboxWatcher;

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -0,0 +1,229 @@
+// canvas-inbox-watcher.ts — pi extension for pi-native canvas agent nodes.
+//
+// Loaded into every canvas node's pi process via the node's launch.extensions
+// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
+//
+// The canvas model: each node is a long-lived resident that alternates between
+// "working" (pi actively generating) and "dormant" (pi idle, waiting for a
+// subscribed worker to push a report). This watcher bridges the dormant→working
+// transition automatically: it polls the node's inbox.jsonl every 800ms and,
+// when new entries arrive, coalesces them into a single digest and injects it as
+// a pi user message — waking the node to react.
+//
+// Key differences from the legacy agent-inbox-watcher:
+//   • Target resolution is trivial. CRTR_NODE_ID IS the node; its inbox lives at
+//     nodes/<CRTR_NODE_ID>/inbox.jsonl. No session-dir scanning, no pi_session_id
+//     matching, no spawned-vs-top-level branching.
+//   • readInboxSince / readCursor / writeCursor from the canvas inbox primitive
+//     replace the hand-rolled JSONL scanner and cursor-file helpers.
+//   • coalesce() renders the digest (pointer list, not job-status prose).
+//   • No crtr root-init or spawnSync bootstrap — the canvas runtime wires up the
+//     node before launching pi; CRTR_NODE_ID is always present when we activate.
+//   • Deliver-as decision is driven by InboxEntry.tier (and kind): critical →
+//     true preempt (ctx.abort() the live turn, redeliver next tick), urgent →
+//     steer at the turn boundary, normal|deferred → followUp. A finished node
+//     (kind 'final') ALSO steers — a completion the subscriber may be blocked on
+//     must interrupt the current turn, not wait behind it as a follow-up.
+//
+// Double-notify prevention (copied from legacy watcher):
+//   A module-level `liveTimer` ensures that a /reload re-init clears the previous
+//   setInterval before starting a new one — exactly one watcher is live at a time.
+//
+// Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
+// crouter's own tsc build without a dep on the pi packages.
+import { readInboxSince, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
+// ---------------------------------------------------------------------------
+// Module-level timer — prevents stacking on /reload (the double-notify bug).
+//
+// pi ignores an extension factory's returned disposer, so a /reload re-enters
+// this module and would ADD a new setInterval on top of any running one.
+// N reloads → N live watchers, each with its own in-memory cursor → N deliveries
+// of the same entry. Clearing the prior timer on each re-init ensures exactly
+// one watcher is live. Pattern copied verbatim from agent-inbox-watcher.ts.
+// ---------------------------------------------------------------------------
+let liveTimer;
+const TICK_MS = 800; // polling cadence
+const DEBOUNCE_MS = 1000; // flush once the burst has been quiet for this long
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the canvas inbox watcher on `pi`.
+ *
+ * CRTR_NODE_ID is re-read each tick so late-injected env (edge case) is
+ * handled gracefully. Returns a disposer for testability; pi ignores it —
+ * the module-level liveTimer guard is the actual stacking prevention.
+ */
+export function registerCanvasInboxWatcher(pi) {
+    // Capture the latest event context so isIdle() is readable inside the timer
+    // callback, which has no ctx of its own.
+    let lastCtx;
+    let streaming = false;
+    const captureCtx = (_event, ctx) => {
+        if (ctx !== undefined)
+            lastCtx = ctx;
+    };
+    pi.on('session_start', captureCtx);
+    pi.on('turn_end', captureCtx);
+    pi.on('agent_start', (_e, ctx) => {
+        captureCtx(_e, ctx);
+        streaming = true;
+    });
+    pi.on('agent_end', (_e, ctx) => {
+        captureCtx(_e, ctx);
+        streaming = false;
+    });
+    /**
+     * True when pi is not currently streaming a response.
+     * When idle, sendUserMessage triggers a new turn immediately.
+     * When streaming, steer (interrupt) on urgency or a finished node, else follow up.
+     */
+    const isIdle = () => {
+        try {
+            if (typeof lastCtx?.isIdle === 'function')
+                return lastCtx.isIdle() === true;
+        }
+        catch {
+            /* fall through to the streaming flag */
+        }
+        return !streaming;
+    };
+    // ---------------------------------------------------------------------------
+    // Debounce state
+    // ---------------------------------------------------------------------------
+    /** Entries received since the last flush — coalesced into one message. */
+    let buffer = [];
+    /** Epoch-ms of the most recent entry arrival. Used to detect burst-quiet. */
+    let lastArrival = 0;
+    /**
+     * Durable cursor — ISO 8601 of the last entry we've consumed.
+     * Seeded from the persisted cursor file on first resolution; undefined means
+     * "read from the beginning" (no prior cursor → process all existing entries).
+     * NOT reset to `now` on first tick: that would silently drop entries that
+     * arrived between node creation and watcher startup (the startup race).
+     */
+    let cursor;
+    let seeded = false;
+    // ---------------------------------------------------------------------------
+    // Flush: deliver the buffered entries as a single pi user message.
+    // ---------------------------------------------------------------------------
+    const flush = () => {
+        if (buffer.length === 0)
+            return;
+        // Deferred-tier entries must never WAKE an idle node — by contract they ride
+        // the next natural turn, never interrupt. If everything buffered is deferred
+        // and the node is idle, hold them (leave buffered, cheap re-check each tick)
+        // and return without delivering. They flush the moment the node is next
+        // streaming, or a higher-tier entry joins the batch (every() turns false).
+        if (isIdle() && buffer.every((e) => e.tier === 'deferred'))
+            return;
+        const batch = buffer;
+        buffer = [];
+        const digest = coalesce(batch);
+        // Tier (and kind) drive delivery mode. Critical is a TRUE preempt; urgent —
+        // and a finished node (kind 'final') — steers at the turn boundary;
+        // normal/deferred ride the next turn (followUp). (A purely-deferred idle
+        // batch was already held above and never reaches here.) A completion a
+        // subscriber is likely blocked on must not drain as a follow-up, so 'final'
+        // steers exactly like 'urgent'.
+        const anyCritical = batch.some((e) => e.tier === 'critical');
+        const steerMidStream = anyCritical || batch.some((e) => e.tier === 'urgent' || e.kind === 'final');
+        try {
+            if (isIdle()) {
+                // Idle → trigger a new turn immediately (sendUserMessage always triggers).
+                pi.sendUserMessage(digest);
+            }
+            else if (anyCritical) {
+                // Critical mid-stream → TRUE preempt. ctx.abort() cancels the live LLM
+                // stream right now (stopReason becomes 'aborted'; the stophook stays alive
+                // on that). We then re-buffer and let the next tick deliver via the idle
+                // path — by then the turn has torn down and sendUserMessage starts a fresh
+                // turn. Relying on the proven idle path (not steer-after-abort semantics)
+                // keeps this robust; if abort hasn't settled by the next tick we simply
+                // abort again and retry — idempotent and self-healing.
+                try {
+                    lastCtx?.abort?.();
+                }
+                catch { /* abort is best-effort */ }
+                buffer = batch.concat(buffer);
+            }
+            else {
+                // Mid-stream → steer on urgency or a finished node, else enqueue for the
+                // turn after this one.
+                pi.sendUserMessage(digest, { deliverAs: steerMidStream ? 'steer' : 'followUp' });
+            }
+        }
+        catch {
+            // Re-queue on delivery failure so a transient error doesn't silently drop
+            // inbox entries. They will be retried on the next flush.
+            buffer = batch.concat(buffer);
+        }
+    };
+    // ---------------------------------------------------------------------------
+    // Tick: poll the node's inbox and buffer new arrivals.
+    // ---------------------------------------------------------------------------
+    const tick = () => {
+        try {
+            // Re-read env each tick: CRTR_NODE_ID could theoretically be set after the
+            // extension factory runs (e.g. the runtime injects it just before the first
+            // turn). In practice it is always present before turn_end fires, but the
+            // check is cheap and keeps the watcher robust.
+            const nodeId = process.env['CRTR_NODE_ID'];
+            if (nodeId === undefined || nodeId.trim() === '')
+                return;
+            // Seed the cursor once, on the first tick that resolves a nodeId.
+            // readCursor returns undefined when no cursor file exists → readInboxSince
+            // with undefined returns ALL entries (no truncation to `now`).
+            if (!seeded) {
+                cursor = readCursor(nodeId);
+                seeded = true;
+            }
+            const newEntries = readInboxSince(nodeId, cursor);
+            if (newEntries.length > 0) {
+                // Advance and persist the cursor BEFORE buffering, so a crash after this
+                // point loses at most one coalesced message rather than re-injecting
+                // already-delivered entries on restart (exactly-once over restart contract).
+                const latest = newEntries.reduce((a, b) => (a.ts > b.ts ? a : b));
+                cursor = latest.ts;
+                writeCursor(nodeId, cursor);
+                buffer.push(...newEntries);
+                lastArrival = Date.now();
+            }
+            // Flush only once the burst has settled (no new entry within DEBOUNCE_MS)
+            // so near-simultaneous pushes from multiple workers arrive as one message.
+            if (buffer.length > 0 && Date.now() - lastArrival >= DEBOUNCE_MS) {
+                flush();
+            }
+        }
+        catch {
+            /* watcher is best-effort; a tick must never crash the host session */
+        }
+    };
+    // ---------------------------------------------------------------------------
+    // Timer management — clear any leftover timer from a prior /reload.
+    // ---------------------------------------------------------------------------
+    if (liveTimer !== undefined)
+        clearInterval(liveTimer);
+    const timer = setInterval(tick, TICK_MS);
+    // unref() so the watcher doesn't keep the Node process alive when everything
+    // else has finished (matches legacy watcher behaviour).
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    liveTimer = timer;
+    // pi DOES fire session_shutdown — use it as the authoritative teardown so a
+    // re-init (e.g. /reload) never discovers a live sibling timer.
+    pi.on('session_shutdown', () => {
+        clearInterval(timer);
+        if (liveTimer === timer)
+            liveTimer = undefined;
+    });
+    // Disposer: returned for testability + explicit teardown in test harnesses.
+    // pi ignores the factory return value, so the module-level guard above is what
+    // actually prevents stacking in production.
+    return () => {
+        clearInterval(timer);
+        if (liveTimer === timer)
+            liveTimer = undefined;
+    };
+}
+export default registerCanvasInboxWatcher;

package/dist/pi-extensions/canvas-nav.d.ts

@@ -0,0 +1,32 @@
+type PiEvents = 'session_start' | 'turn_end' | 'session_shutdown';
+interface ExtensionWidgetOptions {
+    /** Where the widget is rendered. "aboveEditor" | "belowEditor" */
+    placement?: 'aboveEditor' | 'belowEditor';
+}
+interface UIContext {
+    setWidget(key: string, content: string[] | undefined, options?: ExtensionWidgetOptions): void;
+    /** Raw key tap that fires BEFORE the editor. Return {consume:true} to swallow
+     *  the key (so e.g. UP doesn't trigger pi's history recall). Returns unsub. */
+    onTerminalInput?(handler: (data: string) => {
+        consume?: boolean;
+        data?: string;
+    } | undefined): () => void;
+    /** Current editor buffer text — used to only hijack keys on an empty editor. */
+    getEditorText?(): string;
+    /** Transient toast, used to report a failed focus. */
+    notify?(message: string, type?: 'info' | 'warning' | 'error'): void;
+}
+interface ExtensionCtx {
+    ui: UIContext;
+}
+interface PiLike {
+    on(event: PiEvents, handler: (event: any, ctx: ExtensionCtx) => void | Promise<void>): void;
+}
+/**
+ * Register the canvas nav chrome on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasNav(pi: PiLike): void;
+export default registerCanvasNav;