@crouton-kit/crouter 0.3.13 → 0.3.14

package/dist/core/runtime/tmux.js

@@ -98,25 +98,6 @@ export function openNodeWindow(opts) {
     ]);
     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();
@@ -145,6 +126,17 @@ export function windowOfPane(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{window_id}']);
     return r.ok && r.stdout !== '' ? r.stdout : null;
 }
+/** The session + window a pane currently lives in. Used by demote to place the
+ *  recycled root's meta on the pane it respawns into. Null if tmux fails. */
+export function paneLocation(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{session_name}\t#{window_id}']);
+    if (!r.ok)
+        return null;
+    const [session, window] = r.stdout.split('\t');
+    if (session === undefined || session === '' || window === undefined || window === '')
+        return null;
+    return { session, window };
+}
 /** 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
@@ -232,13 +224,52 @@ export function switchClient(session) {
 /** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
 export function installMenuBinding() {
     const sess = nodeSession();
-    return tmux([
+    const title = ' crtr ';
+    const items = [
+        // Promote types `/promote` into the agent's pane rather than shelling out:
+        // the slash command delivers the orchestration guidance into the node's
+        // context, which a bare `run-shell` (output discarded) could not.
+        { name: 'promote to orchestrator', key: 'o', cmd: `send-keys -t '#{pane_id}' '/promote' Enter` },
+        { name: 'finish agent + recycle pane', key: 'd', cmd: `run-shell "crtr node demote --pane '#{pane_id}'"` },
+        { name: 'browse background agents', key: 'g', cmd: `switch-client -t ${sess}` },
+    ];
+    // tmux's -x sets the menu's LEFT edge. To sit the box INSIDE the pane's
+    // top-right corner, shift x left by the box width (longest line + tmux chrome:
+    // borders + padding + the right-aligned mnemonic-key column) via format math.
+    const boxW = Math.max(title.length, ...items.map((i) => i.name.length)) + 6;
+    // Fine-tune nudges off the pane's top-right corner: a hair further left and
+    // one row down so the box doesn't kiss the pane border.
+    const nudgeX = 1; // extra columns left
+    const nudgeY = 3; // rows down
+    const args = [
         '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}`,
+        '-T', `#[align=centre]${title}`,
+        '-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`,
+        '-y', `#{e|+:#{pane_top},${nudgeY}}`,
+    ];
+    for (const it of items)
+        args.push(it.name, it.key, it.cmd);
+    return tmux(args).ok;
+}
+// ---------------------------------------------------------------------------
+// Nav bindings — Alt+] / Alt+[ DFS-walk the canvas one window at a time. Each
+// key shells out to `crtr node cycle`, passing the active pane so the walk is
+// relative to the agent in front of you; cycle then swaps the next/prev node
+// into that pane (like `node focus`). Output is discarded so the keypress never
+// pops a results view. Installed at root boot alongside the Alt+C menu.
+// ---------------------------------------------------------------------------
+/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
+ *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
+ *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
+ */
+export function installNavBindings() {
+    const next = tmux([
+        'bind-key', '-n', 'M-]', 'run-shell',
+        `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    const prev = tmux([
+        'bind-key', '-n', 'M-[', 'run-shell',
+        `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
     ]).ok;
+    return next && prev;
 }

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

