@crouton-kit/crouter 0.3.14 → 0.3.16

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

@@ -0,0 +1,22 @@
+interface CommandUI {
+    select(title: string, options: string[]): Promise<string | undefined>;
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void;
+}
+interface CommandCtx {
+    mode: string;
+    ui: CommandUI;
+}
+interface PiLike {
+    registerCommand?(name: string, options: {
+        description?: string;
+        handler: (args: string, ctx: CommandCtx) => void | Promise<void>;
+    }): void;
+}
+/**
+ * Register the /resume-node command on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasResume(pi: PiLike): void;
+export default registerCanvasResume;

package/dist/pi-extensions/canvas-resume.js

@@ -0,0 +1,173 @@
+// canvas-resume.ts — pi extension registering the /resume-node canvas command.
+//
+//   /resume-node  — open a TREE-SHAPED picker over the WHOLE canvas (every root,
+//     INCLUDING DORMANT nodes: done / idle / dead / canceled) rendered with tree
+//     glyphs (├─ / └─) + a status tag + name + short id, then revive the chosen
+//     node by shelling `crtr node focus <id>` (fire-and-forget). Reviving dormant
+//     nodes is the entire point, so — unlike the BASE/GRAPH chrome and
+//     renderForest()'s live-only (active|idle) filter — this walks ALL roots
+//     and ALL statuses.
+//
+//   The name is literally `resume-node`, NOT `resume`, to avoid clashing with
+//   pi's built-in /resume.
+//
+// ⚠ DESYNC — why `crtr node focus` is the ONLY sanctioned open
+//   `crtr node focus <id>` routes through reviveNode() (src/core/runtime/
+//   revive.ts), the ONLY sanctioned launcher of `pi --session <file>`: it sets
+//   CRTR_NODE_ID + the `-e` canvas extensions and runs transition('revive').
+//   A RAW `pi --session <file>` has NEITHER → every canvas hook is inert: the
+//   stophook never records pi_pid / clears intent / marks done, no inbox-watcher
+//   wakes it, and transition('revive') never runs so the row stays dormant.
+//   Worst case (idle + intent=idle-release) the daemon can't see the raw pi (no
+//   pi_pid) and DOUBLE-SPAWNS a second pi on the same .jsonl, corrupting the
+//   conversation. A UI must therefore NEVER spawn `pi --session` directly — it
+//   opens nodes via `crtr node focus` / `crtr canvas revive`.
+//
+// INERT when CRTR_NODE_ID is absent (a plain pi session, not a canvas node).
+//
+// 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 (mirrors
+// canvas-nav.ts / canvas-commands.ts).
+import { execFile } from 'node:child_process';
+import { getNode, listNodes, subscriptionsOf, fullName } from '../core/canvas/index.js';
+// ---------------------------------------------------------------------------
+// Forest rendering — one line per node across the WHOLE canvas, with a parallel
+// ids[] array so the chosen line maps back to its node_id. Plain unicode glyphs
+// (no ANSI) so the line renders cleanly inside pi's select dialog.
+// ---------------------------------------------------------------------------
+const STATUS_GLYPH = {
+    active: '●',
+    idle: '○',
+    done: '✓',
+    dead: '✗',
+    canceled: '⊘',
+};
+function shortId(id) {
+    return id.slice(0, 8);
+}
+/** `<glyph> <status> <name> [<kind>/<mode>] (<shortid>)` — a status TAG + name
+ *  + short id, prefixed with the tree branch. Best-effort on a missing meta. */
+function nodeLabel(nodeId, branch) {
+    const node = getNode(nodeId);
+    if (node === null)
+        return `${branch}? <missing ${shortId(nodeId)}>`;
+    const glyph = STATUS_GLYPH[node.status] ?? '?';
+    return `${branch}${glyph} ${node.status} ${fullName(node)} [${node.kind}/${node.mode}] (${shortId(nodeId)})`;
+}
+/** Sort rank for roots — live first (active, then idle), dormant after. Keeps
+ *  the picker oriented while still listing every dormant root. */
+function statusRank(status) {
+    switch (status) {
+        case 'active': return 0;
+        case 'idle': return 1;
+        case 'done': return 2;
+        case 'canceled': return 3;
+        case 'dead': return 4;
+        default: return 5;
+    }
+}
+/** Recursively render the subscription subtree rooted at `nodeId` into the
+ *  parallel lines/ids arrays. Mirrors render.ts walkTree but keeps lines and
+ *  ids strictly 1:1 (a cycle back-ref still maps to its real node, so selecting
+ *  it just focuses that node — harmless). Cycle-safe via `visited`. */
+function walkSubtree(nodeId, indent, connector, visited, out) {
+    if (visited.has(nodeId)) {
+        out.lines.push(`${indent}${connector}↺ ${shortId(nodeId)} (cycle)`);
+        out.ids.push(nodeId);
+        return;
+    }
+    visited.add(nodeId);
+    out.lines.push(nodeLabel(nodeId, `${indent}${connector}`));
+    out.ids.push(nodeId);
+    const children = subscriptionsOf(nodeId);
+    // Root rows carry no connector; children of a last-child get clear space, of a
+    // mid-child a continued spine — exactly render.ts walkTree's prefix math.
+    const childIndent = indent + (connector === '' ? '' : connector === '└─ ' ? '   ' : '│  ');
+    for (let i = 0; i < children.length; i++) {
+        const isLast = i === children.length - 1;
+        walkSubtree(children[i].node_id, childIndent, isLast ? '└─ ' : '├─ ', visited, out);
+    }
+}
+/** The whole-canvas forest: EVERY root (parent === null, ANY status) and its
+ *  subtree, flattened to parallel label/id arrays. */
+function buildForest() {
+    const out = { lines: [], ids: [] };
+    const visited = new Set();
+    const roots = listNodes()
+        .filter((n) => n.parent === null)
+        .sort((a, b) => statusRank(a.status) - statusRank(b.status));
+    for (const r of roots)
+        walkSubtree(r.node_id, '', '', visited, out);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the /resume-node command on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export function registerCanvasResume(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    if (typeof pi.registerCommand !== 'function')
+        return;
+    pi.registerCommand('resume-node', {
+        description: 'Resume a node — pick from the whole canvas (incl. dormant) and revive it',
+        handler: async (_args, ctx) => {
+            // select() is a terminal-only dialog — guard the run mode before it.
+            if (ctx.mode !== 'tui') {
+                try {
+                    ctx.ui.notify('/resume-node needs the interactive TUI', 'warning');
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            let forest;
+            try {
+                forest = buildForest();
+            }
+            catch {
+                try {
+                    ctx.ui.notify('resume: could not read the canvas', 'error');
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            if (forest.lines.length === 0) {
+                try {
+                    ctx.ui.notify('No nodes on the canvas to resume.', 'info');
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            const choice = await ctx.ui.select('Resume which node?', forest.lines);
+            if (choice === undefined)
+                return; // cancelled / timed out
+            const idx = forest.lines.indexOf(choice);
+            const targetId = idx >= 0 ? forest.ids[idx] : undefined;
+            if (targetId === undefined)
+                return;
+            // The ONLY sync-safe open: route through reviveNode via `crtr node focus`.
+            // Fire-and-forget — `node focus` swaps the target into THIS pane, replacing
+            // the current pi, so the callback may never run (best-effort notify only).
+            try {
+                execFile('crtr', ['node', 'focus', targetId], (err) => {
+                    if (err != null) {
+                        try {
+                            ctx.ui.notify(`resume failed: focus ${shortId(targetId)}`, 'error');
+                        }
+                        catch { /* best-effort */ }
+                    }
+                });
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    });
+}
+export default registerCanvasResume;

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

@@ -5,6 +5,22 @@ interface PiLike {
         deliverAs?: 'steer' | 'followUp';
     }) => void;
 }
+/** The nudge text for a crossed band, specialized to the node's (mode,
+ *  lifecycle) persona + how far along the escalation it is.
+ *
+ *  - orchestrator (terminal OR resident): checkpoint its roadmap and yield
+ *    (gently → firmly → pushy). It has a context/roadmap.md to yield against.
+ *  - resident/base (root conversation): never promoted, so NO roadmap exists —
+ *    steer it to PROMOTE if the chat is growing into a multi-phase job (which
+ *    seeds a roadmap), else wrap up / start fresh. Never points at roadmap.md or
+ *    a bare `node yield`, which for a roadmap-less root just drops context.
+ *  - terminal/base (worker): PROMOTE itself — become an orchestrator — when
+ *    work remains, with an "ignore if nearly done, finish with push final" once
+ *    it's deeper in.
+ *
+ *  At/past 185k every persona goes PUSHY: the context is long enough that
+ *  drifting further risks an overflow. */
+export declare function steerNote(at: number, lifecycle: string, mode: string): string;
 /**
  * Register the canvas turn_end / agent_end handlers on `pi`.
  *