@north-light/api 0.3.580 → 0.3.587

package/dist/commands/node/message.js

@@ -0,0 +1,170 @@
+// `crtr node message` — immediate inbox delivery and typed-output requests.
+import { envNodeId } from '../../shared/env.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { requireScope } from '../../core/errors.js';
+import { OUTPUT_SCHEMA_CONSTRAINTS, OUTPUT_SCHEMA_TRANSPORT, parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
+import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
+function requireNonBlankDiscriminant(input, name) {
+    const value = input[name];
+    if (value !== undefined && (typeof value !== 'string' || value.trim() === '')) {
+        const flag = name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+        throw new InputError({ error: 'empty_discriminant', message: `--${flag} must contain non-whitespace text`, received: typeof value === 'string' ? value : String(value), field: flag, next: `Pass a non-empty --${flag} value, or omit the flag.` });
+    }
+}
+async function resolveMsgTarget(input, hasBody) {
+    const to = input['to']?.trim();
+    const self = input['self'] === true;
+    const hasTo = to !== undefined && to !== '';
+    if (hasTo === self) {
+        throw new InputError({
+            error: 'bad_target',
+            message: hasTo && self ? '--to and --self are mutually exclusive' : hasBody ? 'no target given — the message body is not a node id' : 'exactly one of --to or --self is required',
+            field: hasTo ? undefined : 'to',
+            next: hasTo ? 'Pass --to <node-id> or --self.' : hasBody ? 'Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.' : 'Pass --to <node-id> or --self.',
+        });
+    }
+    if (self) {
+        const id = envNodeId();
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node to target with --self (CRTR_NODE_ID unset)', next: 'Run from inside a node, or pass --to <node-id>.' });
+        }
+        return { targetId: id, isSelf: true };
+    }
+    const exists = await getNodeOrNull(to);
+    if (exists === null) {
+        throw new InputError({ error: 'not_found', message: `no node: ${to}`, field: 'to', next: 'List nodes with `crtr node inspect list`.' });
+    }
+    return { targetId: to, isSelf: false };
+}
+function messageOutput() {
+    return [
+        { name: 'revived', type: 'boolean', required: false, constraint: 'True when this request synchronously revived the target; ordinary durable delivery to an active or idle dormant target queues lifecycle revival instead.' },
+        { name: 'guidance', type: 'string', required: true, constraint: 'Immediate action confirmation.' },
+    ];
+}
+function missingMessageTargetForBody(input) {
+    const to = input['to']?.trim();
+    if ((to !== undefined && to !== '') || input['self'] === true)
+        return undefined;
+    return {
+        message: 'no target given — the positional argument is the message body, not a node id',
+        field: 'to',
+        next: 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.',
+    };
+}
+function messageSendParams() {
+    return [
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --situational-context is supplied.', positionalStdinConflict: missingMessageTargetForBody },
+        { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
+        { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
+        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node, except a terminal one, which has no later cycle to read it on and is raised to urgent.' },
+        { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
+        { kind: 'flag', name: 'reopen', type: 'bool', required: false, constraint: 'Re-task the target: clears any finalization latch before delivery and brings a done target back to active. Commits the target resident, except when you are its manager (the node that spawned it): then it keeps its lifecycle, so a terminal child still owes a final report. Valid for live, parked, and finalized targets.' },
+    ];
+}
+function messageRequestParams() {
+    return [
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.', positionalStdinConflict: missingMessageTargetForBody },
+        { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
+        { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
+        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal'], required: false, default: 'normal', constraint: 'Delivery urgency. Every accepted tier queues lifecycle revival for an active or idle dormant target because the request must be answered; deferred is rejected for that reason.' },
+        { kind: 'flag', name: 'output-schema', type: 'string', required: true, constraint: `JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} The target answers with \`crtr push result\` (or declines with \`crtr push result --decline "<reason>" --code <token>\`), then keeps working. ${OUTPUT_SCHEMA_CONSTRAINTS}` },
+        { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
+        { kind: 'flag', name: 'reopen', type: 'bool', required: false, hidden: true, constraint: 'Clear a finalized target latch before delivery or fresh revive.' },
+    ];
+}
+async function runMessageEngine(input) {
+    requireScope('crtr:act', 'crtr node message');
+    const situationalContextSupplied = input['situationalContext'] !== undefined;
+    const situationalContextRaw = input['situationalContext']?.trim();
+    if (situationalContextSupplied && situationalContextRaw === '') {
+        throw new InputError({ error: 'empty_situational_context', message: '--situational-context must contain non-whitespace text', field: 'situational-context', next: 'Pass non-whitespace text, or omit --situational-context.' });
+    }
+    const bodyRaw = input['body'];
+    const body = bodyRaw !== undefined ? bodyRaw.trim() : undefined;
+    const hasBody = body !== undefined && body !== '';
+    const { targetId } = await resolveMsgTarget(input, hasBody);
+    const tierRaw = input['tier'];
+    const hasTier = tierRaw !== undefined && tierRaw !== '';
+    const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
+    const outputSchema = outputSchemaParsed !== null ? JSON.stringify(outputSchemaParsed) : null;
+    const hasSituational = situationalContextRaw !== undefined && situationalContextRaw !== '';
+    const reopen = input['reopen'] === true;
+    if (outputSchema !== null && tierRaw === 'deferred') {
+        throw new InputError({ error: 'output_schema_deferred_tier', message: '--output-schema cannot combine with --tier deferred because the target must answer', field: 'tier', next: 'Use normal, urgent, or critical tier, or drop --output-schema.' });
+    }
+    const senderFrom = envNodeId();
+    const client = cliClient();
+    if (!hasBody && !hasSituational && outputSchema === null) {
+        throw new InputError({ error: 'empty_body', message: 'a message body is required unless --output-schema or --situational-context is supplied', field: 'body', next: 'Pass the message on stdin, or supply one of the documented alternatives.' });
+    }
+    const tier = (hasTier ? tierRaw : 'normal');
+    const res = await client.sendMessage(targetId, {
+        body: body ?? '',
+        tier,
+        ...(reopen ? { reopen: true } : {}),
+        ...(hasSituational ? { situational_context: situationalContextRaw } : {}),
+        ...(outputSchema !== null ? { output_schema: outputSchema } : {}),
+        ...(senderFrom !== undefined ? { from: senderFrom } : {}),
+    }).catch(rethrowAsCliError);
+    if (res.wake_failed !== undefined) {
+        const failed = res.wake_failed;
+        return {
+            revived: false,
+            guidance: `Accepted but NOT delivered to a running node — waking the target failed (${failed.error}): ${failed.message}${failed.next === undefined ? '' : ` ${failed.next}`} The message is queued durably (${failed.message_id}); do not resend it.`,
+        };
+    }
+    const guidance = res.revived
+        ? 'Delivered — the dormant target was revived to receive it.'
+        : tier !== 'deferred'
+            ? 'Delivered.'
+            : res.delivered_tier === undefined
+                ? "Delivered — held for the target's next natural cycle; not revived."
+                : 'Delivered — the target is terminal and takes no later cycle, so it was raised to urgent rather than held.';
+    return { revived: res.revived, guidance };
+}
+const nodeMessageSend = defineLeaf({
+    name: 'send',
+    description: 'deliver an inbox message to an existing node immediately',
+    whenToUse: 'a target chosen with `--to <node-id>` or `--self` should have information or new direction now — steering a worker mid-task, handing over a finding it needs, correcting a wrong turn, or waking a dormant node with fresh work. The target reads it and decides what to do with it. Use `node message request` instead when you need an answer back in a shape you specify, and `node subscription add` when the target should keep receiving this node’s pushes rather than this one delivery',
+    help: {
+        name: 'node message send',
+        summary: 'deliver an inbox message to an existing node immediately',
+        params: messageSendParams(),
+        output: messageOutput(),
+        outputKind: 'object',
+        effects: ['Appends one inbox entry. Critical, urgent, and normal delivery queues lifecycle revival for an active or idle dormant target; deferred waits for its next natural cycle.', '--reopen clears any finalization latch before delivery, allowing the target to take a new mandate. It commits the target resident unless you are its manager (the node that spawned it), in which case the target keeps its lifecycle and a terminal child still owes a final report. It is valid for live, parked, and finalized targets. Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted.'],
+    },
+    run: (input) => runMessageEngine(input),
+    render: (r) => String(r['guidance']),
+});
+const nodeMessageRequest = defineLeaf({
+    name: 'request',
+    description: 'deliver an immediate typed-output request to an existing node',
+    whenToUse: 'a target chosen with `--to <node-id>` or `--self` must hand back one answer in a shape you fix — a choice among options, a structured extraction, a verdict your own logic will branch on — or must be held to answering at all before it goes quiet. Use `node message send` instead when prose in the target’s own judgment is enough, and `node new --output-schema` when no node holds the context yet and the work needs a fresh agent',
+    help: {
+        name: 'node message request',
+        summary: 'deliver an immediate typed-output request to an existing node',
+        params: messageRequestParams(),
+        output: messageOutput(),
+        outputKind: 'object',
+        effects: ['Installs the one-off output schema before appending the request.'],
+    },
+    run: (input) => {
+        requireNonBlankDiscriminant(input, 'outputSchema');
+        return runMessageEngine(input);
+    },
+    render: (r) => String(r['guidance']),
+});
+export const nodeMessage = defineBranch({
+    name: 'message',
+    description: 'deliver immediate inbox work to an existing node',
+    whenToUse: 'you need one immediate delivery: send ordinary information, or request one schema-constrained result',
+    help: {
+        name: 'node message',
+        summary: 'deliver one immediate inbox entry to an existing node',
+        model: 'Both children append one inbox entry to a node that already exists, targeted with `--to <node-id>` or `--self`, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off output schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
+    },
+    children: [nodeMessageSend, nodeMessageRequest],
+});

package/dist/commands/node/outcome.d.ts

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

package/dist/commands/node/outcome.js

@@ -0,0 +1,133 @@
+// `crtr node outcome` — read a durable terminal outcome through crtrd only.
+import { isSafeNodeId } from '../../api/index.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+function nodeId(input) {
+    const id = typeof input['node'] === 'string' ? input['node'].trim() : '';
+    if (!isSafeNodeId(id)) {
+        throw new InputError({
+            error: 'invalid_node',
+            message: `invalid node id: ${id === '' ? '(empty)' : id}`,
+            field: 'node',
+            next: 'Pass the exact node id returned when the node was created.',
+        });
+    }
+    return id;
+}
+function renderedJson(value) {
+    return value === null || value === undefined ? 'none' : JSON.stringify(value);
+}
+const nodeOutcomeRead = defineLeaf({
+    name: 'read',
+    description: 'read or briefly await a node’s durable terminal outcome',
+    whenToUse: 'an external caller needs the durable result or failure reason for one node, optionally blocking for its terminal outcome without consuming or claiming it',
+    help: {
+        name: 'node outcome read',
+        summary: 'read a node’s durable outcome, optionally awaiting it for up to 25 seconds',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id whose durable outcome to read.' },
+            { kind: 'flag', name: 'wait', type: 'int', required: false, default: 0, constraint: 'Whole seconds to await settlement: 0–25. Omit or use 0 to return the current pending/settled state immediately.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The requested node id.' },
+            { name: 'state', type: 'string', required: true, constraint: '`pending` while the node has no terminal outcome, otherwise `settled`.' },
+            { name: 'outcome', type: 'object', required: true, constraint: 'The durable result/failure record when settled — kind/reason, revision, settled time, report basename/path, structured result, failure detail, and `declined` ({ reason, code, retryable } for a failure with reason `declined`, else null) — otherwise null.' },
+            { name: 'node_status', type: 'string', required: true, constraint: 'The node status observed with the outcome.' },
+            { name: 'deadline_at', type: 'string', required: true, constraint: 'The absolute spawn deadline, or null when unbounded.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: calls the daemon’s replay-safe GET outcome route. With --wait, the daemon polls the durable row for no more than 25 seconds.'],
+    },
+    run: async (input) => {
+        const id = nodeId(input);
+        const wait = input['wait'];
+        if (typeof wait !== 'number' || !Number.isInteger(wait) || wait < 0 || wait > 25) {
+            throw new InputError({
+                error: 'invalid_wait',
+                message: '--wait must be an integer between 0 and 25 seconds',
+                field: 'wait',
+                received: wait,
+                next: 'Pass a whole number from 0 through 25, or omit --wait to poll immediately.',
+            });
+        }
+        return { ...await cliClient().getNodeOutcome(id, { waitSeconds: wait }).catch(rethrowAsCliError) };
+    },
+    render: (result) => {
+        const outcome = result['outcome'];
+        if (outcome === null) {
+            return [
+                `<outcome state="pending" node_id="${result['node_id']}">`,
+                `- node status: ${result['node_status']}`,
+                `- deadline: ${result['deadline_at'] ?? 'none'}`,
+                '</outcome>',
+            ].join('\n');
+        }
+        return [
+            `<outcome kind="${outcome['kind']}" reason="${outcome['reason']}" state="settled" node_id="${result['node_id']}" revision="${outcome['revision']}">`,
+            `- final report: ${outcome['final_report'] === null || outcome['final_report'] === undefined ? 'none' : `${outcome['final_report']} (read with \`crtr canvas read ${outcome['final_report']}\`)`}`,
+            `- structured result: ${renderedJson(outcome['structured_result'])}`,
+            `- declined: ${renderedJson(outcome['declined'])}`,
+            `- failure detail: ${renderedJson(outcome['detail'])}`,
+            `- settled at: ${outcome['settled_at']}`,
+            `- node status: ${result['node_status']}`,
+            `- deadline: ${result['deadline_at'] ?? 'none'}`,
+            '</outcome>',
+        ].join('\n');
+    },
+});
+export const nodeOutcomeDelivery = defineLeaf({
+    name: 'delivery',
+    description: 'inspect a node outcome-delivery registration',
+    whenToUse: 'you need the durable state of the local action target registered to receive a node’s outcome',
+    help: {
+        name: 'node outcome delivery',
+        summary: 'inspect the registered outcome-delivery target for one node',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id whose outcome-delivery registration to inspect.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose outcome is delivered.' },
+            { name: 'state', type: 'string', required: true, constraint: '`armed`, `pending`, `running`, `accepted`, or `permanent_failed`.' },
+            { name: 'action', type: 'string', required: true, constraint: 'The resolved configured action name.' },
+            { name: 'attempt', type: 'number', required: true, constraint: 'How many delivery attempts have been claimed.' },
+            { name: 'next_attempt_at', type: 'string', required: true, constraint: 'ISO-8601 time of the next retry, or null before a retry is scheduled (including while armed).' },
+            { name: 'accepted_at', type: 'string', required: true, constraint: 'When the target accepted the document, or null.' },
+            { name: 'permanent_failed_at', type: 'string', required: true, constraint: 'When the target permanently rejected the document, or null.' },
+            { name: 'last_failure', type: 'object', required: true, constraint: 'The most recent retryable or permanent delivery failure, or null.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'When this delivery registration was created.' },
+            { name: 'updated_at', type: 'string', required: true, constraint: 'When this delivery registration was last updated.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: calls the daemon outcome-delivery inspection route.'],
+    },
+    run: async (input) => {
+        const id = nodeId(input);
+        return { ...await cliClient().getOutcomeDelivery(id).catch(rethrowAsCliError) };
+    },
+    render: (result) => {
+        return [
+            `<outcome-delivery state="${result['state']}" node_id="${result['node_id']}">`,
+            `- attempt: ${result['attempt']}`,
+            `- next retry: ${result['next_attempt_at'] ?? 'none'}`,
+            `- last failure: ${renderedJson(result['last_failure'])}`,
+            `- action: ${result['action']}`,
+            `- accepted at: ${result['accepted_at'] ?? 'none'}`,
+            `- permanently failed at: ${result['permanent_failed_at'] ?? 'none'}`,
+            `- registered at: ${result['created_at']}`,
+            `- updated at: ${result['updated_at']}`,
+            '</outcome-delivery>',
+        ].join('\n');
+    },
+});
+export const nodeOutcome = defineBranch({
+    name: 'outcome',
+    description: 'read a node’s terminal outcome or its delivery state',
+    whenToUse: 'you need the durable terminal result/failure of one node, or the state of its registered outcome-delivery target',
+    help: {
+        name: 'node outcome',
+        summary: 'read one node’s durable terminal outcome or its delivery registration',
+        model: 'Outcome reads never consume the terminal record. Read returns the durable result or failure and can wait briefly for settlement; delivery inspects the separate action-registration attempt state.',
+    },
+    children: [nodeOutcomeRead, nodeOutcomeDelivery],
+});

package/dist/commands/node/pyramid.d.ts

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

package/dist/commands/node/pyramid.js

@@ -0,0 +1,79 @@
+// The node-subtree slash command is provisioned with the node family.
+export const pyramidSlash = {
+    name: 'pyramid',
+    description: 'Explain a topic as a live-building Minto pyramid diagram, backed by parallel explore agents.',
+    argumentHint: '<topic to explain>',
+    body: [
+        '# Pyramid explanation',
+        '',
+        'Explain **$ARGUMENTS** as a *pyramid*: lead with the answer, support it with a few key pillars, ground each pillar in evidence. You build this as a LIVE termrender diagram that fills in as parallel research lands — the user watches the skeleton grow into a complete picture.',
+        '',
+        '## The pyramid (Minto principle)',
+        '- **Apex** — ONE crisp sentence: the single governing answer/claim, the thing worth remembering.',
+        '- **Pillars** — 2–4 MECE supporting arguments that together prove the apex.',
+        '- **Base** — concrete evidence under each pillar (mechanisms, `file:line` refs, numbers, sources).',
+        '',
+        'Top-down: the reader gets the conclusion first, then descends for as much support as they want.',
+        '',
+        '## Workflow',
+        '',
+        '1. **Frame it.** Restate the topic in one line and commit to a *working* apex hypothesis (you will sharpen it). Name the 2–4 pillars you expect to need.',
+        '',
+        '2. **Scaffold the live diagram FIRST.** Write the termrender skeleton below to `./pyramid-<slug>.md` (apex = your hypothesis, pillars = titles, every base entry marked `[?]` pending). Then open it live so the user watches it build:',
+        '   ```bash',
+        '   termrender pane open ./pyramid-<slug>.md --watch   # detached tmux side-pane; re-renders on every save',
+        '   ```',
+        '   Not in tmux? Tell the user to run `termrender doc watch ./pyramid-<slug>.md` in another terminal, then continue regardless.',
+        '',
+        '3. **Investigate in parallel — do not block.** Fan out ONE explore agent per pillar/unknown AND dig into what you can answer yourself, concurrently:',
+        '   ```bash',
+        '   crtr node new "Investigate: <focused question for this pillar>. Report findings with sources / file:line refs." --kind explore',
+        '   ```',
+        '   You auto-subscribe; each finish wakes you. Never poll or wait — kick them all off, then start filling in what you already know.',
+        '',
+        '4. **Live-update as findings land.** Every time you learn something — your own digging or an explore report — EDIT the diagram file: flip a `[?]` to `[x]` (or `[!]` for a caveat/risk), add evidence under the right pillar, sharpen or rewrite the apex, drop a pillar that did not hold. Each save re-renders the pane. The diagram visibly grows skeleton → complete.',
+        '',
+        '5. **Land it.** When the apex is one crisp sentence, the pillars are MECE, and the base is concrete, do a final pass for accuracy, then give the user a 3–4 sentence spoken summary that mirrors apex → pillars. Tell them the diagram file path.',
+        '',
+        '## termrender skeleton (write this verbatim, then keep editing it)',
+        '',
+        'Apex panel on top, a divider, then the pillars as a row of boxes below — a literal pyramid: 1 claim over N supports.',
+        '```markdown',
+        ':::panel{title="<TOPIC>" color="cyan"}',
+        '**<one-line apex answer — your governing claim>**',
+        ':::',
+        '',
+        ':::divider{label="why"}',
+        ':::',
+        '',
+        '::::::columns',
+        ':::::col{width="33%"}',
+        '::::panel{title="Pillar 1 — <claim>" color="green"}',
+        ':::tree',
+        'evidence A [x]',
+        'evidence B [?]',
+        ':::',
+        '::::',
+        ':::::',
+        ':::::col{width="33%"}',
+        '::::panel{title="Pillar 2 — <claim>" color="green"}',
+        ':::tree',
+        'evidence C [?]',
+        ':::',
+        '::::',
+        ':::::',
+        ':::::col{width="34%"}',
+        '::::panel{title="Pillar 3 — <claim>" color="green"}',
+        ':::tree',
+        'evidence D [?]',
+        ':::',
+        '::::',
+        ':::::',
+        '::::::',
+        '```',
+        '',
+        '**Nesting rule (termrender will reject the file otherwise): an OUTER directive needs strictly MORE colons than the directive nested inside it.** Hence `::::::columns` (6) wraps `:::::col` (5) wraps `::::panel` (4) wraps `:::tree` (3). Every block closes with a bare run of its OWN colon count on its own line. Run `termrender doc check ./pyramid-<slug>.md` after each edit — if it errors, fix the colon counts before re-saving.',
+        '',
+        'Markers inside a tree: `[x]` → ✔ confirmed, `[!]` → ⚠ caveat/risk; `[?]` is not a marker and stays literal — use it for still-pending. Write structure only — termrender draws every box, border, and guide line; never hand-draw ASCII. Keep the apex to one sentence; push all detail into the base.',
+    ].join('\n'),
+};

package/dist/commands/node/subscription.d.ts

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

package/dist/commands/node/subscription.js

@@ -0,0 +1,78 @@
+// `crtr node subscription` — push-delivery edge controls.
+import { envNodeId } from '../../shared/env.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+function resolveSubscriber(input) {
+    const sub = input['subscriber'] ?? envNodeId();
+    if (sub === undefined || sub === '') {
+        throw new InputError({ error: 'no_subscriber', message: 'no subscriber (set CRTR_NODE_ID or pass --subscriber)', field: 'subscriber', next: 'Run from inside a node, or pass --subscriber <id>.' });
+    }
+    return sub;
+}
+const nodeSubscribe = defineLeaf({
+    name: 'add',
+    description: 'make one node watch another, so it receives that node\'s pushes (active or --passive)',
+    whenToUse: 'you want to make one node receive another node’s pushes, actively or passively. Managed-child creation already adds its active edge; use this for other subscriber-to-publisher pairs',
+    help: {
+        name: 'node subscription add',
+        summary: 'make one node watch another so it receives that node\'s pushes — the subscriber can be you (default) or, with --subscriber, ANY node, to ANY publisher. Re-running flips an existing subscription\'s active/passive mode.',
+        params: [
+            { kind: 'positional', name: 'publisher', required: true, constraint: 'The node to subscribe TO — whose pushes get delivered to the subscriber.' },
+            { kind: 'flag', name: 'subscriber', type: 'string', required: false, constraint: 'Who receives the pushes. Defaults to the calling node (CRTR_NODE_ID). Pass any node id to wire a third party.' },
+            { kind: 'flag', name: 'passive', type: 'bool', required: false, constraint: 'Passive subscription: pushes ACCUMULATE without waking the subscriber, then auto-inject as timestamped XML pre-text on its next message. Omit for an active (wake-on-push) subscription.' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: ['Records an ask watch from the subscriber on the publisher in canvas.db; --passive sets its listening configuration to deliver on the next turn only.', 'Passive subscriptions never wake the subscriber and do not hold it alive (excluded from the stop-guard).'],
+    },
+    run: async (input) => {
+        const publisher = input['publisher'];
+        const subscriber = resolveSubscriber(input);
+        const passive = input['passive'] === true;
+        if (subscriber === publisher) {
+            throw new InputError({ error: 'self_subscribe', message: 'a node cannot subscribe to itself', next: 'Pick a different publisher.' });
+        }
+        await cliClient()
+            .subscribe(subscriber, { target: publisher, active: !passive })
+            .catch((err) => rethrowAsCliError(err));
+        return {};
+    },
+    render: () => 'Subscription added.'
+});
+const nodeUnsubscribe = defineLeaf({
+    name: 'remove',
+    description: 'stop one node watching another for pushes',
+    whenToUse: 'you want to stop one node receiving a publisher’s pushes; removal is idempotent',
+    help: {
+        name: 'node subscription remove',
+        summary: 'drop a subscription (a node watch) — the subscriber (you by default, or any node via --subscriber) stops receiving the publisher\'s pushes.',
+        params: [
+            { kind: 'positional', name: 'publisher', required: true, constraint: 'The node to stop subscribing to.' },
+            { kind: 'flag', name: 'subscriber', type: 'string', required: false, constraint: 'Who to detach. Defaults to the calling node (CRTR_NODE_ID).' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: ['Removes the subscriber\'s subscription watch on the publisher from canvas.db; a watch from reading or messaging the same node survives.'],
+    },
+    run: async (input) => {
+        const publisher = input['publisher'];
+        const subscriber = resolveSubscriber(input);
+        await cliClient()
+            .unsubscribe(subscriber, publisher)
+            .catch((err) => rethrowAsCliError(err));
+        return {};
+    },
+    render: () => 'Subscription removed.'
+});
+export const nodeSubscription = defineBranch({
+    name: 'subscription',
+    description: 'manage push-delivery edges between nodes',
+    whenToUse: 'you need an ongoing active or passive subscriber-to-publisher delivery edge that spawn did not create, or need to remove one',
+    help: {
+        name: 'node subscription',
+        summary: 'add or remove subscriber-to-publisher push-delivery edges',
+        model: 'Subscriptions point from a subscriber to a publisher and control future push delivery. A subscription is a watch the subscriber holds on the publisher (`crtr canvas edges <node> --type watches` lists every watch, including plain reads and messages; the subscribers of a node are the `managers` in `crtr node inspect show <node>`, and the nodes it subscribes to are its `reports`). Active subscriptions wake on each push; passive ones accumulate pushes for the subscriber’s next turn. Removing either kind stops subsequent delivery without changing messages already received.',
+    },
+    children: [nodeSubscribe, nodeUnsubscribe],
+});

package/dist/commands/node/wait.d.ts

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