@north-light/crouter 0.3.184 → 0.3.186

package/dist/core/tui/page-host.d.ts

@@ -0,0 +1,25 @@
+import { ProcessTerminal, TUI, type Component, type Focusable } from "@earendil-works/pi-tui";
+import { readRawScopeConfig } from "../config.js";
+import { type BindingId, type BindingResolution } from "../keybindings/index.js";
+/** A full-screen page: a focusable TUI component that cleans up after itself. */
+export type TuiPageSurface = Component & Focusable & {
+    dispose(): void;
+};
+export interface TuiPageContext {
+    tui: TUI;
+    terminal: ProcessTerminal;
+    bindings: BindingResolution<BindingId>;
+    rawUserConfig: ReturnType<typeof readRawScopeConfig>;
+}
+export interface TuiPageControl<Result> {
+    /** Close the page with a result. */
+    submit(result: Result): void;
+    /** Close the page with no result. */
+    cancel(): void;
+}
+/** Mount one page as the TUI's only child and resolve when it closes.
+ *
+ *  `interceptCancel` is a process-level escape hatch for surfaces that must be
+ *  abandonable while a nested component holds the keyboard; it runs before the
+ *  page sees the input and closes the page when it returns true. */
+export declare function runTuiPage<Result>(createSurface: (context: TuiPageContext, control: TuiPageControl<Result>) => TuiPageSurface, interceptCancel?: (data: string, bindings: BindingResolution<BindingId>) => boolean): Promise<Result | undefined>;

package/dist/core/tui/page-host.js

@@ -0,0 +1,65 @@
+// The process-level terminal host for crouter's full-screen TUI pages —
+// `crtr sys settings`, the setup wizard, and `crtr pkg browse`.
+//
+// It owns exactly the concerns every page shares: theme, resolved keybindings,
+// the raw user config those pages edit, the ProcessTerminal/TUI pair, and a
+// restore path that survives an exception, a signal, and process exit. Anything
+// a single page needs beyond that — pi's model runtime, a canvas client — the
+// page's own runner builds and closes over before calling in here.
+import { ProcessTerminal, TUI, } from "@earendil-works/pi-tui";
+import { applyTheme } from "../../clients/attach/config.js";
+import { readRawScopeConfig } from "../config.js";
+import { resolveKeybindings, } from "../keybindings/index.js";
+/** Mount one page as the TUI's only child and resolve when it closes.
+ *
+ *  `interceptCancel` is a process-level escape hatch for surfaces that must be
+ *  abandonable while a nested component holds the keyboard; it runs before the
+ *  page sees the input and closes the page when it returns true. */
+export async function runTuiPage(createSurface, interceptCancel) {
+    applyTheme({ cwd: process.cwd() });
+    const rawUserConfig = readRawScopeConfig("user");
+    const bindings = resolveKeybindings(rawUserConfig?.keybindings);
+    const terminal = new ProcessTerminal();
+    const tui = new TUI(terminal, true);
+    return new Promise((resolve, reject) => {
+        let surface;
+        let restored = false;
+        const restore = () => {
+            if (restored)
+                return;
+            restored = true;
+            surface?.dispose();
+            try {
+                tui.stop();
+            }
+            catch {
+                /* terminal restore */
+            }
+        };
+        const finish = (result) => {
+            restore();
+            resolve(result);
+        };
+        try {
+            surface = createSurface({ tui, terminal, bindings, rawUserConfig }, { submit: finish, cancel: () => finish(undefined) });
+            tui.addChild(surface);
+            tui.setFocus(surface);
+            process.once("exit", restore);
+            for (const signal of ["SIGTERM", "SIGHUP", "SIGINT"])
+                process.once(signal, () => finish(undefined));
+            if (interceptCancel !== undefined) {
+                tui.addInputListener((data) => {
+                    if (!interceptCancel(data, bindings))
+                        return undefined;
+                    finish(undefined);
+                    return { consume: true };
+                });
+            }
+            tui.start();
+        }
+        catch (error) {
+            restore();
+            reject(error);
+        }
+    });
+}

package/dist/daemon/api/handlers/messages.js