@@ -0,0 +1,34 @@
+interface AutocompleteItem {
+    value: string;
+    label?: string;
+}
+interface CommandUI {
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void;
+    setStatus(key: string, text: string | undefined): void;
+}
+interface CommandCtx {
+    ui: CommandUI;
+}
+interface CustomMessage {
+    customType: string;
+    content: string;
+    display?: boolean;
+}
+interface PiLike {
+    registerCommand(name: string, options: {
+        description?: string;
+        getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null;
+        handler: (args: string, ctx: CommandCtx) => Promise<void>;
+    }): void;
+    sendMessage(message: CustomMessage, options?: {
+        triggerTurn?: boolean;
+    }): void;
+}
+/**
+ * Register the canvas slash-commands on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasCommands(pi: PiLike): void;
+export default registerCanvasCommands;

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

@@ -0,0 +1,100 @@
+// canvas-commands.ts — pi extension registering canvas slash-commands on nodes.
+//
+//   /promote [kind]  — promote THIS node to a resident orchestrator. Runs
+//     `crtr node promote --json` for CRTR_NODE_ID (optionally specializing its
+//     kind), then injects the orchestration guidance the command returns into
+//     context and triggers a turn, so the node authors its roadmap immediately.
+//     This is the same mid-turn guidance dump the node would get by running the
+//     command itself by hand — surfaced as a one-keystroke affordance.
+//
+// The Alt+C tmux action menu's "promote to orchestrator" item (key `o`) simply
+// send-keys `/promote` into the active pane, so the menu and the slash command
+// share this one implementation.
+//
+// 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). The only crouter import is availableKinds, used to offer
+// `/promote <kind>` completions.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { availableKinds } from '../core/personas/index.js';
+const pexec = promisify(execFile);
+// Kinds for `/promote <kind>` completions — computed once (persona dirs rarely
+// change within a session), best-effort so a loader hiccup never breaks input.
+let cachedKinds = null;
+function kinds() {
+    if (cachedKinds === null) {
+        try {
+            cachedKinds = availableKinds();
+        }
+        catch {
+            cachedKinds = [];
+        }
+    }
+    return cachedKinds;
+}
+/**
+ * Register the canvas slash-commands on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export function registerCanvasCommands(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    pi.registerCommand('promote', {
+        description: 'Promote this node to a resident orchestrator — /promote, or /promote <kind> to specialize',
+        getArgumentCompletions: (prefix) => {
+            const items = kinds()
+                .filter((k) => k.startsWith(prefix))
+                .map((k) => ({ value: k, label: k }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const kind = args.trim().toLowerCase();
+            ctx.ui.setStatus('crtr-promote', kind ? `promoting → ${kind}…` : 'promoting…');
+            const argv = ['node', 'promote', '--json'];
+            if (kind !== '')
+                argv.push('--kind', kind);
+            // Run promote out-of-process. On a non-zero exit, crtr still prints the
+            // structured error to stdout, so prefer its `message` over the raw throw.
+            let result = null;
+            let errMsg = null;
+            try {
+                const { stdout } = await pexec('crtr', argv, { timeout: 15_000, maxBuffer: 4 * 1024 * 1024 });
+                result = JSON.parse(stdout);
+            }
+            catch (err) {
+                const e = err;
+                const stdout = typeof e.stdout === 'string' ? e.stdout : '';
+                try {
+                    const payload = JSON.parse(stdout);
+                    errMsg = typeof payload.message === 'string' ? payload.message : null;
+                }
+                catch {
+                    /* stdout wasn't JSON */
+                }
+                if (errMsg === null)
+                    errMsg = typeof e.message === 'string' ? e.message : String(err);
+            }
+            ctx.ui.setStatus('crtr-promote', '');
+            if (result === null) {
+                ctx.ui.notify(`promote failed: ${errMsg ?? 'unknown error'}`, 'error');
+                return;
+            }
+            const rmPath = (result.roadmap_path ?? '').trim();
+            ctx.ui.notify(`Promoted to ${result.kind ?? 'orchestrator'} orchestrator — authoring roadmap${rmPath !== '' ? ` (${rmPath})` : ''}.`, 'info');
+            // The guidance is operating instructions for the node, not the user.
+            // Inject it silently and trigger a turn so the node acts on it now —
+            // exactly what happens when the node runs `crtr node promote` by hand.
+            const guidance = (result.guidance ?? '').trim();
+            if (guidance === '')
+                return;
+            pi.sendMessage({ customType: 'crtr-promote', content: guidance, display: false }, { triggerTurn: true });
+        },
+    });
+}
+export default registerCanvasCommands;

package/dist/pi-extensions/canvas-goal-capture.d.ts

