@crouton-kit/crouter 0.3.27 → 0.3.29

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

@@ -0,0 +1,236 @@
+// canvas-recap.ts — pi extension for pi-native canvas agent nodes.
+//
+// A per-node INACTIVITY RECAP, drawn as the topmost chrome above the editor.
+// When a node has had NO new message (user or assistant) for IDLE_MS (300s by
+// default), it runs Haiku over the literal conversation and pins a terse
+// three-fragment card — goal / doing-now / next — above canvas-nav's manager
+// line. The card disappears the instant the next message arrives, and the idle
+// clock restarts.
+//
+//   trigger/clear are keyed off MESSAGES, not turns-of-work:
+//     • a user `input` event OR an assistant `turn_end` resets the idle clock
+//       and clears any shown recap.
+//     • a single low-rate timer (no busy-loop) checks elapsed-since-last-message
+//       and, on crossing IDLE_MS, generates + shows the recap once.
+//
+//   Haiku input = ALL user + assistant LITERAL text, most-recent within a char
+//   budget. Tool calls, tool results, thinking blocks, and extension-injected
+//   custom messages are excluded (only `message` entries with role user/assistant,
+//   and only their `text` content blocks).
+//
+//   Placement: key `crtr-recap`, placement `aboveEditor`, ordered ABOVE
+//   `crtr-managers` via the widget-order bus (pi's widget store is insertion-
+//   ordered and re-setting moves a key to the bottom; after we paint the recap
+//   we ask canvas-nav to re-assert its manager line, which drops it below us).
+//
+//   Surface gating: shows in BOTH the in-pane pi TUI (mode 'tui') and the
+//   headless broker → attach/web viewers (mode 'print', setWidget broadcasts to
+//   all surfaces). It does NOT gate on mode === 'tui' (that would kill the
+//   headless+attach path). It NO-OPs only when ui/setWidget is unavailable, and
+//   harmlessly in a true one-shot `pi -p` (the unref'd timer never fires before
+//   the process exits, and naming-style one-shots load with --no-extensions).
+//
+// INERT when CRTR_NODE_ID is absent (a plain pi session or legacy job agent).
+//
+// 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 { generateRecap } from '../core/runtime/recap.js';
+import { requestNavRerender } from './widget-order-bus.js';
+// ---------------------------------------------------------------------------
+// Tuning constants
+// ---------------------------------------------------------------------------
+/** No-new-message window before a recap is shown. 300s by default; override with
+ *  CRTR_RECAP_IDLE_MS (for fast runtime verification). */
+function idleMs() {
+    const raw = process.env['CRTR_RECAP_IDLE_MS'];
+    const n = raw !== undefined ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 300_000;
+}
+/** How often the (single, low-rate) timer checks elapsed-since-last-message.
+ *  Mirrors canvas-nav's ASK_POLL_MS — cheap and tmux/crtr-free. */
+const POLL_MS = 7_000;
+/** Char budget on the conversation fed to Haiku — the model only needs the gist,
+ *  so we keep the MOST-RECENT text within this cap (a recap is about where we
+ *  left off, not the whole history). */
+const CONVO_CHAR_BUDGET = 12_000;
+const WIDGET_KEY = 'crtr-recap';
+// ---------------------------------------------------------------------------
+// Module-level state — persists across /reload so the timer doesn't stack.
+// ---------------------------------------------------------------------------
+/** The one live poll timer. Cleared and replaced on every re-registration. */
+let liveTimer;
+// ---------------------------------------------------------------------------
+// Conversation extraction — literal user+assistant text ONLY.
+// ---------------------------------------------------------------------------
+/** Pull the literal text out of a message's content (string or text blocks),
+ *  dropping non-text blocks (thinking, toolCall, image). */
+function messageText(msg) {
+    const c = msg.content;
+    if (typeof c === 'string')
+        return c.trim();
+    if (!Array.isArray(c))
+        return '';
+    return c
+        .filter((b) => b !== null && typeof b === 'object' && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => (b.text ?? '').trim())
+        .filter((t) => t !== '')
+        .join('\n')
+        .trim();
+}
+/** Concatenate the conversation's user + assistant literal text into a single
+ *  `User:`/`Agent:` transcript, keeping only the MOST-RECENT CONVO_CHAR_BUDGET
+ *  characters. Excludes tool calls/results (role toolResult, plus toolCall/
+ *  thinking content blocks dropped by messageText) and extension-injected
+ *  custom messages (entry.type !== 'message'). Returns '' when there is nothing
+ *  to summarize. */
+function buildConversation(sm) {
+    let entries;
+    try {
+        entries = sm.getEntries();
+    }
+    catch {
+        return '';
+    }
+    const parts = [];
+    for (const e of entries) {
+        if (e.type !== 'message' || e.message === undefined)
+            continue;
+        const role = e.message.role;
+        if (role !== 'user' && role !== 'assistant')
+            continue; // drop toolResult etc.
+        const text = messageText(e.message);
+        if (text === '')
+            continue;
+        parts.push(`${role === 'user' ? 'User' : 'Agent'}: ${text}`);
+    }
+    if (parts.length === 0)
+        return '';
+    const full = parts.join('\n\n');
+    return full.length > CONVO_CHAR_BUDGET ? full.slice(full.length - CONVO_CHAR_BUDGET) : full;
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the inactivity-recap chrome on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent — a plain pi session
+ * or legacy job agent loads it as a no-op.
+ */
+export function registerCanvasRecap(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    // Captured on session_start; used by the timer and the message handlers.
+    let ui;
+    let sessionManager;
+    /** Wall-clock of the most recent user/assistant message. The idle clock. */
+    let lastMessageAt = Date.now();
+    /** True while a recap is currently shown (so we generate at most once per
+     *  idle window, and know whether a clear is needed on the next message). */
+    let recapShown = false;
+    /** True while a Haiku generation is in flight (so we don't fire a second). */
+    let generating = false;
+    const canPaint = () => ui !== undefined && typeof ui.setWidget === 'function';
+    const clearRecap = () => {
+        if (!canPaint())
+            return;
+        try {
+            ui.setWidget(WIDGET_KEY, undefined, { placement: 'aboveEditor' });
+        }
+        catch { /* best-effort */ }
+    };
+    /** Render the three fragments as the topmost above-editor card. */
+    const showRecap = (fragments) => {
+        if (!canPaint())
+            return;
+        const labels = ['◷ goal', '· now ', '→ next'];
+        const lines = fragments.slice(0, 3).map((f, i) => `${labels[i] ?? '    '}  ${f}`);
+        if (lines.length === 0)
+            return;
+        try {
+            ui.setWidget(WIDGET_KEY, lines, { placement: 'aboveEditor' });
+        }
+        catch { /* best-effort */ }
+        // Re-assert the manager line BELOW us (pi's widget store is insertion-
+        // ordered; re-setting crtr-managers drops it under crtr-recap).
+        requestNavRerender();
+    };
+    /** A user or assistant message landed: reset the idle clock and clear any
+     *  shown recap (the conversation has moved on). */
+    const onMessage = () => {
+        lastMessageAt = Date.now();
+        if (recapShown) {
+            recapShown = false;
+            clearRecap();
+            requestNavRerender();
+        }
+    };
+    // -------------------------------------------------------------------------
+    // Events
+    // -------------------------------------------------------------------------
+    pi.on('session_start', (_event, ctx) => {
+        ui = ctx.ui;
+        sessionManager = ctx.sessionManager;
+        // Fresh session / hot-swap: start the idle clock now and drop any stale
+        // recap that bled through a /reload.
+        lastMessageAt = Date.now();
+        recapShown = false;
+        generating = false;
+        clearRecap();
+    });
+    pi.on('input', (_event, _ctx) => {
+        // Every user message (any source) is activity — reset + clear.
+        onMessage();
+    });
+    pi.on('turn_end', (_event, _ctx) => {
+        // A completed assistant turn is activity — reset + clear.
+        onMessage();
+    });
+    // -------------------------------------------------------------------------
+    // The single low-rate idle poll — no busy-loop, mirrors canvas-nav's timer.
+    // -------------------------------------------------------------------------
+    if (liveTimer !== undefined)
+        clearInterval(liveTimer);
+    const timer = setInterval(() => {
+        try {
+            if (!canPaint() || sessionManager === undefined)
+                return;
+            if (recapShown || generating)
+                return;
+            if (Date.now() - lastMessageAt < idleMs())
+                return;
+            const convo = buildConversation(sessionManager);
+            if (convo === '')
+                return; // nothing to summarize yet
+            // Snapshot the clock: if a message arrives while Haiku runs, discard the
+            // (now-stale) result instead of painting over the live conversation.
+            const startedAt = lastMessageAt;
+            generating = true;
+            generateRecap(convo, (fragments) => {
+                generating = false;
+                if (lastMessageAt !== startedAt)
+                    return; // a message landed mid-flight
+                if (!canPaint())
+                    return;
+                recapShown = true;
+                showRecap(fragments);
+            });
+            // generateRecap is silent on failure (never calls back), so clear the
+            // in-flight flag after the timeout window even if no callback fires.
+            setTimeout(() => { generating = false; }, 30_000).unref?.();
+        }
+        catch {
+            /* timer is best-effort */
+        }
+    }, POLL_MS);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    liveTimer = timer;
+    pi.on('session_shutdown', () => {
+        clearInterval(timer);
+        if (liveTimer === timer)
+            liveTimer = undefined;
+    });
+}
+export default registerCanvasRecap;

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

@@ -27,6 +27,7 @@
 // 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 { surfaceTmuxStyleArgs } from '../core/runtime/surface-bg.js';
 /** Single-quote a string for safe interpolation into a `sh -c` command line —
  *  tmux runs the display-popup trailing string through the shell, so a cwd with
  *  spaces or quotes must be escaped. */
@@ -66,7 +67,7 @@ export function registerCanvasResume(pi) {
                 const cwd = shellQuote(process.cwd());
                 const cmd = `crtr canvas browse --return-pane ${origPane} --cwd ${cwd}`;
                 try {
-                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', cmd], () => { });
+                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => { });
                 }
                 catch { /* best-effort */ }
                 return;

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

@@ -1,4 +1,4 @@
-type PiEvents = 'agent_start' | 'turn_end' | 'agent_end' | 'session_shutdown' | 'session_start';
+type PiEvents = 'agent_start' | 'turn_end' | 'agent_end' | 'session_shutdown' | 'session_start' | 'tool_execution_start';
 interface PiLike {
     on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
     sendUserMessage: (content: string, options?: {
@@ -6,20 +6,22 @@ interface PiLike {
     }) => void;
 }
 /** The nudge text for a crossed band, specialized to the node's (mode,
- *  lifecycle) persona + how far along the escalation it is.
+ *  lifecycle) persona + how far along the escalation it is. `crtr node yield` is
+ *  the single "keep going past this window" verb for every persona: it refreshes
+ *  the node into a clean window against a roadmap, and for a base node
+ *  auto-promotes transparently — so no persona is ever steered at a bare `node
+ *  promote` (which framed promotion as a heavy "become an orchestrator" step and
+ *  bred yield-avoidance).
  *
- *  - 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.
+ *  - orchestrator (terminal OR resident): checkpoint context/roadmap.md, then
+ *    yield (it already has a roadmap to bring current first).
+ *  - resident/base (root conversation): yield to continue in a fresh window if
+ *    the chat is growing into a job, else wrap up — a root can simply end.
+ *  - terminal/base (worker): yield to continue if work remains, or `push final`
+ *    when close.
  *
- *  At/past 185k every persona goes PUSHY: the context is long enough that
- *  drifting further risks an overflow. */
+ *  The wording strengthens with depth: gentle < 150k → firm < 185k → pushy at/
+ *  past 185k, where 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`.