@north-light/api 0.3.580 → 0.3.588

package/dist/commands/human/prompts.js

@@ -0,0 +1,326 @@
+import { envNodeId } from '../../shared/env.js';
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { join } from 'node:path';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { productComponents } from './components.js';
+import { preparePage } from '../../core/human/page-authoring.js';
+import { PageAuthoringError } from '../../core/human/page.js';
+import { isResponseBearingSlot, validateAuthoredPageManifest } from '../../core/human/page-schema.js';
+import { display } from '../../core/termrender/display.js';
+import { pageHelpText, resolveMaxPanes } from './shared.js';
+// Only `pageHint` is surface-independent; everything else this file reads off
+// PageHelpText is chosen per host, so the send leaf is built for a surface
+// rather than defined once as a const.
+const PAGE_HINT = pageHelpText().pageHint;
+/** The asking node's id, or null when run from a bare shell (no parent to route to). */
+function askingNode() {
+    return envNodeId() ?? null;
+}
+/** 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, 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 async function sender() {
+    const nodeId = askingNode();
+    if (nodeId === null || nodeId === '')
+        return { source: {}, lifecycle: null };
+    try {
+        const client = cliClient();
+        const node = await client.getNode(nodeId);
+        const sessionName = node.name.trim();
+        const profileName = node.profile_id === null
+            ? undefined
+            : (await client.getProfile(node.profile_id)).name;
+        return {
+            source: {
+                nodeId,
+                ...(sessionName === '' ? {} : { sessionName }),
+                ...(profileName === undefined ? {} : { profileName }),
+            },
+            lifecycle: node.lifecycle,
+        };
+    }
+    catch {
+        return { source: { nodeId }, lifecycle: null };
+    }
+}
+/** Delivery is two authored choices and one derived fact. Placement and inbox
+ * are the sender's to pick; `reply` is not a flag, because a page routes
+ * completion back exactly when it carries response-bearing components — the
+ * page's own shape decides it, and a sender who disagreed could only be wrong
+ * (inputs with no way to submit, or a bridge no response can settle).
+ *
+ * Skipping the inbox leaves the sender's own transcript as the page's only
+ * route to a human, so a terminal sender — a node that finishes, whose
+ * transcript nobody is watching — always projects to the inbox. */
+function deliveryFrom(input, responseBearing, senderLifecycle) {
+    const inbox = senderLifecycle === 'terminal'
+        ? true
+        : input['inbox'] === true
+            ? true
+            : input['noInbox'] === true
+                ? false
+                : responseBearing;
+    const placement = input['placement'] ?? 'inline';
+    return { placement, inbox, reply: responseBearing };
+}
+function submitAuthoredPage(submit) {
+    try {
+        return submit();
+    }
+    catch (error) {
+        if (!(error instanceof PageAuthoringError))
+            throw error;
+        throw new InputError({
+            error: 'invalid_page',
+            message: error.message,
+            field: 'page',
+            next: 'Fix the authored page and submit again; the reported location is in the authored `.tsx` source.',
+        });
+    }
+}
+/** The page a `--replace` names, read through crtrd for the routing it retains. */
+async function replacedPage(requestId) {
+    try {
+        const request = await cliClient().getHumanRequest(requestId);
+        if (request.kind !== 'page')
+            throw new InputError({ error: 'unknown_page', message: `no page ${requestId} on this canvas`, field: 'replace', next: 'Pass the page_id a previous send returned, or omit --replace to raise a new page.' });
+        return (await cliClient().getHumanInboxPage(request.inbox_ticket_id)).page;
+    }
+    catch (error) {
+        if (error instanceof InputError)
+            throw error;
+        rethrowAsCliError(error, 'Pass the page_id a previous send returned, or omit --replace to raise a new page.');
+    }
+}
+function writePipedPage(document) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-human-page-'));
+    const path = join(dir, 'page.tsx');
+    writeFileSync(path, document, { encoding: 'utf8', mode: 0o600 });
+    return { dir, path };
+}
+/** Resolve exactly one authored page input. Piped bytes are materialized so
+ * both input forms follow the same page preparation and validation path. */
+function pageInput(input) {
+    const file = input['page'];
+    const documentRaw = input['document'];
+    // Optional stdin arrives as an empty string when a caller redirects an empty
+    // stream. It is not a page source and must not conflict with --page.
+    const document = typeof documentRaw === 'string' && documentRaw.trim() !== '' ? documentRaw : undefined;
+    if (file !== undefined && document !== undefined) {
+        throw new InputError({
+            error: 'bad_invocation',
+            message: 'received both --page and a piped page document',
+            field: 'page, document',
+            next: 'Pass exactly one page source: --page PATH or the document on stdin.',
+        });
+    }
+    if (file === undefined && document === undefined) {
+        throw new InputError({
+            error: 'missing_parameter',
+            message: 'a page source is required',
+            field: 'page, document',
+            next: 'Pass exactly one page source: --page PATH or the document on stdin.',
+        });
+    }
+    if (file !== undefined) {
+        if (typeof file !== 'string')
+            throw new InputError({ error: 'invalid_type', message: '--page must be a path', field: 'page', next: 'Retry with --page PATH.' });
+        return { sourceFile: file };
+    }
+    if (typeof document !== 'string')
+        throw new InputError({ error: 'invalid_type', message: 'stdin must contain a page document', field: 'document', next: 'Pipe the page document on stdin.' });
+    const temp = writePipedPage(document);
+    return { sourceFile: temp.path, tempDir: temp.dir };
+}
+/** The non-blocking status peek returned by ask/review. How the human reaches
+ * their inbox is theirs, not the agent's — naming a shortcut here only teaches
+ * agents to repeat a screen-specific gesture back to a reader who may be on a
+ * different surface entirely. */
+function queuedFollowUp() {
+    return 'Queued for the user. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block.';
+}
+// send
+export function humanSend(pageSurface = false) {
+    const pageHelp = pageHelpText(pageSurface);
+    return defineLeaf({
+        name: 'send',
+        description: 'send a durable page with explicit delivery',
+        whenToUse: pageHelp.sendWhenToUse,
+        help: {
+            name: 'human send',
+            summary: pageHelp.sendSummary,
+            guide: 'Page authoring: `crtr human -h`.',
+            params: [
+                { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: pageHelp.stdinConstraint },
+                { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HINT} ${pageHelp.pageFlagConstraint}` },
+                { kind: 'flag', name: 'placement', type: 'enum', choices: ['inline', 'panel'], required: false, default: 'inline', constraint: "Where the page is delivered. inline renders in this conversation's transcript; panel opens from the inbox beside it." },
+                { kind: 'flag', name: 'inbox', type: 'bool', required: false, constraint: 'Project this page into the inbox. Mutually exclusive with --no-inbox.' },
+                { kind: 'flag', name: 'no-inbox', type: 'bool', required: false, constraint: "Do not project this page into the inbox, leaving this conversation's transcript as its only route to the user. Mutually exclusive with --inbox, and refused from a terminal node, whose transcript nobody reads once it finishes." },
+                { kind: 'flag', name: 'replace', type: 'string', required: false, constraint: 'Page id returned by an earlier send. Rewrites source in place while retaining its delivery and transcript anchor. Refused once the page is settled or canceled. Not combinable with delivery flags.' },
+            ],
+            output: [
+                { name: 'page_id', type: 'string', required: true, constraint: 'Identifier for the page; pass it as --replace to revise source in place.' },
+                { name: 'dir', type: 'string', required: true, constraint: pageHelp.dirConstraint },
+                { name: 'placement', type: 'inline | panel', required: true, constraint: 'Resolved page placement.' },
+                { name: 'inbox', type: 'boolean', required: true, constraint: 'Whether the page is projected into the inbox.' },
+                { name: 'reply', type: 'boolean', required: true, constraint: 'Whether completion is delivered to the asking request identity. Not a flag: true exactly when the page has response-bearing components.' },
+                { name: 'follow_up', type: 'string', required: true, constraint: 'What happens next; never instructs the caller to poll.' },
+            ],
+            outputKind: 'object',
+            effects: [
+                'Writes one durable page request. Inbox projection follows the delivery flags, except from a terminal node, which always projects; completion delivery follows the page\'s own components.',
+                "A display-only page's inbox entry is a notice, not a task: it clears itself once the person has actually seen the page, wherever they see it.",
+                'A reply-bearing page records the asking node on the request and delivers completion directly to that node.',
+                '--replace rewrites source in place while retaining delivery and emitted time; open surfaces reload it without creating another page.',
+            ],
+        },
+        run: async (input, context) => {
+            const { sourceFile, tempDir } = pageInput(input);
+            const replacePage = input['replace'];
+            const deliveryFlags = ['placement', 'inbox', 'noInbox'];
+            if (input['inbox'] === true && input['noInbox'] === true) {
+                throw new InputError({ error: 'bad_invocation', message: 'received conflicting delivery flags', field: 'inbox', next: 'Pass at most one of --inbox and --no-inbox.' });
+            }
+            if (replacePage !== undefined && deliveryFlags.some((flag) => context?.providedParams.has(flag) === true)) {
+                throw new InputError({ error: 'bad_invocation', message: '--replace cannot change delivery', field: 'replace', next: 'Remove delivery flags: replacement retains the page placement, inbox, reply, and emitted time.' });
+            }
+            try {
+                const productKinds = await productComponents();
+                if (replacePage !== undefined) {
+                    const prior = await replacedPage(replacePage);
+                    // The human's submit wins the race with a revision: once the ticket has
+                    // any terminal outcome, replacement is refused, and that refusal is the
+                    // reviser's signal that the ticket is closed.
+                    const existing = await cliClient().getHumanRequest(replacePage);
+                    if (existing.state !== 'pending') {
+                        throw new InputError({
+                            error: 'page_settled',
+                            message: `page ${replacePage} already has a terminal outcome`,
+                            field: 'replace',
+                            next: 'The page was answered or canceled; nothing on it can change now. Raise a new page if more is needed.',
+                        });
+                    }
+                    // A revision changes only the content. Identity, routing, and emitted
+                    // time stay the original sender's, so the prior source is inherited
+                    // verbatim — a fork revising the page must not repoint its provenance.
+                    const revised = submitAuthoredPage(() => preparePage({ sourceFile, source: prior.source, productKinds, delivery: prior.delivery }));
+                    const updated = await cliClient().replaceHumanRequest(replacePage, { page: { dialect: revised.manifest.dialect, source: revised.document } });
+                    return { page_id: replacePage, dir: updated.request_dir, ...prior.delivery, follow_up: 'Replaced in place. Every open surface reloads it; delivery and emitted time are unchanged.' };
+                }
+                const { source, lifecycle } = await sender();
+                // A terminal node finishes and its transcript stops being read, so the
+                // inbox is the only surface its page can still reach a human on. Refuse
+                // rather than quietly overriding the flag: the caller asked for a page
+                // nobody would ever see, and that is worth knowing.
+                if (lifecycle === 'terminal' && input['noInbox'] === true) {
+                    throw new InputError({
+                        error: 'invalid_page_delivery',
+                        message: 'a terminal node cannot send a page --no-inbox',
+                        field: 'inbox',
+                        next: 'Drop --no-inbox. This node finishes, and nobody reads a finished node\'s transcript, so a page kept out of the inbox reaches no one.',
+                    });
+                }
+                // Static extraction is an evaluation. Derive and validate delivery from this
+                // exact manifest so authored code runs once and cannot change between passes.
+                const prepared = submitAuthoredPage(() => preparePage({ sourceFile, source, productKinds }));
+                const responseBearing = prepared.manifest.slots.some(isResponseBearingSlot);
+                const delivery = deliveryFrom(input, responseBearing, lifecycle);
+                prepared.manifest = submitAuthoredPage(() => validateAuthoredPageManifest({ ...prepared.manifest, delivery }, productKinds));
+                if (!delivery.reply) {
+                    const created = await cliClient().createHumanRequest({
+                        page: { dialect: prepared.manifest.dialect, source: prepared.document },
+                        delivery,
+                        source: prepared.manifest.source,
+                        requester_node_id: null,
+                        creator_cwd: process.cwd(),
+                    });
+                    const dir = created.request_dir;
+                    // A page with no reply route carries no response-bearing components, so what the
+                    // follow-up must get right is where the person will meet it and how it
+                    // settles: an inline page is already in this conversation, and its
+                    // inbox entry is a notice that clears itself the moment the page has
+                    // actually been seen — an agent that points the person at their inbox
+                    // for a page on their screen sends them to an empty list.
+                    const followUp = delivery.placement === 'inline' && delivery.inbox
+                        ? 'Shown in this conversation and queued in the user\'s inbox.'
+                        : delivery.placement === 'inline'
+                            ? 'Shown in this conversation as passive page content with no inbox entry.'
+                            : delivery.inbox
+                                ? 'Queued in the inbox; it opens in the panel and waits until dismissed.'
+                                : 'Published as passive page content with no inbox or response lifecycle.';
+                    return { page_id: created.request_id, dir, ...delivery, follow_up: followUp };
+                }
+                const originNodeId = askingNode();
+                if (originNodeId === null || originNodeId === '') {
+                    throw new InputError({ error: 'no_requester', message: 'a response-bearing page must be sent from a crouter node', field: 'page', next: 'Run `crtr human send` from the node that should receive the answer.' });
+                }
+                const created = await cliClient().createHumanRequest({
+                    page: { dialect: prepared.manifest.dialect, source: prepared.document },
+                    delivery,
+                    source: prepared.manifest.source,
+                    requester_node_id: originNodeId,
+                    creator_cwd: process.cwd(),
+                });
+                return { page_id: created.request_id, dir: created.request_dir, ...delivery, follow_up: queuedFollowUp() };
+            }
+            finally {
+                if (tempDir !== undefined)
+                    rmSync(tempDir, { recursive: true, force: true });
+            }
+        },
+    });
+}
+// show (no job, non-blocking passthrough) — passive live document display, NOT
+// a ticket surface. `display()` puts a file live in a watch pane and never
+// enqueues anything.
+export const humanShow = defineLeaf({
+    name: 'show',
+    description: "put a file live on the user's screen",
+    whenToUse: 'displaying a doc on screen while the user comments',
+    help: {
+        name: 'human show',
+        summary: "put a file live on screen in a tmux pane with crouter's renderer",
+        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid). To put a rich document in front of the user as a durable inbox page, use `crtr human send --page PATH`; a page with no response-bearing components is a standalone announcement.',
+        params: [
+            { kind: 'positional', name: 'path', type: 'path', required: true, constraint: 'Path to the file to render.' },
+            { kind: 'flag', name: 'window', type: 'enum', choices: ['auto', 'split', 'new'], required: false, default: 'auto', constraint: 'Placement. Default auto.' },
+        ],
+        output: [
+            { name: 'pane_id', type: 'string | null', required: true, constraint: 'Tmux pane id, or null when not displayed.' },
+            { name: 'reason', type: 'string | null', required: true, constraint: 'Why no pane was created, or null on success.' },
+        ],
+        outputKind: 'object',
+        effects: ['Spawns a live-watch tmux pane when possible. No job. Always exits 0.'],
+    },
+    run: async (input) => {
+        const path = input['path'];
+        const windowArg = input['window'];
+        const window = windowArg !== undefined ? windowArg : 'auto';
+        // `human show` always reports display failures in its result rather than
+        // turning a passive screen surface into a failed agent turn.
+        try {
+            const result = display(path, { window, maxPanes: resolveMaxPanes() });
+            return result.paneId !== undefined
+                ? { pane_id: result.paneId, reason: null }
+                : { pane_id: null, reason: result.reason };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return { pane_id: null, reason: `display failed: ${reason}` };
+        }
+    },
+});

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

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

package/dist/commands/human/queue.js

@@ -0,0 +1,191 @@
+import { envNodeId } from '../../shared/env.js';
+import { ApiError } from '../../api/index.js';
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { paginate } from '../../core/pagination.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+async function fetchNodeRefs() {
+    return (await cliClient().listNodes()).map((node) => ({ node_id: node.node_id, name: node.name, cwd: node.cwd, parent: node.parent, status: node.status }));
+}
+function resolveConversation(asking, nodes) {
+    if (asking === undefined)
+        return undefined;
+    const byId = new Map(nodes.map((node) => [node.node_id, node]));
+    let current = asking;
+    const seen = new Set();
+    while (current.parent !== null && !seen.has(current.node_id)) {
+        seen.add(current.node_id);
+        const parent = byId.get(current.parent);
+        if (parent === undefined)
+            break;
+        current = parent;
+    }
+    return current;
+}
+function readableSourceLabel(source) {
+    const sessionName = source?.sessionName?.trim();
+    if (sessionName !== undefined && sessionName !== '')
+        return sessionName;
+    const askedBy = source?.askedBy?.trim();
+    return askedBy === '' ? undefined : askedBy;
+}
+function summarizeTicket(summary, nodes, byId) {
+    const asking = summary.source.nodeId === undefined ? undefined : byId.get(summary.source.nodeId);
+    const conversation = resolveConversation(asking, nodes);
+    const sourceLabel = readableSourceLabel(summary.source);
+    return {
+        ticket_id: summary.request_id,
+        dir: summary.request_dir,
+        title: summary.title,
+        subtitle: summary.subtitle ?? '',
+        kind: summary.kind,
+        ...(summary.kind === 'page' ? { emitted_at: summary.emitted_at } : { blocked_since: summary.blocked_since }),
+        ...(sourceLabel === undefined ? {} : { source_label: sourceLabel }),
+        ...(asking === undefined ? {} : { asking_node_id: asking.node_id, asking_node_name: asking.name, cwd: asking.cwd }),
+        ...(conversation === undefined ? {} : { conversation_id: conversation.node_id, conversation_title: conversation.name }),
+    };
+}
+async function requireInteraction(ticketId) {
+    try {
+        const request = await cliClient().getHumanRequest(ticketId);
+        return { request_id: request.request_id, kind: request.kind };
+    }
+    catch (error) {
+        if (!(error instanceof ApiError) || error.status !== 404)
+            rethrowAsCliError(error);
+    }
+    const ticket = (await cliClient().listHumanInbox()).tickets.find((item) => item.request_id === ticketId);
+    if (ticket === undefined)
+        throw new InputError({ error: 'not_found', message: `no interaction ticket: ${ticketId}`, field: 'ticket_id', next: 'Pass a ticket_id from `crtr human list`.' });
+    return { request_id: ticket.request_id, kind: ticket.kind };
+}
+function isAlreadySettled(error) {
+    return error instanceof ApiError && error.status === 409 && (error.code === 'already_settled' || error.code === 'review_terminal_conflict');
+}
+export const humanList = defineLeaf({
+    name: 'list',
+    description: 'enumerate pending interactions',
+    whenToUse: 'discovering what is blocked on the user',
+    help: {
+        name: 'human list',
+        summary: 'paginated list of pending interactions, oldest first',
+        params: [
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Default 20, max 100.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: "Opaque token from a previous response's next_cursor. Omit on first call." },
+        ],
+        output: [
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {ticket_id, dir, title, subtitle, kind, emitted_at? | blocked_since?}; pages use emitted_at, reviews use blocked_since. Enriched when derivable with claim_owner, source_label, asking_node_id/name, conversation_id/title. Oldest first.' },
+            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Pass on the next call to continue. null means no more items.' },
+            { name: 'total', type: 'integer | null', required: true, constraint: 'Total pending interactions.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const limit = Math.min(Math.max(1, input['limit']), 100);
+        const nodes = await fetchNodeRefs();
+        const byId = new Map(nodes.map((node) => [node.node_id, node]));
+        const items = (await cliClient().listHumanInbox()).tickets.map((summary) => summarizeTicket(summary, nodes, byId)).sort((a, b) => {
+            const left = `${a.emitted_at ?? a.blocked_since}|${a.ticket_id}`;
+            const right = `${b.emitted_at ?? b.blocked_since}|${b.ticket_id}`;
+            return left < right ? -1 : left > right ? 1 : 0;
+        });
+        const page = paginate(items, { limit, cursor: input['cursor'] }, {
+            defaultLimit: 20,
+            maxLimit: 100,
+            keyOf: (item) => `${item.emitted_at ?? item.blocked_since}|${item.ticket_id}`,
+            total: 'count',
+        });
+        return { items: page.items, next_cursor: page.next_cursor, total: page.total };
+    },
+});
+function parseResolveBody(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(error)}`, field: 'stdin', next: 'Pass {"responses":{"<component_id>":{...}}} on stdin.' });
+    }
+    if (typeof parsed.responses !== 'object' || parsed.responses === null || Array.isArray(parsed.responses)) {
+        throw new InputError({ error: 'invalid_field', message: 'responses must be an object keyed by the id of a response-bearing component', field: 'responses', next: 'Pass {"responses":{"<component_id>":{...}}}, or {"responses":{}} to acknowledge a page with no response-bearing components.' });
+    }
+    return parsed.responses;
+}
+export const humanResolve = defineLeaf({
+    name: 'resolve',
+    description: 'resolve one human page from stdin answers',
+    whenToUse: 'an API client or local tool is submitting answers for a pending human interaction.',
+    tier: 'hidden',
+    help: {
+        name: 'human resolve',
+        summary: 'resolve a pending page with the given answers',
+        params: [
+            { kind: 'positional', name: 'ticket_id', type: 'string', required: true, constraint: 'page_id from human send, or a page ticket_id from human list.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'JSON {responses:{<component_id>:{...}}} — one typed response object per response-bearing component of the page.' },
+        ],
+        output: [
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call completed the page.' },
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'Interaction request id.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'already_settled when resolved is false.' },
+        ],
+        outputKind: 'object',
+        effects: ['The daemon settles the request and directly delivers a reply-bearing completion to its asking node.'],
+    },
+    run: async (input) => {
+        const ticketId = input['ticket_id'];
+        const ticket = await requireInteraction(ticketId);
+        if (ticket.kind !== 'page')
+            throw new InputError({ error: 'not_found', message: `no page for interaction: ${ticketId}`, field: 'ticket_id', next: 'Pass a pending page ticket_id from `crtr human list`.' });
+        try {
+            await cliClient().respondHumanRequest(ticket.request_id, { responses: parseResolveBody(input['body']), actor: envNodeId() ?? 'human' });
+        }
+        catch (error) {
+            if (isAlreadySettled(error))
+                return { resolved: false, ticket_id: ticketId, reason: 'already_settled' };
+            rethrowAsCliError(error);
+        }
+        return { resolved: true, ticket_id: ticketId };
+    },
+});
+export const humanCancel = defineLeaf({
+    name: 'cancel',
+    description: 'retract a pending page/review',
+    whenToUse: 'a page or review went stale before the user completed it',
+    help: {
+        name: 'human cancel',
+        summary: 'retract a pending page or review',
+        params: [
+            { kind: 'positional', name: 'ticket_id', type: 'string', required: true, constraint: 'page_id returned by human send, or ticket_id returned by human list.' },
+            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Optional short note delivered to the asking node explaining why it was retracted.' },
+        ],
+        output: [
+            { name: 'canceled', type: 'boolean', required: true, constraint: 'True when the interaction was retracted; false when it was already terminal.' },
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The interaction request id.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'already_settled when canceled is false.' },
+        ],
+        outputKind: 'object',
+        effects: ['The daemon removes the request from the human inbox and directly notifies its asking node when it has one.'],
+    },
+    run: async (input) => {
+        const ticketId = input['ticket_id'];
+        const ticket = await requireInteraction(ticketId);
+        const reason = input['reason'];
+        const body = { ...(reason === undefined || reason === '' ? {} : { reason }), actor: envNodeId() ?? 'human' };
+        try {
+            if (ticket.kind === 'review')
+                await cliClient().cancelReview(ticket.request_id, body);
+            else
+                await cliClient().cancelHumanRequest(ticket.request_id, body);
+        }
+        catch (error) {
+            if (isAlreadySettled(error))
+                return { canceled: false, ticket_id: ticketId, reason: 'already_settled' };
+            rethrowAsCliError(error);
+        }
+        return { canceled: true, ticket_id: ticketId };
+    },
+    render: (result) => result['canceled'] === true
+        ? `Canceled human interaction ${result['ticket_id']} — it left the human inbox.`
+        : `Nothing to cancel for ${result['ticket_id']} — ${result['reason'] ?? 'nothing to cancel'}.`,
+});

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

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