@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/core/runtime/spawn.js

@@ -0,0 +1,123 @@
+// The spawn orchestration — the one place that turns "I want a node here" into
+// a running pi process on the canvas. Composes canvas (birth + spine), persona
+// (resolve), launch (pi argv), and tmux (placement).
+//
+//   bootRoot   — a user-opened entry point (bare `crtr`).
+//                Resident. Runs pi in the foreground (inline) or its own session.
+//   spawnChild — a background worker spawned by a live node (`crtr node new`).
+//                Terminal. Opens a non-focus-stealing window under the root.
+import { spawnSync } from 'node:child_process';
+import { FRONT_DOOR_ENV } from './front-door.js';
+import { spawnNode, currentNodeContext } from './nodes.js';
+import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { writeGoal } from './kickoff.js';
+import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, installMenuBinding, } from './tmux.js';
+import { updateNode, getNode } from '../canvas/index.js';
+import { ensureDaemon } from '../../daemon/manage.js';
+/** Create a root node and bring up its pi. Returns the node; for 'inline' this
+ *  only returns after pi exits (it took over the terminal). */
+export function bootRoot(opts) {
+    // The thin supervisor must be up before any node exists, so a refresh-yield
+    // or crash can be reaped/revived. Idempotent.
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    const kind = opts.kind ?? 'general';
+    // A born-resident root starts in base mode; it earns the orchestrator persona
+    // the first time it delegates (or on promotion). Resident lifecycle either way.
+    const { launch } = buildLaunchSpec(kind, 'base');
+    const meta = spawnNode({
+        kind,
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: opts.cwd,
+        name: opts.name ?? kind,
+        parent: null,
+        launch,
+    });
+    // Persist the spawning prompt as the goal so a fresh revive can re-read its
+    // mandate (bare `crtr` has none — writeGoal no-ops on empty).
+    if (opts.prompt !== undefined)
+        writeGoal(meta.node_id, opts.prompt);
+    // Every node window — root or child — lives in the one shared session.
+    const session = nodeSession();
+    ensureSession(session, opts.cwd);
+    // Make the Alt+C action menu live on this server (idempotent, in-tmux only).
+    if (inTmux()) {
+        try {
+            installMenuBinding();
+        }
+        catch { /* best-effort */ }
+    }
+    if (opts.placement === 'session') {
+        updateNode(meta.node_id, { tmux_session: session });
+        const withSession = getNode(meta.node_id);
+        const inv = buildPiArgv(withSession, { prompt: opts.prompt });
+        const env = { ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
+        const win = openNodeWindow({
+            session,
+            name: meta.name,
+            cwd: opts.cwd,
+            env,
+            command: piCommand(inv.argv),
+        });
+        updateNode(meta.node_id, { window: win });
+        return getNode(meta.node_id);
+    }
+    // inline: the root's pi takes over THIS terminal, so its own window stays
+    // where the user is (its tmux_session tracks that real pane so supervision
+    // sees it alive). But its children spawn into the shared global session via
+    // CRTR_ROOT_SESSION — they never clutter the user's working session.
+    const here = currentTmux();
+    const adopted = here?.session ?? session;
+    updateNode(meta.node_id, { tmux_session: adopted, window: here?.window ?? null });
+    const withSession = getNode(meta.node_id);
+    const inv = buildPiArgv(withSession, { prompt: opts.prompt });
+    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: session, [FRONT_DOOR_ENV]: '1' };
+    const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
+    process.exit(r.status ?? 0);
+}
+/** Spawn a terminal worker as a background window under the root session.
+ *  The parent auto-subscribes (active) to it via spawnNode. */
+export function spawnChild(opts) {
+    try {
+        ensureDaemon();
+    }
+    catch { /* daemon is best-effort */ }
+    const ctx = currentNodeContext();
+    const parent = opts.parent ?? ctx.nodeId;
+    if (parent === null || parent === undefined) {
+        throw new Error('spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent');
+    }
+    const mode = opts.mode ?? 'base';
+    const { launch } = buildLaunchSpec(opts.kind, mode);
+    const meta = spawnNode({
+        kind: opts.kind,
+        mode,
+        lifecycle: 'terminal',
+        cwd: opts.cwd,
+        name: opts.name ?? opts.kind,
+        parent,
+        launch,
+    });
+    // Persist the task as the child's goal for a fresh revive to re-read.
+    writeGoal(meta.node_id, opts.prompt);
+    // Children always land in the shared global session: inherited from the
+    // parent's CRTR_ROOT_SESSION, else the default node session.
+    let session = process.env['CRTR_ROOT_SESSION'];
+    if (session === undefined || session === '')
+        session = nodeSession();
+    ensureSession(session, opts.cwd);
+    const inv = buildPiArgv(meta, { prompt: opts.prompt });
+    const env = { ...inv.env, CRTR_ROOT_SESSION: session };
+    const window = openNodeWindow({
+        session,
+        name: meta.name,
+        cwd: opts.cwd,
+        env,
+        command: piCommand(inv.argv),
+    });
+    const saved = updateNode(meta.node_id, { tmux_session: session, window });
+    return { node: saved, window, session };
+}

