@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { defineRoot, runCli } from './core/command.js';
-import { registerAgent } from './commands/agent.js';
-import { registerMode } from './commands/mode.js';
 import { registerSkill } from './commands/skill.js';
-import { registerJob } from './commands/job.js';
 import { registerPkg } from './commands/pkg.js';
 import { registerHuman } from './commands/human.js';
 import { registerSys } from './commands/sys.js';
+import { registerPush, registerFeed } from './commands/push.js';
+import { registerNode } from './commands/node.js';
+import { registerCanvas } from './commands/canvas.js';
+import { maybeBootRoot } from './core/runtime/front-door.js';
 import { maybeAutoUpdate } from './core/auto-update.js';
 import { ensureBootSkill, ensureOfficialMarketplace, ensureProjectScope, ensureSlashCommands } from './core/bootstrap.js';
 // Root owns only the tagline and globals. Every subtree's concept line,
@@ -20,15 +21,22 @@ const root = defineRoot({
         { name: '-h', desc: 'print help for any node — append to any subcommand path' },
     ],
     subtrees: [
-        registerAgent(),
-        registerMode(),
         registerSkill(),
         registerPkg(),
-        registerJob(),
         registerHuman(),
         registerSys(),
+        registerNode(),
+        registerPush(),
+        registerFeed(),
+        registerCanvas(),
     ],
 });
+// The front door: bare `crtr` (or `crtr [dir] ["prompt"]`) boots a resident
+// root node and execs pi in this terminal. Recognized subcommands fall through
+// to the normal dispatcher. Must run before anything that assumes a subcommand.
+if (maybeBootRoot(root, process.argv)) {
+    // bootRoot exec'd pi inline and exited; unreachable.
+}
 ensureOfficialMarketplace(process.argv);
 ensureBootSkill(process.argv);
 ensureSlashCommands(root, process.argv);

package/dist/commands/{mode.d.ts → attention.d.ts}

@@ -1,2 +1,2 @@
 import type { BranchDef } from '../core/command.js';
-export declare function registerMode(): BranchDef;
+export declare const attentionBranch: BranchDef;

package/dist/commands/attention.js

