@north-light/crouter 0.3.154

package/dist/commands/canvas-roster.js

@@ -0,0 +1,62 @@
+import { defineLeaf } from '../core/command.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+export const canvasRosterLeaf = defineLeaf({
+    name: 'roster',
+    description: 'emit the lean canvas topology roster as structured data',
+    whenToUse: 'you need a fast, set-based roster of every canvas node + subscribes_to edges for a browser or viewer poll loop; use `canvas snapshot` for the enriched on-demand view (ctx tokens, streaming, hanging, last activity)',
+    tier: 'hidden',
+    help: {
+        name: 'canvas roster',
+        summary: 'lean, set-based canvas topology roster (recurring poll target)',
+        params: [],
+        output: [
+            { name: 'generated_at', type: 'string', required: true, constraint: 'ISO timestamp when the roster was generated.' },
+            {
+                name: 'nodes',
+                type: 'object[]',
+                required: true,
+                constraint: 'Lean node rows (no per-row meta.json read) plus attention_count for the returned node set.',
+            },
+            {
+                name: 'subscriptions',
+                type: 'object',
+                required: true,
+                constraint: 'Authoritative subscribes_to adjacency map: each node id maps to its publisher/child node ids in edge order.',
+            },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Read-only: two indexed canvas.db scans server-side (nodes, subscribes_to edges) plus a bounded attention-count read for the returned node ids.',
+        ],
+        // Machine-readable dump for the browser/attach roster poll, not for an
+        // agent/human to glance at — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async () => {
+        // The lean roster (rosterNodes + rosterEdges, exactly two indexed queries,
+        // no enrichRows/per-row getNode) is built server-side in crtrd
+        // (`GET /v1/canvas/roster`). Attention counts stay a SEPARATE bounded read
+        // (`POST /v1/canvas/attention/counts`) — never folded into the roster query
+        // itself, which must stay indexed-scan-only.
+        try {
+            const dto = await cliClient().canvasRoster();
+            const ids = dto.nodes.map((n) => n.node_id);
+            const counts = ids.length > 0 ? (await cliClient().attentionCounts(ids)).counts : {};
+            const nodes = dto.nodes.map((n) => ({ ...n, attention_count: counts[n.node_id] ?? 0 }));
+            const subscriptions = {};
+            for (const n of dto.nodes)
+                subscriptions[n.node_id] = [];
+            for (const e of dto.edges) {
+                const list = subscriptions[e.from_id];
+                if (list !== undefined)
+                    list.push(e.to_id);
+                else
+                    subscriptions[e.from_id] = [e.to_id];
+            }
+            return { generated_at: dto.generated_at, nodes, subscriptions };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+});

package/dist/commands/canvas-snapshot.d.ts

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

package/dist/commands/canvas-snapshot.js