@@ -0,0 +1,18 @@
+interface InputEventLike {
+    type: 'input';
+    text: string;
+    images?: unknown[];
+    source: 'interactive' | 'rpc' | 'extension';
+}
+interface PiLike {
+    on: (event: 'input', handler: (event: InputEventLike, ctx: any) => void) => void;
+}
+/**
+ * Register the goal-capture handler on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: on the first interactive message of a goal-less node,
+ * persist it as the goal.
+ */
+export declare function registerCanvasGoalCapture(pi: PiLike): void;
+export default registerCanvasGoalCapture;

package/dist/pi-extensions/canvas-goal-capture.js

@@ -0,0 +1,53 @@
+// canvas-goal-capture.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).
+//
+// A node spawned with a prompt has its goal persisted at birth (writeGoal in
+// spawn.ts). A bare root (`crtr` with no prompt) starts goal-less — its mandate
+// only arrives when the human types their first message. This extension closes
+// that gap: on the FIRST interactive user message, if the node has no goal yet,
+// it persists that message as context/initial-prompt.md. Subsequent messages
+// never clobber it (captureGoalIfAbsent is guarded), and a fresh-revive kickoff
+// prompt is skipped via its sentinel so it can never be mistaken for a mandate.
+//
+// Pure observation — it writes the goal file as a side effect and always lets
+// the message through unchanged (returns nothing ⇒ continue). Registered before
+// canvas-passive-context so it reads the raw user text, not a backlog-prepended
+// transform.
+//
+// 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 { captureGoalIfAbsent, REVIVE_KICKOFF_SENTINEL } from '../core/runtime/kickoff.js';
+/**
+ * Register the goal-capture handler on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: on the first interactive message of a goal-less node,
+ * persist it as the goal.
+ */
+export function registerCanvasGoalCapture(pi) {
+    pi.on('input', (event) => {
+        try {
+            const nodeId = process.env['CRTR_NODE_ID'];
+            if (nodeId === undefined || nodeId.trim() === '')
+                return; // not a canvas node
+            // Only a genuine human-typed prompt seeds the mandate — never an RPC or an
+            // extension-injected message (inbox wakes, steering nudges, kickoffs).
+            if (event.source !== 'interactive')
+                return;
+            const text = (event.text ?? '').trim();
+            if (text === '')
+                return;
+            // A fresh-revive kickoff is delivered as the launch prompt; never let it
+            // masquerade as the user's first mandate.
+            if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
+                return;
+            captureGoalIfAbsent(nodeId, text);
+        }
+        catch {
+            // Best-effort: a capture failure must never drop or alter the message.
+        }
+    });
+}
+export default registerCanvasGoalCapture;

package/dist/pi-extensions/canvas-passive-context.d.ts

@@ -0,0 +1,32 @@
+import type { InboxEntry } from '../core/feed/inbox.js';
+interface InputEventLike {
+    type: 'input';
+    text: string;
+    images?: unknown[];
+    source: 'interactive' | 'rpc' | 'extension';
+}
+type InputEventResultLike = {
+    action: 'continue';
+} | {
+    action: 'transform';
+    text: string;
+    images?: unknown[];
+} | {
+    action: 'handled';
+};
+interface PiLike {
+    on: (event: 'input', handler: (event: InputEventLike, ctx: any) => InputEventResultLike | void) => void;
+}
+/**
+ * Render drained passive entries (oldest first) into one XML pre-text block.
+ * Each accumulated message is its own timestamped `<update>` element.
+ */
+export declare function formatPassive(entries: InboxEntry[]): string;
+/**
+ * Register the passive-context drain on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: drain on every message, prepend when non-empty.
+ */
+export declare function registerCanvasPassiveContext(pi: PiLike): void;
+export default registerCanvasPassiveContext;

package/dist/pi-extensions/canvas-passive-context.js