@@ -0,0 +1,152 @@
+// `crtr canvas attention` — aggregate pending human asks across the canvas.
+//
+// Pending asks are stored per-cwd by humanloop. This subtree surfaces two
+// views:
+//   count  — a single integer (stdout.count is parsed by nav chrome)
+//   list   — itemised entries with cwd, node id, and per-cwd ask count
+//
+// All three scope modes share the same underlying helpers in attention.ts:
+//   --node <id>   → countAsks(id)             (one cwd)
+//   --view <id>   → pendingAsksForView(id)     (sub-DAG from root)
+//   (neither)     → asksAcrossCanvas()         (whole canvas)
+//
+// Exported as a branch; `crtr canvas` (canvas.ts) mounts it.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode } from '../core/canvas/index.js';
+import { countAsks, pendingAsksForView, asksAcrossCanvas, } from '../core/canvas/attention.js';
+// ---------------------------------------------------------------------------
+// attention count
+// ---------------------------------------------------------------------------
+const attentionCount = defineLeaf({
+    name: 'count',
+    help: {
+        name: 'canvas attention count',
+        // stdout.count is parsed directly by the nav chrome — keep the contract.
+        summary: 'return the number of pending human asks; stdout.count is machine-parseable',
+        params: [
+            {
+                kind: 'flag',
+                name: 'node',
+                type: 'string',
+                required: false,
+                constraint: 'Count asks only for this node\'s cwd. Mutually exclusive with --view.',
+            },
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Sum asks for all nodes in the sub-DAG rooted at this id. Mutually exclusive with --node.',
+            },
+        ],
+        output: [
+            { name: 'count', type: 'integer', required: true, constraint: 'Total pending asks in the requested scope.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans humanloop interaction dirs.'],
+    },
+    run: async (input) => {
+        const nodeId = input['node'];
+        const viewId = input['view'];
+        if (nodeId !== undefined && viewId !== undefined) {
+            throw new InputError({
+                error: 'ambiguous_scope',
+                message: '--node and --view are mutually exclusive',
+                next: 'Use one of --node <id>, --view <id>, or neither (canvas-wide).',
+            });
+        }
+        if (nodeId !== undefined) {
+            // Validate node exists.
+            if (getNode(nodeId) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${nodeId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            return { count: countAsks(nodeId) };
+        }
+        if (viewId !== undefined) {
+            if (getNode(viewId) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            const items = pendingAsksForView(viewId);
+            const total = items.reduce((s, e) => s + e.count, 0);
+            return { count: total };
+        }
+        // Canvas-wide.
+        const items = asksAcrossCanvas();
+        const total = items.reduce((s, e) => s + e.count, 0);
+        return { count: total };
+    },
+});
+// ---------------------------------------------------------------------------
+// attention list
+// ---------------------------------------------------------------------------
+const attentionList = defineLeaf({
+    name: 'list',
+    help: {
+        name: 'canvas attention list',
+        summary: 'list nodes with pending human asks, grouped by cwd, oldest first',
+        params: [
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Scope the list to the sub-DAG rooted at this node id. Omit for canvas-wide.',
+            },
+        ],
+        output: [
+            {
+                name: 'items',
+                type: 'object[]',
+                required: true,
+                constraint: 'Each: {node_id, name, cwd, count}. One entry per distinct cwd with count > 0.',
+            },
+            { name: 'total', type: 'integer', required: true, constraint: 'Sum of counts across all entries.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans humanloop interaction dirs.'],
+    },
+    run: async (input) => {
+        const viewId = input['view'];
+        let items;
+        if (viewId !== undefined) {
+            if (getNode(viewId) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            items = pendingAsksForView(viewId);
+        }
+        else {
+            items = asksAcrossCanvas();
+        }
+        const total = items.reduce((s, e) => s + e.count, 0);
+        return { items, total };
+    },
+});
+// ---------------------------------------------------------------------------
+// Export — mounted under `crtr canvas`
+// ---------------------------------------------------------------------------
+export const attentionBranch = defineBranch({
+    name: 'attention',
+    help: {
+        name: 'canvas attention',
+        summary: 'aggregate pending human asks across the canvas',
+        model: 'Human asks are stored per-cwd by humanloop. `count` returns a single integer (stdout.count is parsed by nav chrome); `list` returns itemised entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide.',
+        children: [
+            { name: 'count', desc: 'total pending ask count (machine-parseable stdout.count)', useWhen: 'polling from a script or nav chrome' },
+            { name: 'list', desc: 'itemised list of cwds with pending asks', useWhen: 'finding which agents need a human response' },
+        ],
+    },
+    children: [attentionCount, attentionList],
+});

package/dist/commands/canvas.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerCanvas(): BranchDef;

package/dist/commands/canvas.js

@@ -0,0 +1,35 @@
+// `crtr canvas` — observe and supervise the whole graph.
+//
+// Where `node` operates on one node and `push`/`feed` are a node's own spine
+// I/O, `canvas` is the bird's-eye / supervisor surface over the entire canvas:
+// render the subscription forest (`dashboard`), see who is blocked on a human
+// (`attention`), bring a node back (`revive`), and manage the supervisor
+// process (`daemon`). It assembles leaves/branches the sibling command files
+// own, so each piece declares its own help one level down.
+import { defineBranch } from '../core/command.js';
+import { dashboardLeaf } from './dashboard.js';
+import { reviveLeaf } from './revive.js';
+import { attentionBranch } from './attention.js';
+import { daemonBranch } from './daemon.js';
+export function registerCanvas() {
+    return defineBranch({
+        name: 'canvas',
+        rootEntry: {
+            concept: 'the whole agent graph at a glance — render it, see who is blocked, revive a node, supervise the daemon',
+            desc: 'bird\'s-eye view and supervision of the entire canvas',
+            useWhen: 'surveying the full graph, finding blocked agents, or managing revival/the daemon',
+        },
+        help: {
+            name: 'canvas',
+            summary: 'observe and supervise the whole agent graph',
+            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead node; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit.',
+            children: [
+                { name: 'dashboard', desc: 'render the canvas as a subscription tree', useWhen: 'inspecting the whole graph at a glance' },
+                { name: 'attention', desc: 'count/list pending human asks across the graph', useWhen: 'checking whether any agent is blocked on a human' },
+                { name: 'revive', desc: 'reopen a window for a done/idle/dead node', useWhen: 'manually waking a node (the daemon does this automatically)' },
+                { name: 'daemon', desc: 'manage the crtrd supervisor process', useWhen: 'starting, checking, or stopping background supervision' },
+            ],
+        },
+        children: [dashboardLeaf, attentionBranch, reviveLeaf, daemonBranch],
+    });
+}

package/dist/commands/daemon.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare const daemonBranch: BranchDef;

package/dist/commands/daemon.js

@@ -0,0 +1,111 @@
+// `crtr canvas daemon` — thin supervisor daemon management.
+//
+// The daemon (crtrd) polls active+idle nodes and handles window exit:
+//   • crash (window gone, no intent) → mark 'dead'
+//   • refresh-yield (intent=refresh) → fresh respawn
+//
+// This subtree starts, checks, and stops the daemon process.
+import { defineLeaf, defineBranch } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { spawnDaemon } from '../daemon/manage.js';
+import { readPidfile, isPidAlive } from '../daemon/crtrd.js';
+// ---------------------------------------------------------------------------
+// daemon start
+// ---------------------------------------------------------------------------
+const daemonStart = defineLeaf({
+    name: 'start',
+    help: {
+        name: 'canvas daemon start',
+        summary: 'start the crtrd supervisor daemon in the background (no-op if already running)',
+        params: [],
+        output: [
+            { name: 'started', type: 'boolean', required: true, constraint: 'True when a new daemon process was spawned; false when one was already running.' },
+            { name: 'pid', type: 'number', required: false, constraint: 'PID of the newly spawned daemon.' },
+            { name: 'existing_pid', type: 'number', required: false, constraint: 'PID of the already-running daemon (when started=false).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Spawns dist/daemon/crtrd-cli.js detached + unref\'d; it outlives this process.',
+            'Writes a pidfile at crtrHome()/crtrd.pid.',
+        ],
+    },
+    run: async (_input) => {
+        const result = spawnDaemon();
+        return result;
+    },
+});
+// ---------------------------------------------------------------------------
+// daemon status
+// ---------------------------------------------------------------------------
+const daemonStatus = defineLeaf({
+    name: 'status',
+    help: {
+        name: 'canvas daemon status',
+        summary: 'check whether the crtrd supervisor daemon is currently running',
+        params: [],
+        output: [
+            { name: 'running', type: 'boolean', required: true, constraint: 'True when the daemon is alive.' },
+            { name: 'pid', type: 'number', required: false, constraint: 'PID of the running daemon.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads the pidfile and probes the pid.'],
+    },
+    run: async (_input) => {
+        const pid = readPidfile();
+        const running = pid !== null && isPidAlive(pid);
+        return running
+            ? { running: true, pid }
+            : { running: false };
+    },
+});
+// ---------------------------------------------------------------------------
+// daemon stop
+// ---------------------------------------------------------------------------
+const daemonStop = defineLeaf({
+    name: 'stop',
+    help: {
+        name: 'canvas daemon stop',
+        summary: 'send SIGTERM to the crtrd supervisor daemon',
+        params: [],
+        output: [
+            { name: 'stopped', type: 'boolean', required: true, constraint: 'True when a running daemon was signaled. False when no daemon was found.' },
+            { name: 'pid', type: 'number', required: false, constraint: 'PID that was signaled.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sends SIGTERM to the recorded pid; the daemon removes its pidfile on exit.'],
+    },
+    run: async (_input) => {
+        const pid = readPidfile();
+        if (pid === null || !isPidAlive(pid)) {
+            return { stopped: false };
+        }
+        try {
+            process.kill(pid, 'SIGTERM');
+            return { stopped: true, pid };
+        }
+        catch (err) {
+            throw new InputError({
+                error: 'kill_failed',
+                message: `failed to signal pid ${pid}: ${err.message}`,
+                next: 'The pidfile may be stale; remove ~/.crtr/crtrd.pid manually.',
+            });
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// Export — mounted under `crtr canvas`
+// ---------------------------------------------------------------------------
+export const daemonBranch = defineBranch({
+    name: 'daemon',
+    help: {
+        name: 'canvas daemon',
+        summary: 'manage the crtrd canvas supervisor daemon',
+        model: 'crtrd is a thin background daemon that polls active+idle nodes and acts on window exit: crashed windows become dead; refresh-yield windows get a fresh respawn. It holds no orchestration logic — just process supervision.',
+        children: [
+            { name: 'start', desc: 'start the daemon in the background', useWhen: 'bringing up the supervisor for the first time in a session' },
+            { name: 'status', desc: 'check whether the daemon is running', useWhen: 'verifying the daemon is up before spawning canvas nodes' },
+            { name: 'stop', desc: 'stop the running daemon', useWhen: 'shutting down supervision' },
+        ],
+    },
+    children: [daemonStart, daemonStatus, daemonStop],
+});

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const dashboardLeaf: LeafDef;

package/dist/commands/dashboard.js

@@ -0,0 +1,65 @@
+// `crtr canvas dashboard` — canvas-wide visibility surface.
+//
+// Renders the subscription sub-DAG as an ASCII tree, optionally scoped to a
+// single root.  A human operator pastes the output into a terminal or pipes it
+// to a renderer; a machine consumer reads the structured `rows` array.
+//
+// Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode, listNodes } from '../core/canvas/index.js';
+import { renderTree, renderForest, dashboardRows, dashboardRowsAll } from '../core/canvas/render.js';
+// ---------------------------------------------------------------------------
+// dashboard show — the main leaf
+// ---------------------------------------------------------------------------
+export const dashboardLeaf = defineLeaf({
+    name: 'dashboard',
+    help: {
+        name: 'canvas dashboard',
+        summary: 'render the canvas as an ASCII subscription tree — scoped to a root or the full forest',
+        params: [
+            {
+                kind: 'flag',
+                name: 'root',
+                type: 'string',
+                required: false,
+                constraint: 'Node id to use as the tree root. Omit for the full forest (all canvas roots).',
+            },
+        ],
+        output: [
+            { name: 'tree', type: 'string', required: true, constraint: 'Multi-line ASCII tree.' },
+            { name: 'nodes', type: 'integer', required: true, constraint: 'Total node count in this view.' },
+            { name: 'rows', type: 'object[]', required: true, constraint: 'One per node: {node_id,name,status,kind,mode,ctx_tokens,asks}.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: queries canvas.db and node telemetry files.'],
+    },
+    run: async (input) => {
+        const rootId = input['root'];
+        if (rootId !== undefined) {
+            // Scoped to a single root — validate the node exists.
+            const node = getNode(rootId);
+            if (node === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${rootId}`,
+                    next: 'List nodes with `crtr node inspect list` to find a valid id.',
+                });
+            }
+            const rows = dashboardRows(rootId);
+            return {
+                tree: renderTree(rootId),
+                nodes: rows.length,
+                rows,
+            };
+        }
+        // Full forest: all nodes on the canvas.
+        const allNodes = listNodes();
+        const rows = dashboardRowsAll();
+        return {
+            tree: renderForest(),
+            nodes: allNodes.length,
+            rows,
+        };
+    },
+});

package/dist/commands/human/prompts.d.ts

@@ -0,0 +1,5 @@
+export declare const humanAsk: import("../../core/command.js").LeafDef;
+export declare const humanApprove: import("../../core/command.js").LeafDef;
+export declare const humanReview: import("../../core/command.js").LeafDef;
+export declare const humanNotify: import("../../core/command.js").LeafDef;
+export declare const humanShow: import("../../core/command.js").LeafDef;