@crouton-kit/crouter 0.3.13 → 0.3.15

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

@@ -0,0 +1,103 @@
+// canvas-commands.ts — pi extension registering canvas slash-commands on nodes.
+//
+//   /promote [kind]  — promote THIS node to an orchestrator. Runs
+//     `crtr node promote --json` for CRTR_NODE_ID (optionally specializing its
+//     kind), then triggers a turn. The orchestration guidance is injected
+//     CENTRALLY by the persona injector (canvas-stophook turn_end) at the turn
+//     boundary — the same path the node gets 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 an 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 orchestration guidance is no longer returned by the command — the
+            // persona injector (canvas-stophook turn_end) is the single source and
+            // steers it in at the next turn boundary. Trigger a turn so the node wakes
+            // and the injector fires, exactly as when the node runs `crtr node
+            // promote` itself by hand.
+            pi.sendMessage({
+                customType: 'crtr-promote',
+                content: 'You have just been promoted to an orchestrator. Your new-role guidance is arriving — read it, author your roadmap, and start delegating.',
+                display: false,
+            }, { triggerTurn: true });
+        },
+    });
+}
+export default registerCanvasCommands;

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

@@ -0,0 +1,70 @@
+/** The `customType` stamped on the injected session message. Used both to write
+ *  the entry and to detect it on resume (the idempotency guard). */
+export declare const CONTEXT_INTRO_CUSTOM_TYPE = "crtr-context";
+interface SessionEntryLike {
+    type: string;
+    customType?: string;
+}
+interface SessionStartCtxLike {
+    sessionManager: {
+        getEntries: () => SessionEntryLike[];
+    };
+}
+interface CustomMessageLike {
+    customType: string;
+    content: string;
+    display?: boolean;
+}
+/** The message handed to a message renderer. `content` is normally the string we
+ *  sent, but pi types it as string-or-blocks, so we handle both. */
+interface RenderedMessageLike {
+    customType: string;
+    content: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+}
+/** Minimal structural match for pi-tui's `Component` (render + invalidate). A
+ *  plain object of this shape is a valid child for pi's Container. */
+interface ComponentLike {
+    render: (width: number) => string[];
+    invalidate: () => void;
+}
+/** Subset of pi's `Theme` we touch — `fg(color, text)` wraps text in ANSI. Used
+ *  defensively (falls back to plain text if absent). */
+interface ThemeLike {
+    fg?: (color: string, text: string) => string;
+}
+interface PiLike {
+    on: (event: 'session_start', handler: (event: unknown, ctx: SessionStartCtxLike) => void | Promise<void>) => void;
+    sendMessage: (message: CustomMessageLike, options?: {
+        deliverAs?: string;
+        triggerTurn?: boolean;
+    }) => void;
+    registerMessageRenderer: (customType: string, renderer: (message: RenderedMessageLike, options: {
+        expanded?: boolean;
+    }, theme: ThemeLike) => ComponentLike | undefined) => void;
+}
+/** Build the <crtr-context> bearings block for `nodeId`. Thin wrapper over the
+ *  shared builder in core/runtime/bearings.ts (the single source of truth, also
+ *  used by the promotion guidance dump). Exported for testing. */
+export declare function buildContextIntro(nodeId: string): string;
+/**
+ * Renderer for `crtr-context` messages. Collapsed (default) shows a one-line
+ * stub; expanded (Ctrl+O) shows the label + full body. Returns a plain object
+ * matching pi's structural `Component` interface — no pi-tui import. Exported for
+ * testing.
+ */
+export declare function renderContextMessage(message: RenderedMessageLike, options: {
+    expanded?: boolean;
+}, theme: ThemeLike): ComponentLike;
+/**
+ * Register the context-intro preamble on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. On `session_start`
+ * it injects the <crtr-context> block as the first message of a brand-new chat
+ * — but only when the session does not already carry it, so a `--session <id>`
+ * relaunch (which restores the conversation) never duplicates the block.
+ */
+export declare function registerCanvasContextIntro(pi: PiLike): void;
+export default registerCanvasContextIntro;

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