@@ -0,0 +1,34 @@
+import { defineLeaf } from '../core/command.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+export const canvasSnapshotLeaf = defineLeaf({
+    name: 'snapshot',
+    description: 'emit the browser canvas roster as structured data',
+    whenToUse: 'you need a machine-readable roster of every canvas node for a browser or local tool; use dashboard for the human-readable tree',
+    tier: 'hidden',
+    help: {
+        name: 'canvas snapshot',
+        summary: 'machine-readable snapshot of the whole canvas roster',
+        params: [],
+        output: [
+            { name: 'generated_at', type: 'string', required: true, constraint: 'ISO timestamp when the snapshot was generated.' },
+            { name: 'nodes', type: 'object[]', required: true, constraint: 'NodeSummary rows for browser canvas rendering.' },
+            { name: 'subscriptions', type: 'object', required: true, constraint: 'Authoritative subscribes_to adjacency map: each node id maps to its publisher/child node ids in edge order.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: queries canvas.db, focus rows, telemetry files, and human ask counts.'],
+        // Machine-readable dump for the browser canvas, not for an agent/human to
+        // glance at — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async () => {
+        // The enriched roster (dashboardRowsAll + enrichRows) and the subscribes_to
+        // adjacency are built server-side in crtrd (`GET /v1/canvas/snapshot`).
+        try {
+            const dto = await cliClient().canvasSnapshot();
+            return { generated_at: dto.generated_at, nodes: dto.nodes, subscriptions: dto.subscriptions };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+});

package/dist/commands/canvas-use.d.ts

@@ -0,0 +1 @@
+export declare const canvasUseLeaf: import("../core/command.js").LeafDef;

package/dist/commands/canvas-use.js

@@ -0,0 +1,63 @@
+// `crtr canvas use` — durably select which canvas read commands
+// (`node inspect list/show`, `canvas browse`) default onto: a named remote
+// target, or back to local. A single leaf, not a branch — there is exactly
+// one decision here (pick a target, or go local), not a family of verbs.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { updateState } from '../core/config.js';
+import { getRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+const SCOPE = 'user';
+export const canvasUseLeaf = defineLeaf({
+    name: 'use',
+    description: 'select the durable default canvas for read commands (a remote target, or local)',
+    whenToUse: 'switching what `node inspect list/show` and `canvas browse` read from by default, without passing `--canvas <name>` on every invocation \u2014 select a remote target registered via `crtr canvas config add`, or switch back to local. A command\u2019s own `--canvas <name>` flag always overrides this for that one call.',
+    help: {
+        name: 'canvas use',
+        summary: 'select the durable default canvas (a registered remote target, or local) for read commands',
+        params: [
+            { kind: 'positional', name: 'name', required: false, constraint: 'A remote canvas target registered via `crtr canvas config add`. Mutually exclusive with --local; exactly one of the two is required.' },
+            { kind: 'flag', name: 'local', type: 'bool', required: false, constraint: 'Switch back to the local canvas. Mutually exclusive with <name>.' },
+        ],
+        output: [
+            { name: 'active', type: 'string', required: false, constraint: 'The now-active target name, or omitted/null for local.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes state.json\u2019s activeCanvas (user scope).'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const local = input['local'] === true;
+        if (name !== undefined && local) {
+            throw new InputError({
+                error: 'ambiguous_scope',
+                message: '<name> and --local are mutually exclusive',
+                next: 'Pass a target name to go remote, or --local to go local \u2014 not both.',
+            });
+        }
+        if (name === undefined && !local) {
+            throw new InputError({
+                error: 'missing_target',
+                message: 'nothing to select \u2014 pass a target name or --local',
+                next: 'Pass a target name (see `crtr canvas config list`) to go remote, or --local to go local.',
+            });
+        }
+        if (local) {
+            updateState(SCOPE, (s) => {
+                s.activeCanvas = null;
+            });
+            return { active: null };
+        }
+        if (getRemoteCanvasTarget(name, SCOPE) === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`, or register one with `crtr canvas config add`.',
+            });
+        }
+        updateState(SCOPE, (s) => {
+            s.activeCanvas = name;
+        });
+        return { active: name };
+    },
+    render: (r) => (r['active'] ? `Active canvas: ${r['active']}.` : 'Active canvas: local.'),
+});

package/dist/commands/canvas.d.ts

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

package/dist/commands/canvas.js

@@ -0,0 +1,50 @@
+// `crtr canvas` — observe and supervise the whole graph.
+//
+// Where `node` operates on one node and `push` is a node's own spine write
+// verb, `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`), and mass-reconnect disconnected nodes (`revive --all`). 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 { canvasSnapshotLeaf } from './canvas-snapshot.js';
+import { canvasRosterLeaf } from './canvas-roster.js';
+import { browseLeaf } from './canvas-browse.js';
+import { reviveLeaf } from './revive.js';
+import { attentionBranch } from './attention.js';
+import { chordLeaf } from './chord.js';
+import { canvasPruneLeaf } from './canvas-prune.js';
+import { canvasRebuildIndexLeaf } from './canvas-rebuild-index.js';
+import { historyBranch } from './canvas-history.js';
+import { issueNewLeaf } from './canvas-issue.js';
+import { canvasConfigBranch } from './canvas-config.js';
+import { canvasUseLeaf } from './canvas-use.js';
+export const issueBranch = defineBranch({
+    name: 'issue',
+    description: 'capture a quick todo/idea/bug into a GitHub issue (or a .todos/ note)',
+    whenToUse: 'the alt+c \u2192 i chord uses this; capture a passing thought without leaving your pane',
+    tier: 'hidden',
+    help: {
+        name: 'canvas issue',
+        summary: 'capture a quick todo/idea/bug into a GitHub issue',
+        model: 'Quick brain-dump capture, bound to the alt+c \u2192 i \u2192 (idea|bug) prefix chord. `new` reads a free-text note, auto-generates the title via a headless pi call, and files it with `gh issue create --label <type>` when the pane\u2019s cwd is a GitHub repo, else writes `<git-root>/.todos/<slug>.md`. Meant for the chord/popup, not hand-running.',
+    },
+    children: [issueNewLeaf],
+});
+export function registerCanvas() {
+    return defineBranch({
+        name: 'canvas',
+        rootEntry: {
+            concept: 'the whole agent graph at a glance — render it, see who is blocked, mass-revive disconnected nodes, and find or re-read prior node reports/context artifacts',
+            desc: 'bird\'s-eye view, supervision, and report/artifact history for the entire canvas',
+            useWhen: 'surveying the full graph, finding blocked agents, mass-reviving every disconnected node, or finding/re-reading prior reports/artifacts; run `crtr canvas -h`',
+        },
+        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 write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL. `config` registers/lists remote canvas targets (preview endpoint + relay token); `use` switches read commands (`node inspect`, `browse`) onto a configured remote target or back to local.',
+        },
+        children: [dashboardLeaf, canvasSnapshotLeaf, canvasRosterLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf, canvasConfigBranch, canvasUseLeaf],
+    });
+}

package/dist/commands/chord.d.ts

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

package/dist/commands/chord.js

@@ -0,0 +1,242 @@
+// `crtr canvas chord` — the tmux prefix-menu dispatcher.
+//
+// The alt+c display-menu can't see the cursor node or read config at popup time
+// — it only knows the active pane. So the menu hands this leaf a resolved `--run`
+// string plus the originating pane id; this dispatcher resolves the node in that
+// pane, interpolates the node vars, and execs `crtr <argv>` with no shell.
+//
+// execFile/spawn (never `sh -c`) keeps the argv literal, so shell metacharacters
+// in config data cannot inject.
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliCanvasSource, getNodeOrNull } from './api-client.js';
+import { fullName } from '../core/canvas/labels.js';
+import { getPaneOption } from '../core/runtime/tmux-chrome.js';
+const pexec = promisify(execFile);
+/** The live node whose viewer pane carries the `@crtr_node` tag. Reimplemented
+ *  here rather than importing node.ts's `nodeInPane` (which reaches openDb via the
+ *  canvas accessors) so this dispatcher's import graph stays db-free. Under the
+ *  headless-broker model every engine runs DETACHED (window=null), so the pane tag
+ *  is the ONLY node handle — the window→node fallback in node.ts's variant only ever
+ *  matched legacy in-pane engines, which no longer exist. A stale tag is ignored
+ *  (the tagged node must still be live), validated through the daemon API. */
+async function nodeInPane(pane) {
+    if (pane === undefined || pane === '')
+        return undefined;
+    const tagged = getPaneOption(pane, '@crtr_node');
+    if (tagged === undefined || tagged === '')
+        return undefined;
+    const meta = await getNodeOrNull(tagged);
+    if (meta !== null && (meta.status === 'active' || meta.status === 'idle'))
+        return tagged;
+    return undefined;
+}
+/** Template vars available to a `run` string. Single-valued vars interpolate
+ *  in place (preserving spaces, e.g. a node name); `{pane}` is the active tmux
+ *  pane id; `{subtree}` is multi-valued and a bare `{subtree}` token expands to
+ *  several argv elements. */
+async function buildVars(selfId, pane) {
+    const source = cliCanvasSource();
+    const [node, subs, viewIds] = await Promise.all([
+        source.getNode(selfId),
+        source.subscribersOf(selfId),
+        source.view(selfId),
+    ]);
+    const manager = subs[0]?.node_id ?? '';
+    return {
+        id: selfId,
+        self: selfId,
+        pane,
+        lane: selfId,
+        name: node !== null ? fullName(node) : selfId,
+        manager,
+        subtree: viewIds.join(' '),
+    };
+}
+function parseRun(run) {
+    const out = [];
+    let cur = '';
+    let quoted = null;
+    let escaped = false;
+    let inToken = false;
+    const push = () => {
+        if (!inToken)
+            return;
+        out.push(cur);
+        cur = '';
+        inToken = false;
+    };
+    for (let i = 0; i < run.length; i++) {
+        const ch = run[i];
+        if (escaped) {
+            cur += ch;
+            inToken = true;
+            escaped = false;
+            continue;
+        }
+        if (quoted === 'single') {
+            if (ch === "'") {
+                quoted = null;
+            }
+            else {
+                cur += ch;
+                inToken = true;
+            }
+            continue;
+        }
+        if (quoted === 'double') {
+            if (ch === '"') {
+                quoted = null;
+            }
+            else if (ch === '\\') {
+                escaped = true;
+            }
+            else {
+                cur += ch;
+                inToken = true;
+            }
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            push();
+            continue;
+        }
+        if (ch === "'") {
+            quoted = 'single';
+            inToken = true;
+            continue;
+        }
+        if (ch === '"') {
+            quoted = 'double';
+            inToken = true;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+            inToken = true;
+            continue;
+        }
+        cur += ch;
+        inToken = true;
+    }
+    if (escaped) {
+        cur += '\\';
+        inToken = true;
+    }
+    if (quoted !== null) {
+        throw new InputError({
+            error: 'bad_run',
+            message: 'invalid canvas run string: unterminated quote',
+            next: 'Fix the bind in config.json and try again.',
+        });
+    }
+    push();
+    return out;
+}
+/** Split a `run` string argv-style and interpolate the template vars. A bare
+ *  `{subtree}` token expands to several argv elements; every other placeholder
+ *  is substituted in place (kept as one element so a multi-word name survives
+ *  as a single argument under execFile). */
+function interpolateArgv(run, vars) {
+    const out = [];
+    for (const tok of parseRun(run)) {
+        if (tok === '{subtree}') {
+            for (const part of (vars['subtree'] ?? '').split(/\s+/).filter((p) => p !== ''))
+                out.push(part);
+            continue;
+        }
+        out.push(tok.replace(/\{(\w+)\}/g, (_, name) => vars[name] ?? ''));
+    }
+    return out;
+}
+async function dispatch(argv, interactive) {
+    if (argv.length === 0)
+        return;
+    if (interactive) {
+        await new Promise((resolve) => {
+            try {
+                const child = spawn('crtr', argv, { stdio: 'inherit' });
+                child.once('error', () => resolve());
+                child.once('close', () => resolve());
+            }
+            catch {
+                resolve();
+            }
+        });
+        return;
+    }
+    try {
+        await pexec('crtr', argv, { timeout: 15_000 });
+    }
+    catch {
+        /* best-effort: the keystroke just acts; errors are surfaced by the inner cmd */
+    }
+}
+export const chordLeaf = defineLeaf({
+    name: 'chord',
+    description: 'tmux prefix-menu dispatcher (bound by alt+c; not run by hand)',
+    whenToUse: 'never directly — the alt+c menu routes node-relative actions through it',
+    tier: 'hidden',
+    help: {
+        name: 'canvas chord',
+        summary: 'tmux prefix-menu dispatcher — resolve the node in --pane, interpolate --run against it, and exec `crtr <argv>`. Bound by the alt+c menu; not meant to be run by hand.',
+        params: [
+            {
+                kind: 'flag',
+                name: 'pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id whose node the chord acts on. Defaults to $TMUX_PANE / your current pane.',
+            },
+            {
+                kind: 'flag',
+                name: 'run',
+                type: 'string',
+                required: true,
+                constraint: 'The argv string to run as crtr, after node vars resolve.',
+            },
+            {
+                kind: 'flag',
+                name: 'interactive',
+                type: 'bool',
+                required: false,
+                constraint: 'When true, inherit stdio so popup forms can read from the popup tty.',
+            },
+        ],
+        output: [
+            { name: 'ran', type: 'boolean', required: true, constraint: 'True when an action was dispatched.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The node the chord resolved against.' },
+            { name: 'action', type: 'string', required: false, constraint: 'What ran: a crtr argv string or "noop".' },
+        ],
+        outputKind: 'object',
+        effects: ['Runs a `crtr` subcommand per the resolved bind.'],
+    },
+    run: async (input) => {
+        const rawPane = input['pane'];
+        const pane = rawPane !== undefined && rawPane !== '' ? rawPane : process.env['TMUX_PANE'];
+        const run = input['run']?.trim();
+        const interactive = input['interactive'] === true;
+        if (run === undefined || run === '') {
+            throw new InputError({
+                error: 'missing_run',
+                message: 'no run string provided',
+                next: 'Pass --run <argv-string> from the menu renderer.',
+            });
+        }
+        const selfId = await nodeInPane(pane);
+        if (selfId === undefined) {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no node found in this pane',
+                next: 'Run from inside an agent\'s pane, or pass --pane <pane-id>.',
+            });
+        }
+        const argv = interpolateArgv(run, await buildVars(selfId, pane ?? ''));
+        if (argv.length === 0)
+            return { ran: false, node_id: selfId, action: 'noop' };
+        await dispatch(argv, interactive);
+        return { ran: true, node_id: selfId, action: `crtr ${argv.join(' ')}` };
+    },
+});

package/dist/commands/cron.d.ts

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