@north-light/api 0.3.579 → 0.3.587

package/dist/commands/human/request.js

@@ -0,0 +1,266 @@
+// `crtr human request` — the command-line face of the durable programmatic
+// request contract. A request is an ordinary page ticket in the human inbox
+// whose creator may exit immediately: there is no reply bridge, the terminal
+// result is durable, and an optional named action carries the completion
+// document to a local command. Every leaf is a thin typed call on crtrd; the
+// daemon owns validation, settlement, and delivery.
+import { existsSync, readFileSync } from 'node:fs';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+// shared input helpers
+function readJsonFile(path, field, shape) {
+    if (!existsSync(path)) {
+        throw new InputError({ error: 'not_found', message: `no such file: ${path}`, field, next: `Pass --${field} PATH pointing at a JSON file holding ${shape}.` });
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new InputError({ error: 'unreadable_file', message: `could not read ${path}: ${String(error)}`, field, next: 'Pass a readable JSON file.' });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new InputError({ error: 'invalid_json', message: `${path} is not valid JSON: ${String(error)}`, field, next: `Write ${shape} into the file as JSON.` });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new InputError({ error: 'invalid_field', message: `${path} must hold a JSON object`, field, next: `Write ${shape} into the file as a JSON object.` });
+    }
+    return parsed;
+}
+/** The page crosses the wire inline, so the CLI reads the authored file and
+ *  derives its dialect from the extension — the same rule page authoring uses. */
+function readPageFile(path) {
+    const html = /\.html?$/i.test(path);
+    if (!html && !path.endsWith('.tsx')) {
+        throw new InputError({ error: 'invalid_field', message: `page source file must be .tsx, .html, or .htm: ${path}`, field: 'page', next: 'Author the page as a .tsx module or a complete .html document.' });
+    }
+    if (!existsSync(path)) {
+        throw new InputError({ error: 'not_found', message: `page source file does not exist: ${path}`, field: 'page', next: 'Pass --page PATH pointing at the authored page.' });
+    }
+    return { dialect: html ? 'html' : 'jsx', source: readFileSync(path, 'utf8') };
+}
+function requestId(input) {
+    const id = typeof input['request_id'] === 'string' ? input['request_id'].trim() : '';
+    if (id === '') {
+        throw new InputError({ error: 'missing_request_id', message: 'a request id is required', field: 'request_id', next: 'Pass the request_id returned by `crtr human request create`.' });
+    }
+    return id;
+}
+/** The one projection of a request record onto leaf output. Absent fields stay
+ *  absent: a dismissal or a withdrawal has no responses to report. */
+function requestResult(dto, includeRequestId = true) {
+    return {
+        ...(includeRequestId ? { request_id: dto.request_id } : {}),
+        state: dto.state,
+        title: dto.title,
+        ...(dto.subtitle === undefined ? {} : { subtitle: dto.subtitle }),
+        source: dto.source,
+        emitted_at: dto.emitted_at,
+        ...(dto.settled_at === undefined ? {} : { settled_at: dto.settled_at }),
+        ...(dto.responses === undefined ? {} : { responses: dto.responses }),
+        ...(dto.reason === undefined ? {} : { reason: dto.reason }),
+        ...(dto.actor === undefined ? {} : { actor: dto.actor }),
+        ...(dto.action === undefined ? {} : { action: dto.action }),
+        ...(dto.delivery === undefined ? {} : { delivery: dto.delivery }),
+    };
+}
+const REQUEST_RESULT_OUTPUT = [
+    { name: 'state', type: 'pending | answered | dismissed | canceled', required: true, constraint: 'answered: the person (or an authorized responder) submitted the typed responses. dismissed: the recipient surface closed it unanswered. canceled: the requester withdrew it.' },
+    { name: 'title', type: 'string', required: true, constraint: 'Page title as currently published.' },
+    { name: 'subtitle', type: 'string', required: false, constraint: 'Page subtitle when the page carries one.' },
+    { name: 'source', type: 'object', required: true, constraint: 'Stored provenance from the request creator: sessionName?, askedBy?, emittedAt?, profileName?, nodeId?.' },
+    { name: 'emitted_at', type: 'string', required: true, constraint: 'UTC ISO instant of creation; a replace never changes it.' },
+    { name: 'settled_at', type: 'string', required: false, constraint: 'UTC ISO instant of the terminal result. Absent while pending.' },
+    { name: 'responses', type: 'object', required: false, constraint: 'The typed slot map, keyed by response-bearing component id. Present only when state is answered.' },
+    { name: 'reason', type: 'string', required: false, constraint: 'Note recorded by the dismissal or the withdrawal.' },
+    { name: 'actor', type: 'string', required: false, constraint: 'Who settled it, when the settling surface named itself.' },
+    { name: 'action', type: 'object', required: false, constraint: '{name, payload} frozen at creation; an omitted payload is frozen as null. Absent when no action is bound.' },
+    { name: 'delivery', type: 'object', required: false, constraint: 'Completion-delivery state for the bound action: {state: none | pending | running | accepted | permanent_failed, attempt, next_attempt_at?, accepted_at?, permanent_failed_at?, last_failure?}. Absent when no action is bound.' },
+];
+const RECORD_OUTPUT = [
+    { name: 'request_id', type: 'string', required: true, constraint: 'The request — the same 64-hex id the human inbox lists it under.' },
+    ...REQUEST_RESULT_OUTPUT,
+];
+// create
+const createLeaf = defineLeaf({
+    name: 'create',
+    description: 'create a durable request from a JSON request file',
+    whenToUse: 'a script or backend needs a human decision that must survive its own exit, rather than an answer routed back to a live node.',
+    help: {
+        name: 'human request create',
+        summary: 'create one durable human request from the typed create object',
+        params: [
+            {
+                kind: 'flag',
+                name: 'request-file',
+                type: 'path',
+                required: true,
+                constraint: 'JSON file holding the create object: {"page":{"dialect":"jsx"|"html","source":"<the authored page text, inline>"}, "delivery"?:{"placement":"inline"|"panel"}, "source"?:{"sessionName"?,"askedBy"?,"emittedAt"?,"profileName"?,"nodeId"?}, "creator_cwd"?:"<absolute dir>", "action"?:{"name":"<declared action>","payload":<any JSON, null when omitted>}}. The page text is inline, never a path — the request must stay readable after the creating process is gone. creator_cwd defaults to this directory and is the scope the action name resolves from. delivery.inbox and delivery.reply are pinned: a programmatic request is always answerable from the inbox and never routes to an agent bridge. Unknown fields are rejected.',
+            },
+        ],
+        output: [
+            { name: 'request_id', type: 'string', required: true, constraint: 'The created request — pass it to get/replace/respond/cancel. Stable, and the deduplication key every completion destination keys on.' },
+            { name: 'action', type: 'object', required: false, constraint: '{name} of the frozen action binding. Absent when the request carries no action.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Publishes one durable page ticket into the human inbox. It has no reply bridge and outlives this process.',
+            'An action name is resolved from the humanActions map in scope config (project ancestors, then user) BEFORE anything is written — an unknown or unusable name is rejected and leaves no inbox row for a person to answer.',
+            'A resolved action is frozen onto the ticket: name, payload, resolved argv, and cwd. replace can never change it; a different effect needs a cancel and a new request.',
+        ],
+    },
+    run: async (input) => {
+        const path = input['requestFile'];
+        const body = readJsonFile(path, 'request-file', 'the create object');
+        if (body['creator_cwd'] === undefined)
+            body['creator_cwd'] = process.cwd();
+        try {
+            const created = await cliClient().createHumanRequest(body);
+            return {
+                request_id: created.request_id,
+                ...(created.action === undefined ? {} : { action: created.action }),
+            };
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// get
+const getLeaf = defineLeaf({
+    name: 'get',
+    description: 'read one request, its terminal result, and its delivery state',
+    whenToUse: 'you need the current state of a request you created — including the answers, once someone has settled it.',
+    help: {
+        name: 'human request get',
+        summary: 'read one durable request',
+        params: [{ kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' }],
+        output: [...RECORD_OUTPUT],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        try {
+            return requestResult(await cliClient().getHumanRequest(requestId(input)));
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// replace
+const replaceLeaf = defineLeaf({
+    name: 'replace',
+    description: 'revise a pending request\'s page in place',
+    whenToUse: 'what you are asking changed while the request is still pending, and the same request should keep its identity and its frozen action.',
+    help: {
+        name: 'human request replace',
+        summary: 'republish a pending request\'s page',
+        params: [
+            { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
+            { kind: 'flag', name: 'page', type: 'path', required: true, constraint: 'The revised page: a .tsx module or a complete .html/.htm document. Read here and sent inline.' },
+        ],
+        output: [...REQUEST_RESULT_OUTPUT],
+        outputKind: 'object',
+        effects: [
+            'Rewrites the page and its typed response contract in place; open surfaces reload it without a second request.',
+            'Identity is untouched: request id, provenance, emitted time, delivery, and the frozen action binding all survive verbatim.',
+            'Refused with already_settled once the request has a terminal result — a settled request is revised by cancelling and creating a new one.',
+        ],
+    },
+    run: async (input) => {
+        const id = requestId(input);
+        const body = { page: readPageFile(input['page']) };
+        try {
+            return requestResult(await cliClient().replaceHumanRequest(id, body), false);
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// respond
+const respondLeaf = defineLeaf({
+    name: 'respond',
+    description: 'settle a pending request with typed answers',
+    whenToUse: 'an authorized host is submitting the answers on the person\'s behalf, rather than the person answering in their inbox.',
+    help: {
+        name: 'human request respond',
+        summary: 'answer a pending request',
+        params: [
+            { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
+            {
+                kind: 'flag',
+                name: 'response-file',
+                type: 'path',
+                required: true,
+                constraint: 'JSON file holding the respond object: {"responses":{"<component_id>":{...}}, "actor"?:"<who answered>"}. One typed response per response-bearing component; the daemon validates the complete map against the currently published page.',
+            },
+        ],
+        output: [...REQUEST_RESULT_OUTPUT],
+        outputKind: 'object',
+        effects: [
+            'Settles the request as answered and drops it from the human inbox.',
+            'Competes with the person\'s own answer, a recipient dismissal, and a requester cancel through one first-writer-wins store: a losing attempt returns already_settled and changes nothing.',
+            'When an action is bound, the winning settlement enqueues one at-least-once completion delivery keyed on the request id.',
+        ],
+    },
+    run: async (input) => {
+        const id = requestId(input);
+        const body = readJsonFile(input['responseFile'], 'response-file', 'the respond object');
+        try {
+            return requestResult(await cliClient().respondHumanRequest(id, body), false);
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// cancel
+const cancelLeaf = defineLeaf({
+    name: 'cancel',
+    description: 'withdraw a pending request',
+    whenToUse: 'the decision you asked for stopped mattering, or the effect must change — the action binding is immutable, so a new effect needs a new request.',
+    help: {
+        name: 'human request cancel',
+        summary: 'withdraw a pending request',
+        params: [
+            { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
+            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Short note recorded on the terminal result and carried in the completion document.' },
+        ],
+        output: [...REQUEST_RESULT_OUTPUT],
+        outputKind: 'object',
+        effects: [
+            'Settles the request as canceled and drops it from the human inbox — the person is no longer asked.',
+            'Races the person\'s answer through the same first-writer-wins store; whoever lands first is authoritative and the loser returns already_settled.',
+            'When an action is bound, the winning settlement enqueues one completion delivery carrying the canceled event.',
+        ],
+    },
+    run: async (input) => {
+        const id = requestId(input);
+        const reason = typeof input['reason'] === 'string' && input['reason'] !== '' ? input['reason'] : undefined;
+        try {
+            return requestResult(await cliClient().cancelHumanRequest(id, reason === undefined ? {} : { reason }), false);
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// Registration
+export const humanRequestBranch = defineBranch({
+    name: 'request',
+    description: 'durable requests that outlive the process that made them',
+    whenToUse: 'a script or backend needs a human decision whose outcome must survive its own exit, instead of an answer pushed back to a live node.',
+    help: {
+        name: 'human request',
+        summary: 'durable programmatic human requests — create, read, revise, and settle',
+        model: 'A request is the same page ticket `human send` publishes, minus the agent bridge: nothing waits on it, and the outcome is read with `get` or carried to a local command by a named action. Reach for it when the caller will be gone before the person answers; when a live node should receive the answer, use `crtr human send` instead.\n\nThe page and its typed response contract stay revisable with `replace` while pending. The action binding does not: name, payload, resolved argv, and cwd are frozen at creation, so a different effect means `cancel` plus a new request. An action is a name declared in the humanActions map of scope config — there is no command, shell string, or callback URL anywhere in this surface.\n\nA request ends exactly once. `respond` (an authorized host answering), the person answering in their own inbox, a recipient dismissal, and `cancel` all compete through one first-writer-wins settlement; the loser gets already_settled and no second delivery. Only the winner enqueues the completion document, delivered at least once — the receiving command must deduplicate on the request id.',
+    },
+    children: [createLeaf, getLeaf, replaceLeaf, respondLeaf, cancelLeaf],
+});

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

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

package/dist/commands/human/review.js

@@ -0,0 +1,288 @@
+import { envNodeId } from '../../shared/env.js';
+import { randomUUID } from 'node:crypto';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient } from '../api-client.js';
+function nodeActor() {
+    const nodeId = envNodeId();
+    return nodeId === undefined || nodeId === '' ? null : nodeId;
+}
+function requireOriginNode() {
+    const nodeId = nodeActor();
+    if (nodeId !== null)
+        return nodeId;
+    throw new InputError({
+        error: 'review_origin_unavailable',
+        message: 'a review must be filed from a node with a live or resumable session',
+        field: 'CRTR_NODE_ID',
+        next: 'Run this from the node whose document context should be forked for the review.',
+    });
+}
+function requireSubtitle(value) {
+    if (typeof value === 'string' && value.trim() !== '')
+        return value.trim();
+    throw new InputError({
+        error: 'missing_parameter',
+        message: 'a non-empty subtitle is required',
+        field: 'subtitle',
+        next: 'Run `crtr human review new -h` and provide one plain-English sentence explaining the review needed and why it matters.',
+    });
+}
+function requireCommentText(value, leaf) {
+    if (typeof value === 'string' && value.trim() !== '')
+        return value;
+    throw new InputError({
+        error: 'missing_parameter',
+        message: 'non-empty comment text is required on stdin',
+        field: 'text',
+        next: `Run \`crtr human review comment ${leaf} -h\` and pipe the comment text on stdin.`,
+    });
+}
+function explicitDeliver(input, context) {
+    const supplied = context?.providedParams.has('deliver') ?? input['deliver'] !== undefined;
+    if (!supplied)
+        return undefined;
+    const deliver = input['deliver'];
+    return deliver === 'wake' || deliver === 'quiet' ? deliver : undefined;
+}
+function mutationOutput(result, includeAnchor = true) {
+    const { comment } = result;
+    return {
+        comment_id: comment.comment_id,
+        status: comment.status,
+        revision: comment.revision,
+        ...(includeAnchor ? { anchor: comment.anchor } : {}),
+        author: comment.author,
+        text: comment.text,
+        changed: result.changed,
+        delivery: result.delivery ?? null,
+    };
+}
+function commentPreview(comment) {
+    return {
+        comment_id: comment.comment_id,
+        status: comment.status,
+        revision: comment.revision,
+        anchor: { line: comment.anchor.line, end_line: comment.anchor.end_line },
+        anchor_state: comment.anchor_state,
+        author: comment.author,
+        updated_by: comment.updated_by,
+        created_at: comment.created_at,
+        updated_at: comment.updated_at,
+        text_preview: comment.text.slice(0, 200),
+    };
+}
+const humanReviewNew = defineLeaf({
+    name: 'new',
+    description: 'queue a document review with a collaborating companion agent',
+    whenToUse: 'filing a live document for a person to review alongside a companion agent.',
+    help: {
+        name: 'human review new',
+        summary: 'queue a live document review and return its ticket handle immediately',
+        guide: 'The person reviews the document in the attach viewer alongside a collaborating companion agent. The daemon reads the document as you and snapshots its current revision into the review. When the person submits, their edits are saved as a new revision of the document and the approval is pushed to your inbox. If the document gets a new revision while the review is open, the save is refused as `stale_revision` and the review stays open; do not edit a document while it is under review.',
+        params: [
+            { kind: 'positional', name: 'document', type: 'string', required: true, constraint: 'The document to review: a name, `<owner>/<name>` or id, `[[ ]]` optional. It must have one head; merge several heads first.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: true, constraint: 'One plain-English sentence stating the review needed and why it matters.' },
+        ],
+        output: [
+            { name: 'review_id', type: 'string', required: true, constraint: 'Daemon-owned review id for the document, comments, and companion.' },
+            { name: 'document', type: 'string', required: true, constraint: 'The reviewed document\'s `<owner>/<name>`.' },
+            { name: 'review_dir', type: 'string', required: true, constraint: 'Directory containing the review\'s document.md snapshot and immutable result.json.' },
+            { name: 'result_path', type: 'string', required: true, constraint: 'The immutable terminal result path: <review_dir>/result.json.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'The review remains live for the person and companion; approval is delivered to the origin inbox.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Records your read of the document and creates the durable review, its `document.md` snapshot, and the companion session fork.',
+            'On submit, a changed snapshot becomes a new revision authored by the person; this command does not submit an approval.',
+        ],
+    },
+    run: async (input) => {
+        const subtitle = requireSubtitle(input['subtitle']);
+        const review = await cliClient().createReview({
+            origin_kind: 'ticket',
+            origin_node_id: requireOriginNode(),
+            document: input['document'],
+            idempotency_key: randomUUID(),
+            subtitle,
+        });
+        return {
+            review_id: review.review_id,
+            document: review.document ?? null,
+            review_dir: review.review_dir,
+            result_path: `${review.review_dir}/result.json`,
+            follow_up: 'The review is live for the person in the attach viewer with its companion agent. Approval is pushed to the origin inbox when submitted.',
+        };
+    },
+});
+const humanReviewCommentCreate = defineLeaf({
+    name: 'create',
+    description: 'add an anchored review comment',
+    whenToUse: 'recording a new finding or instruction against one or more document lines.',
+    help: {
+        name: 'human review comment create',
+        summary: 'add a daemon-owned comment anchored to document lines',
+        guide: 'Without --review, the daemon targets the calling companion node\'s open review. Comment text is supplied on stdin; agent comments use whole-line anchors.',
+        params: [
+            { kind: 'flag', name: 'review', type: 'string', required: false, constraint: 'Review id. Omit only to target the calling companion node\'s open review.' },
+            { kind: 'flag', name: 'line', type: 'int', required: true, constraint: 'First 1-based document line in the anchor.' },
+            { kind: 'flag', name: 'end-line', type: 'int', required: false, constraint: 'Last 1-based document line in the anchor. Default: --line.' },
+            { kind: 'flag', name: 'deliver', type: 'enum', choices: ['wake', 'quiet'], required: false, constraint: 'wake interrupts the companion now; quiet leaves a durable message for its next turn. Default: wake unless the caller is the companion.' },
+            { kind: 'stdin', name: 'text', required: true, constraint: 'Non-empty comment text.' },
+        ],
+        output: [
+            { name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id.' },
+            { name: 'status', type: 'string', required: true, constraint: 'Current comment status: open, resolved, or deleted.' },
+            { name: 'revision', type: 'integer', required: true, constraint: 'Current per-comment revision.' },
+            { name: 'author', type: 'object', required: true, constraint: 'Daemon-derived human or node attribution.' },
+            { name: 'text', type: 'string', required: true, constraint: 'Stored full comment text.' },
+            { name: 'changed', type: 'boolean', required: true, constraint: 'Whether this invocation changed the comment.' },
+            { name: 'delivery', type: 'object | null', required: true, constraint: 'Best-effort companion notification outcome, or null when no notification was needed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Creates a daemon-owned comment and audit event, then best-effort notifies the companion.'],
+    },
+    run: async (input, context) => {
+        const reviewId = input['review'];
+        const line = input['line'];
+        const endLine = input['endLine'];
+        const result = await cliClient().createReviewComment(reviewId, {
+            text: requireCommentText(input['text'], 'create'),
+            anchor: { line, end_line: endLine ?? line },
+            actor_node_id: nodeActor(),
+            ...(explicitDeliver(input, context) === undefined ? {} : { deliver: explicitDeliver(input, context) }),
+        });
+        return mutationOutput(result, false);
+    },
+});
+const humanReviewCommentList = defineLeaf({
+    name: 'list',
+    description: 'list review comments in render order',
+    whenToUse: 'choosing a comment to inspect or checking the current anchored comment set.',
+    help: {
+        name: 'human review comment list',
+        summary: 'list render-ordered review comments with short text previews',
+        guide: 'Without --review, the daemon targets the calling companion node\'s open review. Use show for full comment text and audit history.',
+        params: [
+            { kind: 'flag', name: 'review', type: 'string', required: false, constraint: 'Review id. Omit only to target the calling companion node\'s open review.' },
+            { kind: 'flag', name: 'status', type: 'enum', choices: ['open', 'resolved', 'deleted', 'all'], required: false, default: 'open', constraint: 'Comment statuses to include. Default: open.' },
+        ],
+        output: [
+            { name: 'review_id', type: 'string', required: true, constraint: 'Resolved daemon-owned review id.' },
+            { name: 'comments', type: 'object[]', required: true, constraint: 'Comments in render order with status, anchor, attribution, and a 200-character text_preview.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Points to show for full text and per-comment history.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const reviewId = input['review'];
+        const status = input['status'];
+        const result = await cliClient().listReviewComments(reviewId, reviewId === undefined
+            ? { status, actor_node_id: nodeActor() }
+            : { status });
+        return {
+            review_id: result.review_id,
+            comments: result.comments.map(commentPreview),
+            follow_up: 'Use `crtr human review comment show <comment_id>` for full comment text and event history.',
+        };
+    },
+});
+const humanReviewCommentShow = defineLeaf({
+    name: 'show',
+    description: 'read one comment and its event history',
+    whenToUse: 'you need a comment\'s full text or complete per-comment audit history.',
+    help: {
+        name: 'human review comment show',
+        summary: 'read one full review comment and its event history',
+        params: [{ kind: 'positional', name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id from comment list.' }],
+        output: [
+            { name: 'comment', type: 'object', required: true, constraint: 'Full daemon-owned comment projection, including text and attribution.' },
+            { name: 'events', type: 'object[]', required: true, constraint: 'Complete append-only event history for this comment, in event sequence order.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const result = await cliClient().getReviewComment(input['comment_id']);
+        return { comment: result.comment, events: result.events };
+    },
+});
+function commentMutationLeaf(verb) {
+    const needsText = verb === 'edit';
+    return defineLeaf({
+        name: verb,
+        description: verb === 'edit'
+            ? 'replace a comment\'s text'
+            : `${verb} one review comment`,
+        whenToUse: verb === 'edit'
+            ? 'changing the stored text of an existing open or resolved comment.'
+            : `${verb === 'resolve' ? 'marking a comment addressed' : verb === 'reopen' ? 'returning a resolved comment to open' : 'retaining a terminal comment tombstone while removing it from active work'}.`,
+        help: {
+            name: `human review comment ${verb}`,
+            summary: verb === 'edit' ? 'replace a review comment\'s full text' : `${verb} a review comment`,
+            guide: needsText ? 'Replacement comment text is supplied on stdin.' : undefined,
+            params: [
+                { kind: 'positional', name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id from comment list.' },
+                { kind: 'flag', name: 'deliver', type: 'enum', choices: ['wake', 'quiet'], required: false, constraint: `wake interrupts the companion now; quiet leaves a durable message for its next turn. Default: ${verb === 'resolve' || verb === 'delete' ? 'quiet' : 'wake'} unless the caller is the companion.` },
+                ...(needsText ? [{ kind: 'stdin', name: 'text', required: true, constraint: 'Non-empty replacement comment text.' }] : []),
+            ],
+            output: [
+                { name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id.' },
+                { name: 'status', type: 'string', required: true, constraint: 'Current comment status: open, resolved, or deleted.' },
+                { name: 'revision', type: 'integer', required: true, constraint: 'Current per-comment revision.' },
+                { name: 'anchor', type: 'object', required: true, constraint: 'Current whole-line anchor.' },
+                { name: 'author', type: 'object', required: true, constraint: 'Daemon-derived human or node attribution.' },
+                { name: 'text', type: 'string', required: true, constraint: 'Stored full comment text.' },
+                { name: 'changed', type: 'boolean', required: true, constraint: 'Whether this invocation changed the comment.' },
+                { name: 'delivery', type: 'object | null', required: true, constraint: 'Best-effort companion notification outcome, or null when no notification was needed.' },
+            ],
+            outputKind: 'object',
+            effects: [`Mutates the daemon-owned comment and appends an audit event when its state changes; notification is best-effort.`],
+        },
+        run: async (input, context) => {
+            const commentId = input['comment_id'];
+            const actor_node_id = nodeActor();
+            const deliver = explicitDeliver(input, context);
+            const request = { actor_node_id, ...(deliver === undefined ? {} : { deliver }) };
+            const result = verb === 'edit'
+                ? await cliClient().editReviewComment(commentId, { ...request, text: requireCommentText(input['text'], 'edit') })
+                : verb === 'resolve'
+                    ? await cliClient().resolveReviewComment(commentId, request)
+                    : verb === 'reopen'
+                        ? await cliClient().reopenReviewComment(commentId, request)
+                        : await cliClient().deleteReviewComment(commentId, request);
+            return mutationOutput(result);
+        },
+    });
+}
+const humanReviewComment = defineBranch({
+    name: 'comment',
+    description: 'create, inspect, and update daemon-owned review comments',
+    whenToUse: 'working with the anchored comments on a document review.',
+    help: {
+        name: 'human review comment',
+        summary: 'operate on daemon-owned anchored review comments',
+        model: 'create and list address a review; all other verbs address one comment id. Create, edit, and reopen default to wake, while resolve and delete default to quiet.',
+    },
+    children: [
+        humanReviewCommentCreate,
+        humanReviewCommentList,
+        humanReviewCommentShow,
+        commentMutationLeaf('edit'),
+        commentMutationLeaf('resolve'),
+        commentMutationLeaf('reopen'),
+        commentMutationLeaf('delete'),
+    ],
+});
+export const humanReviewBranch = defineBranch({
+    name: 'review',
+    description: 'queue a document review or operate on its anchored comments',
+    whenToUse: 'a person and companion agent should collaborate on a live document review, or you need to work with that review\'s anchored comments.',
+    help: {
+        name: 'human review',
+        summary: 'queue live document reviews and manage their daemon-owned comments',
+        model: 'new creates the durable review, ticket, and companion. comment contains the operations on the review\'s shared anchored comments.',
+    },
+    children: [humanReviewNew, humanReviewComment],
+});

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

@@ -0,0 +1,16 @@
+export interface PageHelpText {
+    brief: string;
+    authoring: string;
+    componentSelection: readonly string[];
+    pageHint: string;
+    rootUseWhen: string;
+    /** `human send` surfaces. HTML is named only where an HTML page can be read. */
+    sendSummary: string;
+    sendWhenToUse: string;
+    pageFlagConstraint: string;
+    stdinConstraint: string;
+    dirConstraint: string;
+}
+/** The one page authoring model for `human -h`. */
+export declare function pageHelpText(pageSurface?: boolean): PageHelpText;
+export declare function resolveMaxPanes(): number;

package/dist/commands/human/shared.js

@@ -0,0 +1,67 @@
+import { readConfig } from '../../core/config.js';
+import { CORE_COMPONENT_SELECTION_LINES } from '../../core/human/component-docs.js';
+// The reader's missing context is the gap syntax cannot close: an inbox page
+// is opened away from the conversation that produced it, by someone who never
+// followed the work.
+const PAGE_BRIEF = 'Write the page for where it is read. A page projected to the inbox is opened away from this conversation by someone who has not followed the work, so it stands alone; an inline page can lean on what the conversation already said. Title names what is being settled, not the topic it sits under. Subtitle is the single line shown beside the title in the inbox list before anything is opened, so it earns the open — your recommendation and what is at stake — rather than summarising the page. Content carries only what is needed to decide. Ask only what changes your next step, and offer only options you would actually take; mark the one you would take `recommended` (at most one per question), because a page whose single question is that picker can be answered straight from the inbox list without ever being opened, which is the cheapest answer you can ask for. The reader takes a page one step at a time, so hold each step — and a stepless page — to one question or request for action; several decisions means several `<Step>` children, never one long scroll of stacked context and asks. A page that asks nothing states what happened and what it changes.';
+// Both hosts render pages and both want them reached for by default; only the
+// reason differs, so neither surface is left sounding like pages are exotic.
+const ENCOURAGEMENT_PAGE_SURFACE = 'Use inline pages as the default way to put structured or interactive content in front of the user; the environment renders rich components, so a page is not a special occasion.';
+const ENCOURAGEMENT_TERMINAL = 'Use inline pages as the default way to put a question or a decision in front of the user; the viewer draws them in the transcript and in the inbox, so a page is not a special occasion.';
+// The default is about form, not frequency: the page is the cheap part and the
+// reader's attention is the expensive one, so say both in the same breath.
+const INTERRUPTION_COST = 'What costs the reader is being asked, not the page it arrives on: send one when their answer changes what you do next, carry everything else in your next report, and put several decisions in one page as separate steps rather than sending several pages.';
+const AUTHORING_MODULE = 'Write one `.tsx` module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx` that default-exports a component whose root element is `<Page title="…" subtitle="…">`; a multi-step page puts its content in `<Step>` children.';
+// Only a page surface can show an HTML document; a terminal host renders its
+// title and nothing else, so naming the dialect there would hand the agent a
+// page its reader could not read.
+const AUTHORING_HTML = 'Or send a complete `.html` file with a nonempty `<title>`; HTML is delivered verbatim and collects no response.';
+const AUTHORING_RULES = 'Delivery is chosen by `human send` flags, never a Page prop. Registry components and React are already in scope, so the module contains no `import` and no `require`. Full JS is yours: state, expressions, `.map` over your data, event handlers, plain elements with Tailwind classes. `usePageHost` is a reserved hook whose product-supplied members are opaque here. Never render submit or dismiss chrome — the host owns it. Display-only pages are first-class: a page with no questions may be sent without inbox or reply delivery. The module is compiled when you submit it and a compile error rejects the submit; there is no pre-check.';
+// Where context belongs is a property of the surface, not of taste: a page
+// surface shows a question with the whole page around it, a terminal shows one
+// question alone on the screen.
+const CONTEXT_PAGE_SURFACE = 'Context can sit anywhere on the page — prose and display components around a question are rendered beside it — so a question\'s `body` carries what that question needs and the page carries the shared background.';
+const CONTEXT_TERMINAL = 'Put the context a question needs in that question\'s own `body`: the reader is shown one question at a time, so page-level prose is not in front of them while they answer, and a question that leans on it cannot be answered.';
+const FLATTENING_TERMINAL = 'This host draws the page from the components you declared rather than running your module, so layout, Tailwind classes, state, and click handlers never reach the reader — what survives is each component\'s `label`, its markdown `body`, and its options, rows, or cards. A chart renders as one line naming it, and a product-registered component cannot be answered here at all.';
+const DISPLAY_SET_LINE = 'The shadcn display set — `Card`, `Badge`, `Button`, `Table`, `Tabs`, `Separator`, `Alert`, `Progress`, `Accordion` and their parts — is in scope too, for presentation only.';
+/** The one page authoring model for `human -h`. */
+export function pageHelpText(pageSurface = false) {
+    const authoring = [
+        pageSurface ? ENCOURAGEMENT_PAGE_SURFACE : ENCOURAGEMENT_TERMINAL,
+        INTERRUPTION_COST,
+        AUTHORING_MODULE,
+        ...(pageSurface ? [AUTHORING_HTML] : []),
+        AUTHORING_RULES,
+        pageSurface ? CONTEXT_PAGE_SURFACE : CONTEXT_TERMINAL,
+        ...(pageSurface ? [] : [FLATTENING_TERMINAL]),
+    ].join(' ');
+    return {
+        brief: PAGE_BRIEF,
+        authoring,
+        componentSelection: [...CORE_COMPONENT_SELECTION_LINES, DISPLAY_SET_LINE],
+        pageHint: 'Write the page module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx`; pass that path.',
+        // The page-surface wording names no document review and no live display:
+        // `human review` and `human show` are terminal-only and leave the tree on
+        // such a host (see `registerHuman`).
+        // No leading "when": the root renderer already emits `use when ${useWhen}`.
+        rootUseWhen: pageSurface
+            ? 'a person must decide something or receive structured content from you; use inline pages by default because the environment renders rich components.'
+            : 'a person must decide, review a document with you, or receive a live display.',
+        sendSummary: pageSurface ? 'send a durable TSX or HTML page' : 'send a durable TSX page',
+        sendWhenToUse: pageSurface
+            ? 'you need to put structured TSX or HTML content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.'
+            : 'you need to put structured TSX content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.',
+        pageFlagConstraint: pageSurface
+            ? 'A .tsx file is JSX; .html/.htm is complete HTML. Provide exactly one of --page or stdin.'
+            : 'Provide exactly one of --page or stdin.',
+        stdinConstraint: pageSurface
+            ? 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH. HTML is file-authored.'
+            : 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH.',
+        dirConstraint: pageSurface
+            ? 'Interaction directory holding page.tsx or page.html, optional page.js, page.json, and response lifecycle files when delivery needs them.'
+            : 'Interaction directory holding page.tsx, optional page.js, page.json, and response lifecycle files when delivery needs them.',
+    };
+}
+export function resolveMaxPanes() {
+    return readConfig('user').max_panes_per_window;
+}