@north-light/api 0.3.580 → 0.3.588

package/dist/commands/canvas-analytics/view.js

@@ -0,0 +1,102 @@
+// The contract between the Analytics shell (shell.ts) and the tab views.
+//
+// The shell owns the frame (top rows, tab bar, coverage line, key line), the
+// request for data, the Loading/Empty/Error states, the Sources panel, the
+// project picker, and the minimum-size message. A view owns only the content
+// area of one tab, and only once a computation has succeeded with something in
+// it. Views are built once per loaded `AnalyticsDTO` — any `R`, `w`, or `p`
+// builds fresh views, so a view never has to reconcile two models — and keep
+// their cursor across tab switches while that model stands.
+//
+// Each tab module exports one factory the shell imports by name:
+//   overview.ts     createOverviewView(ctx)
+//   graphs.ts       createGraphsView(ctx)
+//   graph-detail.ts createGraphDetailView(ctx, graphId, selectAgentId?)
+//   time.ts         createTimeView(ctx)
+//   memory.ts       createMemoryView(ctx)
+//   usage.ts        createUsageView(ctx)
+//
+// Navigation API (ctx.nav):
+//   openTab(landing)          Switch to a tab, closing any open detail view, and
+//                             call that tab view's `land(landing)` so its cursor
+//                             lands where the Overview headline table says.
+//   openGraphDetail(graphId, selectAgentId?)
+//                             Open graph detail over the current view (the tab bar
+//                             shows Graphs); the cursor starts on `selectAgentId`,
+//                             else on the root. `Esc` there ('back') returns to the
+//                             view that opened it. Drilldowns on Time, Memory, and
+//                             Usage call this with the agent selected.
+//   openInspector(nodeId)     Hand the terminal to `crtr surface inspect <id> --read-only`
+//                             (read-only) and redraw the page when it exits.
+//   openConversation(nodeId)  Close the page and open the conversation the way the
+//                             canvas navigator does. The only key that may wake an
+//                             agent; label it "open, may wake it".
+//   readFinalReport(ref)      The text behind `final_report_ref`, through the same
+//                             /v1 read as `crtr canvas history read <ref>`.
+//   requestRender()           Redraw after an async result (e.g. readFinalReport).
+import { theme } from '../../core/tui/panel.js';
+import { formatCount } from './format.js';
+export const TABS = [
+    { id: 'overview', label: 'Overview' },
+    { id: 'graphs', label: 'Graphs' },
+    { id: 'time', label: 'Time' },
+    { id: 'memory', label: 'Memory' },
+    { id: 'usage', label: 'Usage' },
+];
+/** Content width at or above which the wide (v3) layout applies. */
+export const WIDE_MIN_WIDTH = 96;
+export const isNarrow = (width) => width < WIDE_MIN_WIDTH;
+/** Bar cells in the narrow layout. */
+export const NARROW_BAR_CELLS = 6;
+// How the wide layout scales. One rule for every tab:
+//   Width.  The page grows with the window up to MAX_PAGE_WIDTH columns; past
+//           that the shell centers it. Inside the page, a text column takes its
+//           natural width, at most half of the columns left after the number
+//           columns (`textWidth`), and the chart element beside it — a bar, a
+//           log axis, a timeline, a column chart — takes everything else, so
+//           every chart ends at the page's right edge. A list with no chart
+//           element keeps its numbers beside its names.
+//   Height. Lists show as many rows as fit; a column chart takes the rows
+//           left under the list above it, up to MAX_COLUMN_CHART_ROWS.
+/** Widest the page draws; a wider window centers it. */
+export const MAX_PAGE_WIDTH = 160;
+/** Tallest a column chart grows in a tall window. */
+export const MAX_COLUMN_CHART_ROWS = 16;
+/** A text column's width in the wide layout: its natural width, at least
+ *  `min` and at most half of `free` (the columns left once number columns are
+ *  placed). The chart element beside it gets `free − textWidth`. */
+export function textWidth(free, natural, min) {
+    return Math.max(min, Math.min(natural, Math.floor(free / 2)));
+}
+/** Row prefix: "> " on the cursor row, two spaces elsewhere. */
+export function cursorPrefix(selected) {
+    return selected ? '> ' : '  ';
+}
+/** A row on the cursor, marked by the "> " prefix and, where color exists, bold. */
+export function markRow(text, selected) {
+    return selected ? theme.bold(`> ${text}`) : `  ${text}`;
+}
+/** Which rows of a `count`-long list fit in `capacity` rows with the cursor
+ *  visible. When the list does not fit, the last visible row is spent on a
+ *  "<n> more <things> ↓" line (`more` is the count below the window). */
+export function listWindow(count, cursor, capacity) {
+    if (count <= capacity)
+        return { start: 0, end: count, more: 0 };
+    const rows = Math.max(1, capacity - 1);
+    const start = Math.max(0, cursor - rows + 1);
+    if (start + rows >= count)
+        return { start: Math.max(0, count - capacity), end: count, more: 0 };
+    return { start, end: start + rows, more: count - start - rows };
+}
+/** The "<n> more <things> ↓" row. */
+export function moreRow(more, things) {
+    return `  ${formatCount(more)} more ${things} ↓`;
+}
+/** A view that only names its tab — what each tab shows until its task builds it. */
+export function placeholderView(title) {
+    return {
+        render: () => [`${title}: not built yet.`],
+        handleKey: () => 'unhandled',
+        keyLine: () => '',
+    };
+}

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

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