@@ -59,12 +59,6 @@ function parseSendBody(body) {
     if (delivery !== undefined && delivery !== 'interactive') {
         throw usage(`invalid delivery: ${String(delivery)} (expected interactive)`);
     }
-    const messageId = b['message_id'];
-    if (messageId !== undefined && typeof messageId !== 'string') {
-        throw usage('message_id must be a string');
-    }
-    if (typeof messageId === 'string' && messageId.trim() !== '')
-        out.message_id = messageId;
     if (delivery === 'interactive') {
         // Interactive delivery is a live-conversation send: a plain immediate body,
         // nothing that only makes sense on the durable path.
@@ -164,7 +158,7 @@ async function handleMessage(ctx) {
     //     straight there (append + revive, watcher delivers post-boot). ---
     if (req.delivery === 'interactive' && isBrokerLive(meta)) {
         try {
-            await deliverLive(id, req.body, req.message_id);
+            await deliverLive(id, req.body);
             const body = {
                 node_id: id,
                 delivered: true,

package/dist/pi-extensions/canvas-bash-valve.js

@@ -28,6 +28,7 @@ import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId } from '../core/bash-jobs.js';
+import { Type } from 'typebox';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
 // ---------------------------------------------------------------------------
 // Deadline — 5 minutes by default, overridable via CRTR_BASH_VALVE_MS
@@ -342,6 +343,49 @@ export function createValveOperations(nodeId, contextDir) {
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// `purpose` — the one line a person reads while a command runs
+//
+// A deliberate deviation from taking pi's definition verbatim, and the only one
+// here. Everywhere crtr's output reaches a non-technical audience, the host has
+// to render SOMETHING per step, and without this field its only material is the
+// command — which yields "Running command" for an entire turn. The model is the
+// only party that knows why it is running this, so it says so, in one clause,
+// before the command streams.
+//
+// Declared FIRST so it arrives ahead of `command` in the argument stream: a host
+// parsing partial JSON can show the label while the command is still being
+// written, rather than after the call is complete and about to finish.
+//
+// The execute path ignores it entirely — this is a labelling channel, not an
+// input. Optional, so a model that omits it behaves exactly as before.
+//
+// Upstream ask: pi's own bash tool should carry this (Claude Code's bash tool
+// has shipped an equivalent `description` field for years). Until it does, the
+// field is re-declared here on top of pi's schema rather than forked into it.
+// ---------------------------------------------------------------------------
+const PURPOSE_DESCRIPTION = [
+    'One short clause naming what this step is FOR, in the words of the person you',
+    'are working for — "Reading the Acme thread", not "Fetching emails" and never',
+    '"Running GMAIL_FETCH_EMAILS". A person reads this while the command runs; it',
+    'is the only thing they see of this step. Under about eight words. Omit it for',
+    'steps that only touch your own scratch work.',
+].join(' ');
+/**
+ * Prepend an optional `purpose` to pi's bash schema, carrying pi's own property
+ * definitions through verbatim — so a future upstream change to the `command`
+ * or `timeout` wording still reaches the model, and this file owns exactly one
+ * field.
+ */
+function withPurpose(definition) {
+    return {
+        ...definition,
+        parameters: Type.Object({
+            purpose: Type.Optional(Type.String({ description: PURPOSE_DESCRIPTION })),
+            ...definition.parameters.properties,
+        }),
+    };
+}
 export default function (pi) {
     const nodeId = process.env['CRTR_NODE_ID'];
     if (nodeId === undefined || nodeId.trim() === '')
@@ -356,6 +400,6 @@ export default function (pi) {
     // every session_start is idempotent (last registration wins).
     pi.on('session_start', (_event, ctx) => {
         const operations = createValveOperations(nodeId, contextDir);
-        pi.registerTool(createBashToolDefinition(ctx.cwd, { operations }));
+        pi.registerTool(withPurpose(createBashToolDefinition(ctx.cwd, { operations })));
     });
 }

package/dist/types.d.ts

@@ -301,7 +301,10 @@ export interface InstalledPlugin {
 }
 export interface InstalledMarketplace {
     name: string;
-    scope: Scope;
+    /** Never `builtin`: marketplaces are registered by the user into the user or
+     *  project scope, and `listInstalledMarketplaces` has no builtin directory to
+     *  read. `builtin` describes plugins that ship with crtr, not their source. */
+    scope: Exclude<Scope, 'builtin'>;
     root: string;
     manifest: MarketplaceManifest;
     url: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.184",
+  "version": "0.3.186",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.184",
+  "version": "0.3.186",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.184",
+      "version": "0.3.186",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/dist/core/runtime/broker/message-ledger.d.ts

@@ -1,53 +0,0 @@
-/** One id-bearing message the ledger tracks. */
-export interface LedgerEntry {
-    id: string;
-    text: string;
-}
-export declare class MessageIdLedger {
-    private steering;
-    private followUp;
-    private pendingIntents;
-    private stagedRetirementId;
-    private recent;
-    /** Record an accepted client frame's identity before its engine call runs.
-     *  `id` is the sender's `message_id` when it minted one, else broker-minted. */
-    noteDispatch(id: string, text: string): void;
-    /** Remove a noted intent whose engine call rejected — the message will never
-     *  appear in a queue or as a user message. No-op if already adopted. */
-    dropIntent(id: string): void;
-    /**
-     * Fold one pi `queue_update` into the ledger and return the id arrays
-     * parallel to its text arrays (total: every position gets an id).
-     *
-     * Per-queue positional diff against the mirrored entries: a text matching an
-     * old entry at-or-after the cursor keeps its id (everything skipped is
-     * removed); an unmatched text ADOPTS the first pending intent with equal
-     * text, else mints a fresh id. Exactly ONE removal across both queues is
-     * pi's per-message retirement (its queue_update precedes the user
-     * `message_start` it belongs to) and is staged for `takeUserMessageId`;
-     * 0 or >1 removals (an enqueue, clearQueue/dequeue, abort) stage nothing.
-     */
-    reconcileQueueUpdate(steering: readonly string[], followUp: readonly string[]): {
-        steeringIds: string[];
-        followUpIds: string[];
-    };
-    /**
-     * The id for a relayed user `message_start`, or undefined when this message
-     * carries none (an engine-command expansion, a text pi transformed, or a
-     * pre-ledger replay). A staged retirement wins — pi emitted its queue_update
-     * synchronously right before this message; otherwise the first pending
-     * intent with equal text (the idle-prompt case, which never touches a
-     * queue). Id-bearing results are remembered for `recentUserMessages`.
-     */
-    takeUserMessageId(messageText: string): string | undefined;
-    /** The last {@link MAX_RECENT} id-bearing user-message dispatches, oldest
-     *  first — the `welcome.recentUserMessages` payload. */
-    recentUserMessages(): Array<{
-        id: string;
-        text: string;
-    }>;
-    /** Session rebind/replacement: the mirrored queues, staged retirement, and
-     *  recent list all described the OLD session — drop everything. */
-    reset(): void;
-    private remember;
-}

package/dist/core/runtime/broker/message-ledger.js

@@ -1,143 +0,0 @@
-// message-ledger.ts — broker-owned message identity across pi's id-less queues.
-//
-// pi's steering/follow-up queues and user messages carry TEXT only: `steer()`
-// pushes bare strings, `queue_update` relays bare string arrays, and retirement
-// (on user `message_start`) is a first-index-of-text splice. Every downstream
-// consumer was therefore forced into order/text heuristics to match its own
-// optimistic send to the wake that echoed it — wrong under duplicates,
-// cross-surface sends, and reconnect replay.
-//
-// The broker is the ONLY writer to the engine (every prompt/steer/follow_up/
-// deliver funnels through driveEngine) and observes pi's event stream
-// synchronously in-process, so it can own identity at the wire boundary: mint
-// (or adopt the sender's) id per accepted frame, mirror pi's queue state by
-// reconciling pi's own `queue_update` events, and attach the retired entry's id
-// to the relayed user `message_start`. Same deterministic algorithm over the
-// same data in the same process as pi's own bookkeeping — it cannot drift.
-//
-// pi ordering facts this relies on (verified at pi 0.83.0, agent-session.js):
-//  - `_queueSteer`/`_queueFollowUp` push the text and emit `queue_update`
-//    synchronously inside the steer/followUp call.
-//  - On a queued message's user `message_start`, `_handleAgentEvent` splices
-//    the queue and emits `queue_update` BEFORE emitting the `message_start`,
-//    so a retirement's queue_update always precedes its message and two
-//    removals never interleave.
-//  - An idle `prompt()` never touches a queue — its user message matches a
-//    pending dispatch intent by text instead.
-import { randomUUID } from 'node:crypto';
-/** Dispatch intents not yet observed anywhere: bounded FIFO so an intent whose
- *  text pi transformed (and so never matches) cannot accumulate forever. */
-const MAX_PENDING_INTENTS = 32;
-/** Recent id-bearing user-message dispatches carried in `welcome` so a
- *  reattaching follower can key its snapshot's trailing user wakes. */
-const MAX_RECENT = 8;
-export class MessageIdLedger {
-    steering = [];
-    followUp = [];
-    pendingIntents = [];
-    stagedRetirementId = null;
-    recent = [];
-    /** Record an accepted client frame's identity before its engine call runs.
-     *  `id` is the sender's `message_id` when it minted one, else broker-minted. */
-    noteDispatch(id, text) {
-        this.pendingIntents.push({ id, text });
-        if (this.pendingIntents.length > MAX_PENDING_INTENTS)
-            this.pendingIntents.shift();
-    }
-    /** Remove a noted intent whose engine call rejected — the message will never
-     *  appear in a queue or as a user message. No-op if already adopted. */
-    dropIntent(id) {
-        const idx = this.pendingIntents.findIndex((e) => e.id === id);
-        if (idx !== -1)
-            this.pendingIntents.splice(idx, 1);
-    }
-    /**
-     * Fold one pi `queue_update` into the ledger and return the id arrays
-     * parallel to its text arrays (total: every position gets an id).
-     *
-     * Per-queue positional diff against the mirrored entries: a text matching an
-     * old entry at-or-after the cursor keeps its id (everything skipped is
-     * removed); an unmatched text ADOPTS the first pending intent with equal
-     * text, else mints a fresh id. Exactly ONE removal across both queues is
-     * pi's per-message retirement (its queue_update precedes the user
-     * `message_start` it belongs to) and is staged for `takeUserMessageId`;
-     * 0 or >1 removals (an enqueue, clearQueue/dequeue, abort) stage nothing.
-     */
-    reconcileQueueUpdate(steering, followUp) {
-        const removed = [];
-        const next = (old, texts) => {
-            const out = [];
-            let cursor = 0;
-            for (const text of texts) {
-                let match = -1;
-                for (let j = cursor; j < old.length; j++) {
-                    if (old[j].text === text) {
-                        match = j;
-                        break;
-                    }
-                }
-                if (match !== -1) {
-                    for (let j = cursor; j < match; j++)
-                        removed.push(old[j].id);
-                    out.push(old[match]);
-                    cursor = match + 1;
-                    continue;
-                }
-                const intentIdx = this.pendingIntents.findIndex((e) => e.text === text);
-                const id = intentIdx !== -1 ? this.pendingIntents.splice(intentIdx, 1)[0].id : randomUUID();
-                out.push({ id, text });
-            }
-            for (let j = cursor; j < old.length; j++)
-                removed.push(old[j].id);
-            return out;
-        };
-        this.steering = next(this.steering, steering);
-        this.followUp = next(this.followUp, followUp);
-        this.stagedRetirementId = removed.length === 1 ? removed[0] : null;
-        return {
-            steeringIds: this.steering.map((e) => e.id),
-            followUpIds: this.followUp.map((e) => e.id),
-        };
-    }
-    /**
-     * The id for a relayed user `message_start`, or undefined when this message
-     * carries none (an engine-command expansion, a text pi transformed, or a
-     * pre-ledger replay). A staged retirement wins — pi emitted its queue_update
-     * synchronously right before this message; otherwise the first pending
-     * intent with equal text (the idle-prompt case, which never touches a
-     * queue). Id-bearing results are remembered for `recentUserMessages`.
-     */
-    takeUserMessageId(messageText) {
-        const staged = this.stagedRetirementId;
-        if (staged !== null) {
-            this.stagedRetirementId = null;
-            this.remember(staged, messageText);
-            return staged;
-        }
-        const idx = this.pendingIntents.findIndex((e) => e.text === messageText);
-        if (idx === -1)
-            return undefined;
-        const intent = this.pendingIntents.splice(idx, 1)[0];
-        this.remember(intent.id, messageText);
-        return intent.id;
-    }
-    /** The last {@link MAX_RECENT} id-bearing user-message dispatches, oldest
-     *  first — the `welcome.recentUserMessages` payload. */
-    recentUserMessages() {
-        return this.recent.map((e) => ({ ...e }));
-    }
-    /** Session rebind/replacement: the mirrored queues, staged retirement, and
-     *  recent list all described the OLD session — drop everything. */
-    reset() {
-        this.steering = [];
-        this.followUp = [];
-        this.pendingIntents = [];
-        this.stagedRetirementId = null;
-        this.recent = [];
-    }
-    remember(id, text) {
-        this.recent.push({ id, text });
-        if (this.recent.length > MAX_RECENT)
-            this.recent.shift();
-    }
-}