@@ -0,0 +1,164 @@
+// canvas-context-intro.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 bearings preamble. On `session_start` — which fires BEFORE the node's
+// first user message enters the session — this injects ONE <crtr-context>
+// message via `pi.sendMessage` (no delivery options, so at the idle start it is
+// pushed straight onto the message list and persisted). Because the session is
+// still empty at that point, the bearings land as the FIRST entry, ahead of the
+// node's first prompt — the orienting frame, not a trailing afterthought.
+//   (before_agent_start / deliverAs:"nextTurn" both append AFTER the user
+//    message — see agent-session's submit path — which is why we use
+//    session_start instead.)
+//
+// The block carries: the path to the node's own context dir and the framing for
+// what belongs there (a shared document store for the other nodes). Resident
+// orchestrators additionally get the across-refresh-cycles framing + a <memory>
+// block merging the indexes of their three scoped memory stores (user-global,
+// project, node-local), each labeled with its absolute dir + index path. The
+// prose lives in core/runtime/bearings.ts (shared with the promotion guidance
+// dump), which gates the memory block on the node having a node-local store — so
+// a terminal worker gets no memory framing at all.
+//
+// IDEMPOTENT across resumes: a `--session` relaunch restores the conversation,
+// so the block is already in history; the session_start handler sees it via
+// `sessionManager.getEntries()` and skips, so it never accumulates.
+//
+// COLLAPSED BY DEFAULT: a `registerMessageRenderer` keyed to our customType
+// renders the block as a single one-line stub; the full body only appears when
+// the user expands tool output (Ctrl+O / `app.tools.expand`). pi drives this via
+// `CustomMessageComponent.setExpanded(toolOutputExpanded)`, so the same toggle
+// that expands tool results expands the bearings. The renderer returns a plain
+// object satisfying pi's structural `Component` interface ({ render, invalidate })
+// — no pi-tui class needed. The LLM always sees the full `content` regardless of
+// how it renders; the renderer is display-only.
+//
+// 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 { buildContextBearings } from '../core/runtime/bearings.js';
+/** The `customType` stamped on the injected session message. Used both to write
+ *  the entry and to detect it on resume (the idempotency guard). */
+export const CONTEXT_INTRO_CUSTOM_TYPE = 'crtr-context';
+// ---------------------------------------------------------------------------
+// Block builder
+// ---------------------------------------------------------------------------
+/** Build the <crtr-context> bearings block for `nodeId`. Thin wrapper over the
+ *  shared builder in core/runtime/bearings.ts (the single source of truth, also
+ *  used by the promotion guidance dump). Exported for testing. */
+export function buildContextIntro(nodeId) {
+    return buildContextBearings(nodeId);
+}
+// ---------------------------------------------------------------------------
+// Collapsed-by-default rendering
+// ---------------------------------------------------------------------------
+/** Pull the plain text out of a custom message's content (string or blocks). */
+function messageText(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    return message.content
+        .filter((c) => c.type === 'text' && typeof c.text === 'string')
+        .map((c) => c.text)
+        .join('\n');
+}
+/** Hard-wrap a single logical line to `width` columns (content carries no ANSI).
+ *  Code-point aware so wide-string slicing never splits a surrogate pair; the
+ *  bearings prose is plain text, so code-point count == visible columns. */
+function wrapLine(line, width) {
+    if (width <= 0)
+        return [''];
+    const chars = Array.from(line);
+    if (chars.length <= width)
+        return [line];
+    const out = [];
+    for (let i = 0; i < chars.length; i += width)
+        out.push(chars.slice(i, i + width).join(''));
+    return out;
+}
+/** Truncate plain text to at most `width` columns, appending an ellipsis when it
+ *  would overflow. Content here is ANSI-free plain text (label + prose), so a
+ *  code-point count stands in for visible width. The renderer MUST keep every
+ *  emitted line within the terminal width or pi's TUI aborts the whole render. */
+function truncateToWidth(text, width) {
+    if (width <= 0)
+        return '';
+    const chars = Array.from(text);
+    if (chars.length <= width)
+        return text;
+    if (width === 1)
+        return '…';
+    return chars.slice(0, width - 1).join('') + '…';
+}
+/**
+ * Renderer for `crtr-context` messages. Collapsed (default) shows a one-line
+ * stub; expanded (Ctrl+O) shows the label + full body. Returns a plain object
+ * matching pi's structural `Component` interface — no pi-tui import. Exported for
+ * testing.
+ */
+export function renderContextMessage(message, options, theme) {
+    const expanded = options?.expanded === true;
+    const paint = (color, text) => typeof theme?.fg === 'function' ? theme.fg(color, text) : text;
+    return {
+        render(width) {
+            const w = typeof width === 'number' && width > 0 ? width : 80;
+            if (!expanded) {
+                // Truncate BEFORE painting so the ANSI wrapper never inflates the
+                // measured width; an over-wide line aborts pi's entire TUI render.
+                const stub = `[${CONTEXT_INTRO_CUSTOM_TYPE}] orienting bearings — ctrl+o to expand`;
+                return [paint('dim', truncateToWidth(stub, w))];
+            }
+            const lines = [paint('customMessageLabel', truncateToWidth(`[${CONTEXT_INTRO_CUSTOM_TYPE}]`, w)), ''];
+            for (const raw of messageText(message).split('\n')) {
+                for (const wrapped of wrapLine(raw, w))
+                    lines.push(paint('customMessageText', wrapped));
+            }
+            return lines;
+        },
+        invalidate() {
+            /* stateless — nothing to clear */
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the context-intro preamble on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. On `session_start`
+ * it injects the <crtr-context> block as the first message of a brand-new chat
+ * — but only when the session does not already carry it, so a `--session <id>`
+ * relaunch (which restores the conversation) never duplicates the block.
+ */
+export function registerCanvasContextIntro(pi) {
+    // Collapse the block to a one-liner until the user expands tool output (Ctrl+O).
+    // Harmless to register outside TUI mode (it's only consulted while rendering).
+    pi.registerMessageRenderer(CONTEXT_INTRO_CUSTOM_TYPE, renderContextMessage);
+    pi.on('session_start', (_event, ctx) => {
+        try {
+            const nodeId = process.env['CRTR_NODE_ID'];
+            if (nodeId === undefined || nodeId.trim() === '')
+                return; // not a canvas node
+            // Idempotent: a restored/reloaded session already carries the block.
+            const present = ctx.sessionManager
+                .getEntries()
+                .some((e) => e.type === 'custom_message' && e.customType === CONTEXT_INTRO_CUSTOM_TYPE);
+            if (present)
+                return;
+            // No delivery options: at the idle start of a session this is pushed onto
+            // the (still empty) message list and persisted immediately, so it precedes
+            // the node's first prompt.
+            pi.sendMessage({
+                customType: CONTEXT_INTRO_CUSTOM_TYPE,
+                content: buildContextIntro(nodeId),
+                display: true,
+            });
+        }
+        catch {
+            // Best-effort: a failure here must never break session startup.
+            return;
+        }
+    });
+}
+export default registerCanvasContextIntro;

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

@@ -0,0 +1,21 @@
+interface InputEventLike {
+    type: 'input';
+    text: string;
+    images?: unknown[];
+    source: 'interactive' | 'rpc' | 'extension';
+}
+interface PiLike {
+    on: (event: 'input', handler: (event: InputEventLike, ctx: any) => void) => void;
+    /** Update the live session display name (pi's editor label). Present in
+     *  interactive mode; optional so the extension stays inert where it's not. */
+    setSessionName?: (name: string) => 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,67 @@
+// 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';
+import { generateAndPersistName } from '../core/runtime/naming.js';
+import { editorLabel } from '../core/canvas/index.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;
+            // First mandate for a bare root: persist it as the goal, and ask pi
+            // (async, non-blocking) to name the session from it. The name lands on
+            // meta.description; the onNamed callback pushes the new editor label into
+            // THIS live session via setSessionName, so it updates immediately instead
+            // of only on the next cycle.
+            if (captureGoalIfAbsent(nodeId, text)) {
+                generateAndPersistName(nodeId, text, (meta) => {
+                    try {
+                        pi.setSessionName?.(editorLabel(meta));
+                    }
+                    catch { /* best-effort */ }
+                });
+            }
+        }
+        catch {
+            // Best-effort: a capture failure must never drop or alter the message.
+        }
+    });
+}
+export default registerCanvasGoalCapture;

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