package/dist/commands/canvas-analytics.js

@@ -0,0 +1,28 @@
+// The `crtr canvas analytics` leaf DEFINITION only. The page lives in
+// canvas-analytics/shell.ts and is loaded on demand: it pulls pi-tui and the
+// page host, which every other `crtr canvas …` invocation must not pay for.
+import { defineLeaf } from '../core/command.js';
+export const analyticsLeaf = defineLeaf({
+    name: 'analytics',
+    description: 'open the interactive Analytics page',
+    whenToUse: 'the user wants to see how agents worked in the last 24 hours or 7 days — graph sizes and spawned kinds, created → final report times, memory documents read, and where the API-price estimate and tokens went. It is a person-facing page for the tmux popup (prefix menu, shift+a); it has no non-interactive output for agents',
+    help: {
+        name: 'canvas analytics',
+        summary: 'open the read-only Analytics page — Overview, Graphs, Time, Memory, and Usage tabs over the last 24h or 7d',
+        params: [
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id that `o` opens a conversation beside (the prefix menu passes the pane it was opened from). Default: $TMUX_PANE.' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Opens a pi-tui page; crtrd computes every number (`GET /v1/canvas/analytics`). The page opens no database or transcript file.',
+            'Read-only. The one exception is `o` in graph detail, which closes the page and opens that agent’s conversation and may wake it.',
+            'Does not start crtrd: with the daemon unreachable the page shows the error and `R` retries.',
+            'Requires an interactive terminal. Without one it prints one line to stderr and exits 1.',
+        ],
+    },
+    run: async (input) => {
+        await (await import('./canvas-analytics/shell.js')).runAnalytics(input['pane']);
+    },
+    render: () => '',
+});

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

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

package/dist/commands/canvas-browse.js