package/dist/core/runtime/stop-guard.d.ts

@@ -0,0 +1,18 @@
+export interface StopSignals {
+    /** Did the node call `push --final` (finish) this turn? */
+    pushedFinal: boolean;
+    /** Did the node call `crtr ask` (escalate to the human) this turn? */
+    askedHuman: boolean;
+}
+export type StopAction = {
+    action: 'allow';
+    reason: 'awaiting' | 'finished' | 'escalated' | 'attended';
+} | {
+    action: 'reprompt';
+    reason: 'stalled';
+    message: string;
+};
+export declare const STALL_REPROMPT: string;
+/** Decide what to do when a node stops. Pure given the canvas + this turn's
+ *  signals — the stophook supplies the signals and enacts the action. */
+export declare function evaluateStop(nodeId: string, signals: StopSignals): StopAction;

package/dist/core/runtime/stop-guard.js

@@ -0,0 +1,33 @@
+// The stop-guard — no stalled agents.
+//
+// Every time a node's pi process stops, we ask one question: is this node
+// *legitimately waiting*? A node is legitimately waiting iff it holds an ACTIVE
+// subscription to a node that's still live (active|idle) — something that can
+// actually wake it. (A passive sub won't wake you, so it doesn't count.)
+//
+//   • waiting        → stopping is correct; it's a dormant orchestrator awaiting
+//                      its workers. Let it sleep; a child's push wakes it.
+//   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
+//                      Also fine.
+//   • otherwise      → it has nothing live to wait for and hasn't resolved.
+//                      Re-prompt it to finish or escalate. Stalls are impossible.
+import { hasActiveLiveSubscription, getNode } from '../canvas/index.js';
+export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
+    'Run `crtr push final "<result>"` if the work is done, or `crtr human ask` if you are blocked or need the user.';
+/** Decide what to do when a node stops. Pure given the canvas + this turn's
+ *  signals — the stophook supplies the signals and enacts the action. */
+export function evaluateStop(nodeId, signals) {
+    if (signals.pushedFinal)
+        return { action: 'allow', reason: 'finished' };
+    if (signals.askedHuman)
+        return { action: 'allow', reason: 'escalated' };
+    // A user-opened root (no parent) is human-attended: the human is its wake
+    // source, so stopping to await input is always legitimate — never nag it.
+    const node = getNode(nodeId);
+    if (node !== null && (node.parent === null || node.parent === undefined)) {
+        return { action: 'allow', reason: 'attended' };
+    }
+    if (hasActiveLiveSubscription(nodeId))
+        return { action: 'allow', reason: 'awaiting' };
+    return { action: 'reprompt', reason: 'stalled', message: STALL_REPROMPT };
+}

package/dist/core/runtime/tmux.d.ts

