@north-light/crouter 0.3.197 → 0.3.199

package/dist/commands/canvas-browse.js

@@ -12,7 +12,7 @@ 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, `m` to message and `R` to rename a node in place, and `?` for the full keymap; 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',
+    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',

package/dist/commands/canvas-snapshot.js

@@ -15,7 +15,7 @@ export const canvasSnapshotLeaf = defineLeaf({
             { 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.'],
+        effects: ['Read-only: queries canvas.db, focus rows, telemetry files, and pending human-reply 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 },

package/dist/commands/canvas.js

@@ -43,7 +43,7 @@ export function registerCanvas() {
         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 remote-capable read commands such as `node inspect` onto a configured target or back to local.',
+            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 replies from the user 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 remote-capable read commands such as `node inspect` onto a configured target or back to local.',
         },
         children: [dashboardLeaf, canvasSnapshotLeaf, canvasRosterLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf, canvasConfigBranch, canvasUseLeaf],
     });

package/dist/commands/dashboard.js

@@ -15,7 +15,7 @@ import { renderTreeFromSource, renderForestFromSource, dashboardRowsFromSource,
 export const dashboardLeaf = defineLeaf({
     name: 'dashboard',
     description: 'render the canvas as a subscription tree',
-    whenToUse: 'you want the whole graph at a glance as a rendered tree — the subscription forest drawn in ASCII so you can read its SHAPE: who reports to whom, how deep each branch runs, plus each node\'s status and context size. Scope to one root or show the full forest. Use `node inspect list` instead for a flat roster without the tree, `node inspect show` to drill into one node\'s neighbors, and `canvas attention` to find which nodes are blocked on a human',
+    whenToUse: 'you want the whole graph at a glance as a rendered tree — the subscription forest drawn in ASCII so you can read its SHAPE: who reports to whom, how deep each branch runs, plus each node\'s status and context size. Scope to one root or show the full forest. Use `node inspect list` instead for a flat roster without the tree, `node inspect show` to drill into one node\'s neighbors, and `canvas attention` to find which nodes are blocked on the user',
     help: {
         name: 'canvas dashboard',
         summary: 'render the canvas as an ASCII subscription tree — scoped to a root or the full forest',

package/dist/commands/human/{doc.d.ts → components.d.ts}

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

package/dist/commands/human/components.js

@@ -0,0 +1,77 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { stateBlock } from '../../core/help.js';
+import { InputError } from '../../core/io.js';
+import { resolvePageComponents } from '../../core/config.js';
+import { componentNames, renderComponentCatalog, renderComponentContract } from '../../core/human/component-docs.js';
+function productComponents() {
+    return resolvePageComponents();
+}
+function componentNameState() {
+    const names = componentNames(productComponents());
+    return stateBlock('components', { count: names.length }, names.join(', '));
+}
+const humanComponentsList = defineLeaf({
+    name: 'list',
+    description: 'list page components for selection',
+    whenToUse: 'choosing which components to put in an authored page module.',
+    help: {
+        name: 'human components list',
+        summary: 'list page components for selection',
+        inputNote: 'No input parameters.',
+        output: [
+            { name: 'catalog', type: 'markdown', required: true, constraint: 'One concise selection entry per registry and product-registered component, grouped structural/response/display; no props or response schemas. A product component is written with the PascalCase tag derived from its registered kind.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Points to `crtr human components show <component>` for one selected component contract.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => ({
+        catalog: renderComponentCatalog(productComponents()),
+        follow_up: 'Use `crtr human components show <component>` for one component contract.',
+    }),
+    render: (result) => `${String(result['catalog'])}\n\n${String(result['follow_up'])}`,
+});
+const humanComponentsShow = defineLeaf({
+    name: 'show',
+    description: 'show one page component contract',
+    whenToUse: 'authoring one selected page component and needing its exact props, response contract, and shape in a page module.',
+    help: {
+        name: 'human components show',
+        summary: 'show one page component contract',
+        params: [
+            { kind: 'positional', name: 'component', type: 'string', required: true, constraint: 'Component name from the live <components> catalog below. Case-sensitive: registry components are PascalCase.' },
+        ],
+        output: [
+            { name: 'component', type: 'string', required: true, constraint: 'The selected component name.' },
+            { name: 'contract', type: 'markdown', required: true, constraint: 'Hand-written props, response contract, and authoring example for that component. A shadcn family (Card, CardHeader, …) shares one contract covering every member.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+        dynamicState: componentNameState,
+    },
+    run: async (input) => {
+        const component = input['component'];
+        const contract = renderComponentContract(component, productComponents());
+        if (contract === undefined) {
+            throw new InputError({
+                error: 'unknown_component',
+                message: `unknown page component "${component}"`,
+                field: 'component',
+                next: 'Run `crtr human components show -h` and choose a component from its live catalog.',
+            });
+        }
+        return { component, contract };
+    },
+    render: (result) => String(result['contract']),
+});
+export const humanComponents = defineBranch({
+    name: 'components',
+    description: 'discover page components and their contracts',
+    whenToUse: 'authoring a page module and choosing components, or needing one component’s exact props and response contract.',
+    help: {
+        name: 'human components',
+        summary: 'discover page components and their contracts',
+        model: 'These are the components already in scope in a page module — no import, ever. List is the selection catalog; show owns the full props, response contract, and authoring shape for one selected component.',
+    },
+    children: [humanComponentsList, humanComponentsShow],
+});

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

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

package/dist/commands/human/feedback.js

@@ -0,0 +1,108 @@
+// `crtr human feedback` — the feedback companion's surface for a page ticket's
+// feedback comments. list shows every item with its id and status; resolve is
+// the companion's terminal report that an open item has been dealt with.
+// Creating comments is the person's channel (the page surface); no agent
+// authors, edits, or deletes them.
+import { existsSync } from 'node:fs';
+import { ApiError } from '../../api/index.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { pageManifestPath } from '../../core/human/convention.js';
+import { opaqueInboxTicketId, ticketDir } from '../../core/human/root.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+/** Feedback tickets are addressed by the same raw ids as `human resolve`:
+ * the page_id from human send, which is also the ticket's directory name. */
+function requirePageTicketId(raw) {
+    const ticketId = raw;
+    if (!existsSync(pageManifestPath(ticketDir(ticketId)))) {
+        throw new InputError({ error: 'not_found', message: `no page ticket: ${ticketId}`, field: 'ticket_id', next: 'Pass the ticket id from your bearings, or a page ticket_id from `crtr human list`.' });
+    }
+    return ticketId;
+}
+const humanFeedbackList = defineLeaf({
+    name: 'list',
+    description: "list a page ticket's feedback comments",
+    whenToUse: 'you are the feedback companion for a page ticket and need each comment\'s id and open/resolved status.',
+    help: {
+        name: 'human feedback list',
+        summary: "every feedback comment on one page ticket, with ids and open/resolved status",
+        params: [
+            { kind: 'positional', name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id from your bearings (also the page_id from human send).' },
+        ],
+        output: [
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id.' },
+            { name: 'open_count', type: 'integer', required: true, constraint: 'How many comments remain open. Zero once feedback exists means all of it has been dealt with.' },
+            { name: 'comments', type: 'object[]', required: true, constraint: 'Each: {id, quote, context?, note, status, created_at, resolved_at?}; status is open or resolved. Oldest first.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const ticketId = requirePageTicketId(input['ticket_id']);
+        try {
+            const page = await cliClient().getHumanInboxPage(opaqueInboxTicketId(ticketId));
+            return { ticket_id: ticketId, open_count: page.feedback.open_count, comments: page.feedback.comments };
+        }
+        catch (e) {
+            rethrowAsCliError(e);
+        }
+    },
+});
+const humanFeedbackResolve = defineLeaf({
+    name: 'resolve',
+    description: 'mark one dealt-with feedback comment resolved',
+    whenToUse: 'you are the feedback companion and have dealt with an open comment — by revising the page or answering it in conversation.',
+    help: {
+        name: 'human feedback resolve',
+        summary: 'mark one open feedback comment resolved — terminal, and only after the feedback has actually been dealt with',
+        guide: 'Resolution is your report that the work is done, not a triage state: revise the page or answer the comment in conversation first, then resolve. It appends no chat turn — briefly report the result in the conversation yourself. A resolved comment never reopens; a renewed concern arrives as a new comment.',
+        params: [
+            { kind: 'positional', name: 'comment_id', type: 'string', required: true, constraint: 'A comment id from `crtr human feedback list`. The ticket is your own: it comes from the companion binding of the calling node.' },
+        ],
+        output: [
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call resolved the comment; false when it was already resolved.' },
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id.' },
+            { name: 'comment_id', type: 'string', required: true, constraint: 'The comment id.' },
+            { name: 'open_count', type: 'integer', required: false, constraint: 'Comments still open after this resolution. Present when resolved is true.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'comment_already_resolved when resolved is false.' },
+        ],
+        outputKind: 'object',
+        effects: ["Marks the comment resolved in your own ticket's feedback record — the ticket comes from the calling companion's binding. Only the ticket's bound companion may resolve — any other node refuses with not_companion. A terminal ticket refuses with ticket_terminal — settlement already closed this collaboration."],
+    },
+    run: async (input) => {
+        const commentId = input['comment_id'];
+        const callerNodeId = process.env['CRTR_NODE_ID'];
+        if (callerNodeId === undefined || callerNodeId === '') {
+            throw new InputError({ error: 'no_node', message: 'resolve runs inside the ticket\u2019s feedback companion (CRTR_NODE_ID unset)', next: 'Run this from the companion conversation bound to the ticket.' });
+        }
+        const binding = (await cliClient().getNode(callerNodeId)).review_binding;
+        if (binding === undefined || binding === null || binding.kind !== 'page_feedback') {
+            throw new InputError({ error: 'not_companion', message: 'this node is not a page-feedback companion — only the ticket\u2019s bound companion resolves its comments', next: 'Resolve from the companion conversation bound to the ticket.' });
+        }
+        const ticketId = requirePageTicketId(binding.review_id);
+        try {
+            const result = await cliClient().resolvePageFeedbackComment(opaqueInboxTicketId(ticketId), commentId, callerNodeId);
+            return { resolved: true, ticket_id: ticketId, comment_id: commentId, open_count: result.feedback.open_count };
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 409 && e.code === 'comment_already_resolved') {
+                return { resolved: false, ticket_id: ticketId, comment_id: commentId, reason: 'comment_already_resolved' };
+            }
+            rethrowAsCliError(e);
+        }
+    },
+    render: (r) => r['resolved'] === true
+        ? `Resolved feedback comment ${r['comment_id']} — ${r['open_count']} still open on ${r['ticket_id']}.`
+        : `Nothing to resolve for ${r['comment_id']} — ${r['reason']}.`,
+});
+export const humanFeedbackBranch = defineBranch({
+    name: 'feedback',
+    description: "operate on a page ticket's feedback comments",
+    whenToUse: "you are a feedback companion working a page ticket's feedback comments.",
+    help: {
+        name: 'human feedback',
+        summary: "a page ticket's feedback comments — the person creates them on the page; the bound companion lists and resolves them",
+        model: 'Each comment is immutable once sent and open until resolved. resolve is terminal and companion-only, taken after the feedback has been dealt with by revising the page or answering in conversation.',
+    },
+    children: [humanFeedbackList, humanFeedbackResolve],
+});

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

@@ -1,12 +1,21 @@
-import type { PageSource } from '../../core/human/page-schema.js';
+import { type PageSource } from '../../core/human/page-schema.js';
 /** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
  * directory, never ticket data; `nodeId` carries the originating node so a
  * consumer can relate a ticket back to whatever that node belongs to, and
- * `sessionName` is a presentation label only. Review tickets already stamp
- * `nodeId` the same way (`core/review/realize.ts`), so pages match them.
- * `nodeId` is stamped even when the daemon is unreachable — losing the label is
- * survivable, losing machine attribution is not. */
-export declare function sourceStamp(): Promise<PageSource>;
-export declare const humanAsk: import("../../core/command.js").LeafDef;
-export declare const humanNotify: import("../../core/command.js").LeafDef;
+ * `sessionName` is a presentation label only, while `profileName` lets product
+ * consumers resolve the applet or worker identity behind the ticket. Review
+ * tickets stamp the same provenance (`core/review/realize.ts`), so pages match
+ * them. `nodeId` is stamped even when the daemon is unreachable — losing the
+ * labels is survivable, losing machine attribution is not.
+ *
+ * The same read answers who is sending: `lifecycle` decides whether the sender
+ * has a transcript a human is plausibly reading, which is what makes skipping
+ * the inbox safe. It is null for a bare shell (no node at all) and when the
+ * daemon cannot answer — neither is a terminal sender, so neither restricts
+ * delivery. */
+export declare function sender(): Promise<{
+    source: PageSource;
+    lifecycle: 'terminal' | 'resident' | null;
+}>;
+export declare const humanSend: import("../../core/command.js").LeafDef;
 export declare const humanShow: import("../../core/command.js").LeafDef;