@@ -0,0 +1,71 @@
+// `crtr canvas browse` — the interactive full-screen canvas navigator.
+//
+// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Attention/Pinned), an
+// auto-collapsed tree, and `/` fuzzy search. Enter resumes the chosen node via
+// `crtr surface node focus` (the ONLY sanctioned open — reviveNode, never `pi --session`).
+// Owns the screen, so it returns void and writes nothing to stdout itself.
+// Outside a TTY it prints the static forest and exits 0 (see runBrowse).
+import { envProfileId } from '../shared/env.js';
+import { defineLeaf } from '../core/command.js';
+import { runBrowse } from '../core/canvas/browse/app.js';
+import { ApiCanvasSource, cliClient } from './api-client.js';
+import { getDefaultProfileId } from '../core/profiles/default-binding.js';
+export const browseLeaf = defineLeaf({
+    name: 'browse',
+    description: 'open the interactive canvas navigator (tabs/tree/search)',
+    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Attention/Pinned), an expandable tree (children auto-collapsed; → to expand), `/` fuzzy search, `f` to pin, `y` to copy a node id, `m` to message and `R` to rename a node in place, and `?` for the full keymap; it opens on Live (active/idle) and Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
+    help: {
+        name: 'canvas browse',
+        summary: 'interactive full-screen canvas navigator — tabs, an auto-collapsed tree, and `/` fuzzy search; Enter resumes the chosen node via `crtr surface node focus`. Outside a TTY it prints the static forest and exits',
+        params: [
+            {
+                kind: 'flag',
+                name: 'return-pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id the chosen node REPLACES on Enter — that pane is respawned onto its viewer (set by the /resume popup, so resuming swaps the pane you invoked it from). Default: focus into this pane without replacing it.',
+            },
+            {
+                kind: 'flag',
+                name: 'cwd',
+                type: 'string',
+                required: false,
+                constraint: 'directory used when you toggle the optional cwd filter (c). The navigator opens with All dirs; /resume passes the launching node\'s cwd. Default: the invocation cwd.',
+            },
+            {
+                kind: 'flag',
+                name: 'profile-id',
+                type: 'string',
+                required: false,
+                constraint: 'Exact profile id for the initial profile filter (on by default; P toggles All profiles). Default: the launching node\'s profile via CRTR_PROFILE_ID, then this cwd\'s pinned default profile; absent means All profiles.',
+            },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Takes over the terminal in raw mode (alt-screen) until you quit (q/Esc) or pick a node.',
+            'On Enter: resumes the selected node via `crtr surface node focus` (reviveNode — the only sanctioned open).',
+            'Read-only on the canvas db; mutates nothing but the chosen node\'s placement on resume.',
+        ],
+    },
+    run: async (input) => {
+        const cwd = input['cwd'] ?? process.cwd();
+        const profileId = input['profileId'] ??
+            envProfileId() ??
+            getDefaultProfileId(cwd) ??
+            undefined;
+        const source = new ApiCanvasSource();
+        // The `x` close-out routes through the daemon API (browse `x` = finish the
+        // root to `done`); the callback keeps app.ts off the openDb-reaching
+        // runtime/close.js.
+        await runBrowse({
+            returnPane: input['returnPane'],
+            cwd,
+            profileId,
+            source,
+            viewedNodeIds: async () => new Set((await cliClient().listFocuses()).map((focus) => focus.node_id)),
+            contentSearch: (q) => cliClient().historySearch(q),
+            closeNode: (id) => cliClient().closeNode(id, process.ppid > 0 ? { finish: true, caller_pid: process.ppid } : { finish: true }).then((r) => ({ closed: r.closed })),
+        });
+    },
+});

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

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

package/dist/commands/canvas-config.js