@@ -0,0 +1,107 @@
+/** POSIX single-quote escaping for one shell word. */
+export declare function shellQuote(s: string): string;
+export declare function inTmux(): boolean;
+/** The single, shared tmux session that ALL canvas node windows live in.
+ *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
+ *  child opens a window here rather than cluttering the user's own working
+ *  session — switch to it to browse the whole live graph, ignore it otherwise. */
+export declare function nodeSession(): string;
+export interface TmuxLocation {
+    session: string;
+    window: string;
+    pane: string;
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export declare function currentTmux(): TmuxLocation | null;
+export declare function sessionExists(name: string): boolean;
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export declare function ensureSession(name: string, cwd: string): void;
+export interface OpenWindowOpts {
+    session: string;
+    /** Window name (the node's display name). */
+    name: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the window (already a shell string). */
+    command: string;
+}
+/** Open a background window for a node and run `command` in it. `-d` keeps it
+ *  detached so it doesn't steal focus or become the current window. Returns the
+ *  new window id.
+ *
+ *  Target is `${session}:` (trailing colon = the session, no window index) plus
+ *  `-a` (insert after the current window) so tmux allocates the next free index.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "create window failed: index N in use" whenever the active window is not the
+ *  last one (common when base-index is 0 but the live window sits at index 1).
+ *  `-a` also keeps node windows off index 0, which is reserved for the optional
+ *  dashboard. */
+export declare function openNodeWindow(opts: OpenWindowOpts): string | null;
+/** Open a background window running a plain login shell (no pi) and return its
+ *  window + pane ids. Used by demote: the agent's pi is swapped OUT into this
+ *  window's slot and the shell is swapped INTO the caller's pane. `-a` keeps it
+ *  off index 0 (reserved for a dashboard), `-d` keeps it from stealing focus. */
+export declare function openShellWindow(opts: {
+    session: string;
+    name: string;
+    cwd: string;
+}): {
+    window: string;
+    pane: string;
+} | null;
+/** Bring a node's window forefront. Switches client across roots when needed. */
+export declare function focusWindow(session: string, window: string): boolean;
+/** Close a node's window (drop it from the UI). */
+export declare function closeWindow(window: string): boolean;
+/** The active pane id of a window. Node windows are single-pane, so this is the
+ *  node's pane. Returns null if the window is gone or tmux fails. */
+export declare function paneOfWindow(session: string, window: string): string | null;
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  are not, so the node→window mapping must be re-derived from the pane. Returns
+ *  null if the pane is gone or tmux fails. */
+export declare function windowOfPane(pane: string): string | null;
+/** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
+ *  caller's window active, so the target's pane appears where the caller is
+ *  rather than navigating the client off to the target's window. The caller's
+ *  old pane lives on in the target's former window — the move is reversible
+ *  (focusing back swaps it in again). Best-effort; never throws. */
+export declare function swapPaneInPlace(targetPane: string, callerPane: string): boolean;
+export interface RespawnPaneOpts {
+    /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
+    pane: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the pane (already a shell string). */
+    command: string;
+}
+/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
+ *  current process (e.g. a yielding pi) and starts `command` in the same pane
+ *  — the window/pane survives, so an interactive session is never dropped to a
+ *  shell and no window churns. Used by refresh-yield.
+ *
+ *  Spawned DETACHED (own process group, unref'd) so the request reaches the
+ *  tmux server even though killing the pane tears down the caller's own pi.
+ *  Returns true once the request was dispatched. */
+export declare function respawnPane(opts: RespawnPaneOpts): boolean;
+/** Turn a pi argv array into a single shell command string. */
+export declare function piCommand(argv: string[], binary?: string): string;
+/** List all window ids present in `session`. Returns [] if the session does
+ *  not exist or tmux fails for any reason. Each entry is the raw window id
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export declare function listWindowIds(session: string): string[];
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export declare function windowAlive(session: string | null | undefined, window: string | null | undefined): boolean;
+/** Activate a window within its session (same-session navigation). Equivalent
+ *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
+export declare function selectWindow(session: string, window: string): boolean;
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
+ *  responsible for following up with selectWindow to land on the right window. */
+export declare function switchClient(session: string): boolean;
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+export declare function installMenuBinding(): boolean;

package/dist/core/runtime/tmux.js

@@ -0,0 +1,244 @@
+// tmux placement — one window per active node.
+//
+//   session = a root        window = a node        window 0 = optional dashboard
+//
+// Background windows run but don't render — only the current window draws. That
+// is the "detached but switchable" model: nothing tiles, you never see a node's
+// UI unless you switch to it. Bring one forefront with select-window (within a
+// root) or switch-client + select-window (across roots). done/dead nodes close
+// their window; reviving opens a fresh one.
+import { spawn, spawnSync } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Shell quoting + tmux invocation
+// ---------------------------------------------------------------------------
+/** POSIX single-quote escaping for one shell word. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return {
+        ok: r.status === 0,
+        stdout: (r.stdout ?? '').trim(),
+        stderr: (r.stderr ?? '').trim(),
+    };
+}
+export function inTmux() {
+    return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
+}
+/** The single, shared tmux session that ALL canvas node windows live in.
+ *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
+ *  child opens a window here rather than cluttering the user's own working
+ *  session — switch to it to browse the whole live graph, ignore it otherwise. */
+export function nodeSession() {
+    const v = process.env['CRTR_NODE_SESSION'];
+    return v !== undefined && v !== '' ? v : 'crtr';
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export function currentTmux() {
+    if (!inTmux())
+        return null;
+    const r = tmux([
+        'display-message',
+        '-p',
+        '#{session_name}\t#{window_id}\t#{pane_id}',
+    ]);
+    if (!r.ok)
+        return null;
+    const [session, window, pane] = r.stdout.split('\t');
+    return { session, window, pane };
+}
+// ---------------------------------------------------------------------------
+// Sessions + windows
+// ---------------------------------------------------------------------------
+export function sessionExists(name) {
+    return tmux(['has-session', '-t', name]).ok;
+}
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export function ensureSession(name, cwd) {
+    if (sessionExists(name))
+        return;
+    tmux(['new-session', '-d', '-s', name, '-c', cwd]);
+}
+function envFlags(env) {
+    const out = [];
+    for (const [k, v] of Object.entries(env))
+        out.push('-e', `${k}=${v}`);
+    return out;
+}
+/** Open a background window for a node and run `command` in it. `-d` keeps it
+ *  detached so it doesn't steal focus or become the current window. Returns the
+ *  new window id.
+ *
+ *  Target is `${session}:` (trailing colon = the session, no window index) plus
+ *  `-a` (insert after the current window) so tmux allocates the next free index.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "create window failed: index N in use" whenever the active window is not the
+ *  last one (common when base-index is 0 but the live window sits at index 1).
+ *  `-a` also keeps node windows off index 0, which is reserved for the optional
+ *  dashboard. */
+export function openNodeWindow(opts) {
+    const r = tmux([
+        'new-window',
+        '-d',
+        '-a',
+        '-P',
+        '-F',
+        '#{window_id}',
+        '-t',
+        `${opts.session}:`,
+        '-n',
+        opts.name,
+        '-c',
+        opts.cwd,
+        ...envFlags(opts.env),
+        opts.command,
+    ]);
+    return r.ok ? r.stdout : null;
+}
+/** Open a background window running a plain login shell (no pi) and return its
+ *  window + pane ids. Used by demote: the agent's pi is swapped OUT into this
+ *  window's slot and the shell is swapped INTO the caller's pane. `-a` keeps it
+ *  off index 0 (reserved for a dashboard), `-d` keeps it from stealing focus. */
+export function openShellWindow(opts) {
+    const r = tmux([
+        'new-window', '-d', '-a', '-P',
+        '-F', '#{window_id}\t#{pane_id}',
+        '-t', `${opts.session}:`,
+        '-n', opts.name,
+        '-c', opts.cwd,
+    ]);
+    if (!r.ok)
+        return null;
+    const [window, pane] = r.stdout.split('\t');
+    if (window === undefined || pane === undefined)
+        return null;
+    return { window, pane };
+}
+/** Bring a node's window forefront. Switches client across roots when needed. */
+export function focusWindow(session, window) {
+    const here = currentTmux();
+    const sameRoot = here?.session === session;
+    if (!sameRoot) {
+        if (!tmux(['switch-client', '-t', session]).ok)
+            return false;
+    }
+    return tmux(['select-window', '-t', window]).ok;
+}
+/** Close a node's window (drop it from the UI). */
+export function closeWindow(window) {
+    return tmux(['kill-window', '-t', window]).ok;
+}
+/** The active pane id of a window. Node windows are single-pane, so this is the
+ *  node's pane. Returns null if the window is gone or tmux fails. */
+export function paneOfWindow(session, window) {
+    const r = tmux(['display-message', '-p', '-t', `${session}:${window}`, '#{pane_id}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  are not, so the node→window mapping must be re-derived from the pane. Returns
+ *  null if the pane is gone or tmux fails. */
+export function windowOfPane(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{window_id}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
+ *  caller's window active, so the target's pane appears where the caller is
+ *  rather than navigating the client off to the target's window. The caller's
+ *  old pane lives on in the target's former window — the move is reversible
+ *  (focusing back swaps it in again). Best-effort; never throws. */
+export function swapPaneInPlace(targetPane, callerPane) {
+    if (targetPane === callerPane)
+        return true;
+    return tmux(['swap-pane', '-d', '-s', targetPane, '-t', callerPane]).ok;
+}
+/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
+ *  current process (e.g. a yielding pi) and starts `command` in the same pane
+ *  — the window/pane survives, so an interactive session is never dropped to a
+ *  shell and no window churns. Used by refresh-yield.
+ *
+ *  Spawned DETACHED (own process group, unref'd) so the request reaches the
+ *  tmux server even though killing the pane tears down the caller's own pi.
+ *  Returns true once the request was dispatched. */
+export function respawnPane(opts) {
+    try {
+        const child = spawn('tmux', [
+            'respawn-pane',
+            '-k',
+            '-c',
+            opts.cwd,
+            ...envFlags(opts.env),
+            '-t',
+            opts.pane,
+            opts.command,
+        ], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// pi command assembly
+// ---------------------------------------------------------------------------
+/** Turn a pi argv array into a single shell command string. */
+export function piCommand(argv, binary = 'pi') {
+    return [binary, ...argv.map(shellQuote)].join(' ');
+}
+// ---------------------------------------------------------------------------
+// Window liveness helpers (used by the supervisor daemon)
+// ---------------------------------------------------------------------------
+/** List all window ids present in `session`. Returns [] if the session does
+ *  not exist or tmux fails for any reason. Each entry is the raw window id
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export function listWindowIds(session) {
+    const r = tmux(['list-windows', '-t', session, '-F', '#{window_id}']);
+    if (!r.ok || r.stdout === '')
+        return [];
+    return r.stdout.split('\n').filter((s) => s !== '');
+}
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export function windowAlive(session, window) {
+    if (session == null || window == null)
+        return false;
+    return listWindowIds(session).includes(window);
+}
+// ---------------------------------------------------------------------------
+// Focus helpers (used by the presence layer)
+// ---------------------------------------------------------------------------
+/** Activate a window within its session (same-session navigation). Equivalent
+ *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
+export function selectWindow(session, window) {
+    return tmux(['select-window', '-t', `${session}:${window}`]).ok;
+}
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
+ *  responsible for following up with selectWindow to land on the right window. */
+export function switchClient(session) {
+    return tmux(['switch-client', '-t', session]).ok;
+}
+// ---------------------------------------------------------------------------
+// Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
+// actions. Installed on the running server at root boot; idempotent (a re-bind
+// overwrites the previous one). Items shell out to `crtr`, passing the active
+// pane so an action targets the agent currently in front of you.
+// ---------------------------------------------------------------------------
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+export function installMenuBinding() {
+    const sess = nodeSession();
+    return tmux([
+        'bind-key', '-n', 'M-c', 'display-menu',
+        '-T', '#[align=centre] crtr ',
+        // Anchor to the top-right of the pane it was called from (tmux clamps it
+        // back on-screen) rather than centring on the whole terminal.
+        '-x', '#{pane_right}', '-y', '#{pane_top}',
+        'detach agent \u2192 background', 'd', `run-shell "crtr node demote --pane '#{pane_id}'"`,
+        'browse background agents', 'g', `switch-client -t ${sess}`,
+    ]).ok;
+}