@@ -32,6 +32,7 @@
 // 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';
+import { getNode } from '../core/canvas/index.js';
 // ---------------------------------------------------------------------------
 // Module-level timer — prevents stacking on /reload (the double-notify bug).
 //
@@ -179,6 +180,16 @@ export function registerCanvasInboxWatcher(pi) {
                 seeded = true;
             }
             const newEntries = readInboxSince(nodeId, cursor);
+            // Refresh-yield in flight: the node ran `crtr node yield` and is about to be
+            // torn down and revived fresh. Hold everything — don't consume the cursor
+            // (advancing it past these entries would drop them on tear-down) and don't
+            // deliver (steering a child's `final` into the yielding turn hijacks the
+            // clean stop the refresh path depends on, which is how a yield got derailed
+            // mid-flight). The fresh pi re-reads the feed on boot. getNode only when
+            // there's actual work pending, so idle ticks stay cheap.
+            if ((newEntries.length > 0 || buffer.length > 0) && getNode(nodeId)?.intent === 'refresh') {
+                return;
+            }
             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

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

@@ -1,26 +1,34 @@
 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. */
+     *  the key. Returns an 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 CommandCtx {
+    ui: UIContext;
+}
 interface PiLike {
     on(event: PiEvents, handler: (event: any, ctx: ExtensionCtx) => void | Promise<void>): void;
+    registerCommand?(name: string, options: {
+        description?: string;
+        handler: (args: string, ctx: CommandCtx) => void | Promise<void>;
+    }): void;
+    registerShortcut?(shortcut: string, options: {
+        description?: string;
+        handler: (ctx: CommandCtx) => void | Promise<void>;
+    }): void;
 }
 /**
  * Register the canvas nav chrome on `pi`.