@@ -0,0 +1,192 @@
+// `crtr canvas config` — register, list, inspect, and remove named remote
+// canvas targets (a preview endpoint + a relay token kept in the 0600
+// secrets store, never persisted to config.json or logged). `add` requires
+// `--relay-token -` (stdin-only) — a literal argv value is rejected with a
+// generic error (never echoing what was received, since it may be a real
+// secret) so the token can never land in shell history or process listings.
+// Selecting one for read commands is `crtr canvas use`, a sibling leaf, not a
+// child here.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError, readStdinRaw } from '../core/io.js';
+import { readConfig, updateConfig } from '../core/config.js';
+import { readSecrets, setRelayToken, deleteRelayToken, fingerprint } from '../core/secrets.js';
+const SCOPE = 'user';
+/** Masks one target's token presence/fingerprint from an ALREADY-loaded
+ *  `SecretsStore` — never re-reads/reparses `secrets.json` per target
+ *  (`list`/`show` load it once and pass it in here). */
+function maskedTarget(name, target, secrets) {
+    const token = secrets.relayTokens[target.relayTokenRef];
+    return {
+        name,
+        previewEndpoint: target.previewEndpoint,
+        relayTokenRef: target.relayTokenRef,
+        ...(target.cpOrigin ? { cpOrigin: target.cpOrigin } : {}),
+        tokenStored: token !== undefined && token !== '',
+        ...(token !== undefined && token !== '' ? { fingerprint: fingerprint(token) } : {}),
+    };
+}
+// canvas config add
+const canvasConfigAdd = defineLeaf({
+    name: 'add',
+    description: 'register a remote canvas target (preview endpoint + relay token)',
+    whenToUse: 'wiring up a remote canvas so `node inspect` or `surface attach --canvas` can reach it \u2014 stores the preview endpoint in config.json and the raw relay token in the 0600 secrets store (never together, never persisted to config.json or logged). Re-running with the same name overwrites both.',
+    help: {
+        name: 'canvas config add',
+        summary: 'register (or overwrite) a named remote canvas target',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name \u2014 the id every other `canvas config`/`canvas use`/`--canvas` reference uses.' },
+            { kind: 'flag', name: 'preview', type: 'string', required: true, constraint: 'The Blaxel preview endpoint base URL (e.g. https://<hash>.preview.bl.run).' },
+            { kind: 'flag', name: 'relay-token', type: 'string', required: true, constraint: 'Must be exactly `-` — the raw token is read from stdin, never argv (keeps it out of shell history). Any other value is rejected.' },
+            { kind: 'flag', name: 'cp', type: 'string', required: false, constraint: 'Optional control-plane origin, when this target has one distinct from the preview endpoint.' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: ['Writes remoteCanvas.targets.<name> to config.json (previewEndpoint, relayTokenRef, cpOrigin).', 'Writes the raw token to the 0600 secrets store under relayTokenRef \u2014 never to config.json or stdout.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const previewEndpoint = input['preview'];
+        const rawFlag = input['relayToken'];
+        const cp = input['cp'];
+        if (rawFlag !== '-') {
+            throw new InputError({
+                error: 'invalid_relay_token_arg',
+                message: 'relay token must be piped on stdin — pass `--relay-token -`',
+                field: 'relay-token',
+                next: 'Re-run with `--relay-token -` and pipe the raw token on stdin (e.g. `echo "$TOKEN" | crtr canvas config add <name> --preview <url> --relay-token -`).',
+            });
+        }
+        const token = (await readStdinRaw()).trim();
+        if (token === '') {
+            throw new InputError({
+                error: 'empty_token',
+                message: 'relay token is empty',
+                field: 'relay-token',
+                next: 'Pass a non-empty token, or `--relay-token -` and pipe it on stdin.',
+            });
+        }
+        const target = { previewEndpoint, relayTokenRef: name, ...(cp ? { cpOrigin: cp } : {}) };
+        await updateConfig(SCOPE, (cfg) => {
+            cfg.remoteCanvas.targets[name] = target;
+        });
+        setRelayToken(name, token, SCOPE);
+        return {};
+    },
+    render: () => 'Registered remote canvas target (token stored).',
+});
+// canvas config list
+const canvasConfigList = defineLeaf({
+    name: 'list',
+    description: 'list registered remote canvas targets',
+    whenToUse: 'checking which remote canvas targets exist before `canvas use`/`--canvas <name>` \u2014 never prints a raw token, only a non-reversible fingerprint.',
+    help: {
+        name: 'canvas config list',
+        summary: 'list every registered remote canvas target (masked \u2014 no raw tokens)',
+        output: [
+            {
+                name: 'targets',
+                type: 'object[]',
+                required: true,
+                constraint: 'Each: {name, previewEndpoint, relayTokenRef, cpOrigin?, tokenStored, fingerprint?}. fingerprint is a non-reversible sha256 prefix, present only when a token is stored.',
+            },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads config.json and the secrets-store token presence/fingerprint (never the raw token).'],
+    },
+    run: async () => {
+        const cfg = readConfig(SCOPE);
+        const secrets = readSecrets(SCOPE);
+        const targets = Object.entries(cfg.remoteCanvas.targets).map(([name, t]) => maskedTarget(name, t, secrets));
+        return { targets };
+    },
+    render: (r) => {
+        const targets = r['targets'];
+        if (targets.length === 0)
+            return 'No remote canvas targets configured.';
+        return targets
+            .map((t) => `${t['name']} — ${t['previewEndpoint']} (${t['tokenStored'] ? `token ${t['fingerprint']}` : 'no token stored'})`)
+            .join('\n');
+    },
+});
+// canvas config show
+const canvasConfigShow = defineLeaf({
+    name: 'show',
+    description: 'show one registered remote canvas target',
+    whenToUse: 'inspecting a single remote canvas target\u2019s config \u2014 masked the same way as `list`.',
+    help: {
+        name: 'canvas config show',
+        summary: 'show one remote canvas target (masked \u2014 no raw token)',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The target name.' },
+            { name: 'previewEndpoint', type: 'string', required: true, constraint: 'The stored preview endpoint.' },
+            { name: 'relayTokenRef', type: 'string', required: true, constraint: 'The secrets-store key holding the token.' },
+            { name: 'cpOrigin', type: 'string', required: false, constraint: 'The stored control-plane origin, when this target has one distinct from the preview endpoint.' },
+            { name: 'tokenStored', type: 'boolean', required: true, constraint: 'Whether a token is currently stored under relayTokenRef.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const cfg = readConfig(SCOPE);
+        const target = cfg.remoteCanvas.targets[name];
+        if (target === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`.',
+            });
+        }
+        return maskedTarget(name, target, readSecrets(SCOPE));
+    },
+    render: (r) => `${r['name']} — ${r['previewEndpoint']} (${r['tokenStored'] ? `token ${r['fingerprint']}` : 'no token stored'})`,
+});
+// canvas config remove
+const canvasConfigRemove = defineLeaf({
+    name: 'remove',
+    description: 'remove a registered remote canvas target and its stored token',
+    whenToUse: 'decommissioning a remote canvas target \u2014 drops it from config.json and deletes its raw token from the secrets store.',
+    help: {
+        name: 'canvas config remove',
+        summary: 'remove a remote canvas target and its stored token',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name.' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: ['Deletes remoteCanvas.targets.<name> from config.json.', 'Deletes the stored token under relayTokenRef from the secrets store.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const cfg = readConfig(SCOPE);
+        const target = cfg.remoteCanvas.targets[name];
+        if (target === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`.',
+            });
+        }
+        await updateConfig(SCOPE, (c) => {
+            delete c.remoteCanvas.targets[name];
+        });
+        deleteRelayToken(target.relayTokenRef, SCOPE);
+        return {};
+    },
+    render: () => 'Removed remote canvas target.'
+});
+// Export — mounted under `crtr canvas`
+export const canvasConfigBranch = defineBranch({
+    name: 'config',
+    description: 'register/list/inspect/remove remote canvas targets',
+    whenToUse: 'setting up or auditing a remote canvas target (preview endpoint + relay token) before selecting one with `crtr canvas use`.',
+    help: {
+        name: 'canvas config',
+        summary: 'manage named remote canvas targets',
+        model: 'A remote canvas target is a preview endpoint + a relay token registered under a name. `add` registers one (token goes to the 0600 secrets store, never config.json); `list`/`show` display masked entries (fingerprint only, never the raw token); `remove` deletes both the config entry and the stored token. Select a target for read commands with `crtr canvas use <name>`, or back to local with `crtr canvas use --local`.',
+    },
+    children: [canvasConfigAdd, canvasConfigList, canvasConfigShow, canvasConfigRemove],
+});

package/dist/commands/canvas-history/grep.d.ts

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

package/dist/commands/canvas-history/grep.js

@@ -0,0 +1,85 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
+export const grepLeaf = defineLeaf({
+    name: 'grep',
+    description: 'exact regex line search across the cwd\'s node history',
+    whenToUse: 'you know the exact string or pattern you\'re looking for — an error message, a literal identifier, a code fragment — and want every matching body LINE across every node that ran in this cwd, not a relevance ranking. The pattern is required (an ECMAScript regex, case-insensitive). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Want ranked/browse search instead? Use `canvas history search` — a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit\'s full body. Reports and documents are `crtr canvas search --grep`, not this.',
+    help: {
+        name: 'canvas history grep',
+        summary: 'required-pattern regex line search over past inboxes (default) and conversation transcripts in a cwd',
+        params: [
+            { kind: 'positional', name: 'pattern', required: true, constraint: 'An ECMAScript regex, matched case-insensitively against each body line. One hit per matching line.' },
+            ...filterParams,
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Page size. Default 20, hard max 100.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from a prior next_cursor; omit on the first call.' },
+        ],
+        output: [
+            { name: 'hits', type: 'object[]', required: true, constraint: '{ref, node, ts, line, text} per matching body line, sorted by ref then line. ref is the <node-id>:<relpath> handle passed verbatim to `canvas history read`.' },
+            { name: 'next_cursor', type: 'string|null', required: true, constraint: 'Token for the next page; null is the only end-of-list signal.' },
+            { name: 'total', type: 'int', required: true, constraint: 'Total matching lines (exact).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const pattern = (input['pattern'] ?? '').trim();
+        const limit = Math.min(100, Math.max(1, input['limit'] ?? 20));
+        const cursor = input['cursor'];
+        if (pattern === '')
+            throw usage('pattern is required — the regex to match against body lines.');
+        try {
+            const validate = new RegExp(pattern);
+            void validate;
+        }
+        catch {
+            throw usage(`invalid regex pattern: ${pattern}`);
+        }
+        // Filter flag validation stays client-side (pure); the corpus scan +
+        // regex match + pagination run server-side in crtrd (`POST
+        // /v1/canvas/history/grep`) — buildCorpus reaches canvas.db and loadBody
+        // closures cannot cross the wire.
+        const f = parseFilters(input);
+        const q = { pattern, limit };
+        applyFilters(q, f);
+        if (cursor !== undefined)
+            q.cursor = cursor;
+        try {
+            const res = await cliClient().historyGrep(q);
+            return {
+                hits: res.hits,
+                next_cursor: res.next_cursor,
+                total: res.total,
+                follow_up: 'Read a hit with `crtr canvas history read <ref>`; narrow with `crtr canvas history grep -h`.',
+            };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => renderGrep(r),
+});
+function renderGrep(r) {
+    const hits = r['hits'];
+    const total = r['total'];
+    const nextCursor = r['next_cursor'];
+    const parts = [];
+    if (hits.length === 0) {
+        parts.push('0 hits.');
+    }
+    else {
+        parts.push(`${hits.length} of ${total} hits:`);
+        const cols = Object.keys(hits[0]);
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = hits
+            .map((h) => `| ${cols.map((c) => String(h[c] ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ')} |`)
+            .join('\n');
+        parts.push(`${head}\n${sep}\n${body}`);
+    }
+    parts.push(`- next_cursor: ${nextCursor ?? 'null'}\n- total: ${total}`);
+    parts.push(String(r['follow_up']));
+    return parts.join('\n\n');
+}

package/dist/commands/canvas-history/read.d.ts

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

package/dist/commands/canvas-history/read.js

@@ -0,0 +1,48 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+export const readLeaf = defineLeaf({
+    name: 'read',
+    description: 'read one inbox entry or conversation message in full by its ref',
+    whenToUse: 'you picked a hit from `canvas history search` or `grep` and want its full content — pass the ref verbatim. Reports and documents are `crtr canvas read <name>`, not this.',
+    help: {
+        name: 'canvas history read',
+        summary: 'resolve an inbox or conversation ref to its full body',
+        params: [
+            { kind: 'positional', name: 'ref', required: true, constraint: 'A ref from `canvas history search`: <node-id>:inbox/<n> for one inbox entry, <node-id>:session for a node\'s whole conversation, <node-id>:session/<n> for one message in it.' },
+            { kind: 'flag', name: 'format', type: 'enum', choices: ['rendered', 'raw'], required: false, default: 'rendered', constraint: 'raw returns the verbatim bytes behind a conversation ref — the session .jsonl for <node-id>:session, the single persisted jsonl entry for one message. Use it when the rendered view may be hiding what you are chasing.' },
+        ],
+        output: [
+            { name: 'ref', type: 'string', required: true, constraint: 'Echo of the resolved ref.' },
+            { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
+            { name: 'source', type: 'string', required: true, constraint: 'inbox | transcript.' },
+            { name: 'ts', type: 'string', required: true, constraint: 'Entry or message timestamp.' },
+            { name: 'content', type: 'string', required: true, constraint: 'Full body.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const ref = input['ref'].trim();
+        const format = input['format'] ?? 'rendered';
+        // Fast local shape check; ref resolution (+ its not-found error) runs
+        // server-side in crtrd (`GET /v1/canvas/history/read`).
+        if (!ref.includes(':')) {
+            throw usage(`ref must be <node-id>:inbox/<n>, <node-id>:session, or <node-id>:session/<n>; received: ${ref}`, {
+                received: ref,
+                next: 'Get a valid ref from `crtr canvas history search`. Reports and documents are `crtr canvas read <name>`.',
+            });
+        }
+        try {
+            const res = await cliClient().historyRead({ ref, format });
+            return { ref: res.ref, node: res.node, source: res.source, ts: res.ts, content: res.content };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => {
+        const head = `${r['node']}  |  source: ${r['source']}  |  ts: ${r['ts']}  |  ref: ${r['ref']}`;
+        return `${head}\n\n${String(r['content']).trim()}`;
+    },
+});

package/dist/commands/canvas-history/search.d.ts

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