@@ -0,0 +1,114 @@
+// canvas-passive-context.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 passive-subscription drain. A PASSIVE subscription (active=false edge)
+// never wakes its subscriber: `push` routes its pointers to passive.jsonl, which
+// the inbox-watcher never polls. They simply accumulate. This extension is what
+// finally surfaces them — the moment the node is MESSAGED.
+//
+// pi fires an `input` event for every user message (human-typed, an RPC, or an
+// extension's sendUserMessage — including the inbox-watcher's own wake). On that
+// event we DRAIN the node's passive accumulator and, when non-empty, prepend
+// every entry as timestamped XML to the message text via the `transform` action.
+// So the backlog rides in as pre-text on whatever message next engages the node,
+// before the LLM sees it — and is cleared in the same step (drain = read+clear),
+// so it surfaces exactly once.
+//
+// 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 { existsSync, readFileSync } from 'node:fs';
+import { drainPassive } from '../core/feed/passive.js';
+// Per-entry body cap so a single fat report can't blow the context budget. The
+// full report stays on disk at `ref` if the agent needs more.
+const BODY_CAP = 4_000;
+// ---------------------------------------------------------------------------
+// Report dereference — turn a passive pointer into the message text it carries.
+// ---------------------------------------------------------------------------
+/** Strip the leading YAML frontmatter block a report is written with, returning
+ *  just the body. Tolerant: no frontmatter → returns the input unchanged. */
+function stripFrontmatter(raw) {
+    if (!raw.startsWith('---\n'))
+        return raw;
+    const end = raw.indexOf('\n---\n', 4);
+    return end === -1 ? raw : raw.slice(end + 5);
+}
+/** The content for one accumulated entry: the dereferenced report body when the
+ *  pointer carries a `ref`, else the entry's own label/data. Capped + trimmed. */
+function entryContent(e) {
+    if (e.ref !== undefined && e.ref !== '' && existsSync(e.ref)) {
+        try {
+            const body = stripFrontmatter(readFileSync(e.ref, 'utf8')).trim();
+            if (body !== '') {
+                return body.length > BODY_CAP
+                    ? `${body.slice(0, BODY_CAP)}\n… (truncated; full report at ${e.ref})`
+                    : body;
+            }
+        }
+        catch {
+            /* fall through to the label */
+        }
+    }
+    const data = e.data?.['body'];
+    if (typeof data === 'string' && data.trim() !== '')
+        return data.trim();
+    return e.label;
+}
+/** Minimal XML attribute escaping for the values we interpolate. */
+function attr(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * Render drained passive entries (oldest first) into one XML pre-text block.
+ * Each accumulated message is its own timestamped `<update>` element.
+ */
+export function formatPassive(entries) {
+    const blocks = entries
+        .map((e) => {
+        const from = attr(e.from ?? 'system');
+        const refAttr = e.ref !== undefined && e.ref !== '' ? ` ref="${attr(e.ref)}"` : '';
+        return (`<update from="${from}" kind="${attr(e.kind)}" at="${attr(e.ts)}"${refAttr}>\n` +
+            `${entryContent(e)}\n` +
+            `</update>`);
+    })
+        .join('\n');
+    return (`<passive-subscription-backlog count="${entries.length}" ` +
+        `note="Reports accumulated from nodes you passively subscribe to while you were not actively listening. ` +
+        `Surfaced now because you were messaged. Oldest first.">\n` +
+        `${blocks}\n` +
+        `</passive-subscription-backlog>`);
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the passive-context drain on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: drain on every message, prepend when non-empty.
+ */
+export function registerCanvasPassiveContext(pi) {
+    pi.on('input', (event) => {
+        try {
+            const nodeId = process.env['CRTR_NODE_ID'];
+            if (nodeId === undefined || nodeId.trim() === '')
+                return; // not a canvas node
+            const drained = drainPassive(nodeId);
+            if (drained.length === 0)
+                return; // nothing accumulated → leave the message as-is
+            const preText = formatPassive(drained);
+            const text = event.text.trim() === '' ? preText : `${preText}\n\n${event.text}`;
+            return { action: 'transform', text, images: event.images };
+        }
+        catch {
+            // Best-effort: a drain/format failure must never drop the user's message.
+            return;
+        }
+    });
+}
+export default registerCanvasPassiveContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",