@crouton-kit/crouter 0.3.12 → 0.3.14

package/dist/builtin-personas/runtime-base.md

@@ -34,6 +34,6 @@ If the work is bigger or different than your task implies, say so in a push to y
 ## When your task is too big for one context window
 If you discover the job is far larger than one node can hold — many phases, work that won't fit before you run low on context — **promote yourself** instead of grinding:
 
-    crtr node promote --goal "<the high-level goal you now own>"
+    crtr node promote --kind <kind>
 
-This makes you a resident orchestrator: you get a roadmap (`context/roadmap.md`), you delegate each phase to children, and when your context fills you `crtr node yield` to refresh against that roadmap. Don't promote for work that fits one window — finish it.
+This makes you a resident orchestrator: you author a roadmap (`context/roadmap.md`), delegate each phase to children, and when your context fills you `crtr node yield` to refresh against that roadmap. `--kind` specializes the orchestrator you revive into (developer, review, spec, design, plan, explore, general); omit it to keep your current kind. Don't promote for work that fits one window — finish it.

package/dist/commands/__tests__/human.test.js

@@ -3,13 +3,15 @@
 //
 // These tests exercise the leaf param schemas via parseArgv (framework) and
 // spot-check the leaf definitions directly — no subprocess spawning, no tmux.
-import { test, describe } from 'node:test';
+import { test, describe, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { writeFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { parseArgv } from '../../core/command.js';
+import { humanCancel } from '../human/queue.js';
+import { createNode, getNode, closeDb } from '../../core/canvas/index.js';
 // ---------------------------------------------------------------------------
 // Helper: write a temp JSON file and return its path.
 // ---------------------------------------------------------------------------
@@ -170,6 +172,75 @@ describe('human ask: params', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// human cancel — positional job_id + optional --reason
+// ---------------------------------------------------------------------------
+describe('human cancel: params', () => {
+    const params = [
+        { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Interaction node id.' },
+        { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Why it was retracted.' },
+    ];
+    test('parses positional job_id', async () => {
+        const result = await parseArgv(params, ['abc-1234']);
+        assert.equal(result['job_id'], 'abc-1234');
+    });
+    test('parses job_id + --reason', async () => {
+        const result = await parseArgv(params, ['abc-1234', '--reason', 'answered myself']);
+        assert.equal(result['job_id'], 'abc-1234');
+        assert.equal(result['reason'], 'answered myself');
+    });
+    test('missing job_id throws missing_parameter', async () => {
+        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
+    });
+});
+// ---------------------------------------------------------------------------
+// human cancel — run behavior (canvas-backed)
+// ---------------------------------------------------------------------------
+describe('human cancel: behavior', () => {
+    let home;
+    function humanNode(id, over = {}) {
+        return {
+            node_id: id,
+            name: 'human-ask',
+            created: new Date().toISOString(),
+            cwd: join(tmpdir(), `crtr-cancel-cwd-${randomBytes(3).toString('hex')}`),
+            kind: 'human',
+            mode: 'base',
+            lifecycle: 'terminal',
+            status: 'active',
+            ...over,
+        };
+    }
+    before(() => {
+        home = mkdtempSync(join(tmpdir(), 'crtr-cancel-home-'));
+        process.env['CRTR_HOME'] = home;
+    });
+    beforeEach(() => {
+        closeDb();
+        rmSync(home, { recursive: true, force: true });
+    });
+    after(() => {
+        closeDb();
+        rmSync(home, { recursive: true, force: true });
+        delete process.env['CRTR_HOME'];
+    });
+    test('unknown node throws not_found', async () => {
+        await assert.rejects(() => humanCancel.run({ job_id: 'no-such-node' }), (err) => { assert.match(err.message, /no interaction node/); return true; });
+    });
+    test('already-done node returns canceled:false / already_resolved', async () => {
+        createNode(humanNode('done-1', { status: 'done' }));
+        const r = await humanCancel.run({ job_id: 'done-1' });
+        assert.equal(r['canceled'], false);
+        assert.equal(r['reason'], 'already_resolved');
+    });
+    test('live node with no pane → retires the node (status done)', async () => {
+        createNode(humanNode('live-1', { status: 'active' }));
+        const r = await humanCancel.run({ job_id: 'live-1' });
+        assert.equal(r['canceled'], true);
+        assert.equal(r['job_id'], 'live-1');
+        assert.equal(getNode('live-1')?.status, 'done');
+    });
+});
+// ---------------------------------------------------------------------------
 // human list — --limit int + --cursor string
 // ---------------------------------------------------------------------------
 describe('human list: params', () => {

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

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

package/dist/commands/human/queue.js

@@ -1,9 +1,14 @@
 import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
 import { pushFinal } from '../../core/feed/feed.js';
-import { interactionsRoot } from '../../core/artifact.js';
+import { interactionsRoot, interactionDir } from '../../core/artifact.js';
 import { paginate } from '../../core/pagination.js';
+import { getNode, setStatus, updateNode, subscribersOf } from '../../core/canvas/index.js';
+import { appendInbox } from '../../core/feed/inbox.js';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { inbox, scanInbox, parseDeck, deckPath, ask, launchReview, readJson, } from '@crouton-kit/humanloop';
+import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, } from '@crouton-kit/humanloop';
+import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
 // inbox (human-invoked, blocking)
 // ---------------------------------------------------------------------------
@@ -71,6 +76,88 @@ export const humanList = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// cancel — retract a pending ask/approve/review
+// ---------------------------------------------------------------------------
+export const humanCancel = defineLeaf({
+    name: 'cancel',
+    help: {
+        name: 'human cancel',
+        summary: 'retract a pending ask/approve/review you posed — kills its TUI pane, drops it from the human queue, and retires the node. Reach for this the moment a question goes stale (you answered it yourself, the situation changed) so a human is not left resolving a prompt whose answer no longer matters',
+        guide: 'Pass the job_id returned by `human ask`/`approve`/`review`. Best-effort and idempotent: if the human already answered, or it was already canceled, it reports canceled:false with reason "already_resolved" and changes nothing. Subscribers (you and the asking node) get an inbox note that no answer is coming, so nobody waits on it. A blocking `human review` caller unblocks with status "closed" when its pane is killed.',
+        params: [
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Node id of the interaction to cancel — the job_id returned by ask/approve/review.' },
+            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Optional short note delivered to subscribers explaining why it was retracted.' },
+        ],
+        output: [
+            { name: 'canceled', type: 'boolean', required: true, constraint: 'True when the interaction was retracted; false when there was nothing live to cancel (already answered/canceled).' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The interaction node id.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'Why nothing was canceled (e.g. "already_resolved"), present when canceled is false.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            "Kills the detached TUI pane (if any) so the prompt leaves the human's screen.",
+            'Writes a canceled response.json so the interaction drops out of `human list`/`inbox`.',
+            'Marks the node done and notifies its subscribers that no answer is coming.',
+        ],
+    },
+    run: async (input) => {
+        const jobId = input['job_id'];
+        const reason = input['reason'];
+        const node = getNode(jobId);
+        if (node === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no interaction node: ${jobId}`,
+                field: 'job_id',
+                next: 'Pass the job_id from human ask/approve/review, or list pending with `crtr human list`.',
+            });
+        }
+        // Resolve the interaction dir from the node's RECORDED cwd: interaction dirs
+        // are keyed by the asking process's cwd, which may differ from the caller's.
+        const idir = interactionDir(jobId, node.cwd);
+        // Nothing live to cancel: the human already answered, or it was retired.
+        if (node.status === 'done' || node.status === 'dead' || isResolved(idir)) {
+            return { canceled: false, job_id: jobId, reason: 'already_resolved' };
+        }
+        // (1) Kill the detached TUI pane so the prompt leaves the human's screen and
+        //     any blocking `human review` caller unblocks (pane death → 'closed').
+        const rc = readJson(join(idir, 'run.json'));
+        if (rc?.pane_id !== undefined)
+            killPane(rc.pane_id);
+        // (2) Drop it from the human queue: a response.json marks the dir resolved,
+        //     so scanInbox (human list/inbox) skips it.
+        if (existsSync(idir)) {
+            atomicWriteJson(responsePath(idir), {
+                canceled: true,
+                canceledAt: new Date().toISOString(),
+                ...(reason !== undefined && reason !== '' ? { reason } : {}),
+            });
+        }
+        // (3) Retire the node and tell its subscribers no answer is coming. We do
+        //     NOT push a -final.md report: a blocking `human review` caller must see
+        //     the pane-death 'closed', not a phantom 'done' result.
+        setStatus(jobId, 'done');
+        updateNode(jobId, { intent: 'done' });
+        const caller = process.env['CRTR_NODE_ID'] ?? 'human';
+        const note = reason !== undefined && reason !== '' ? ` — ${reason}` : '';
+        for (const sub of subscribersOf(jobId)) {
+            if (sub.node_id === caller)
+                continue; // don't ping whoever issued the cancel
+            appendInbox(sub.node_id, {
+                from: caller,
+                tier: 'normal',
+                kind: 'message',
+                label: `human interaction ${jobId} canceled — no answer is coming${note}`,
+                data: { body: `The human interaction ${jobId} was canceled${note}. No response will arrive.` },
+            });
+        }
+        return { canceled: true, job_id: jobId };
+    },
+    render: (r) => r['canceled'] === true
+        ? `<canceled job_id="${r['job_id']}"/>`
+        : `<cancel-noop job_id="${r['job_id']}">${r['reason'] ?? 'nothing to cancel'}</cancel-noop>`,
+});
+// ---------------------------------------------------------------------------
 // _run (hidden worker; not listed in branch help)
 // ---------------------------------------------------------------------------
 export const humanRun = defineLeaf({

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

@@ -5,6 +5,8 @@ export interface RunRecord {
     approve_iid?: string;
     file?: string;
     output?: string;
+    /** tmux pane id of the detached TUI, recorded so `human cancel` can kill it. */
+    pane_id?: string;
 }
 export declare function resolveMaxPanes(): number;
 export declare function pickPlacement(): 'split-h' | 'new-window';
@@ -28,6 +30,9 @@ export declare function spawnHumanJob(jobId: string, idir: string, cwd: string):
     follow_up: string;
     paneId?: string;
 };
+/** Best-effort kill of a detached TUI pane. No-op (and never throws) when the
+ *  pane is already gone or tmux is unavailable — `human cancel` is best-effort. */
+export declare function killPane(paneId: string): boolean;
 export interface HumanResult {
     status: string;
     result?: unknown;

package/dist/commands/human/shared.js

@@ -2,6 +2,7 @@ import { readConfig } from '../../core/config.js';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { atomicWriteJson, readJson } from '@crouton-kit/humanloop';
 import { countPanesInCurrentWindow, spawnAndDetach, shellQuote } from '../../core/spawn.js';
 import { reportsDir } from '../../core/canvas/paths.js';
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
@@ -48,12 +49,26 @@ export function spawnHumanJob(jobId, idir, cwd) {
     if (spawn.status !== 'spawned') {
         return { spawned: false, follow_up: followUpDrain(jobId) };
     }
+    // Record the pane id on run.json so `human cancel` can later kill the TUI.
+    // run.json was already written by the caller; merge the pane id in place.
+    if (spawn.paneId !== undefined) {
+        const rcPath = join(idir, 'run.json');
+        const rc = readJson(rcPath);
+        if (rc !== null)
+            atomicWriteJson(rcPath, { ...rc, pane_id: spawn.paneId });
+    }
     return {
         spawned: true,
         follow_up: followUpResult(jobId),
         ...(spawn.paneId !== undefined ? { paneId: spawn.paneId } : {}),
     };
 }
+/** Best-effort kill of a detached TUI pane. No-op (and never throws) when the
+ *  pane is already gone or tmux is unavailable — `human cancel` is best-effort. */
+export function killPane(paneId) {
+    const r = spawnSync('tmux', ['kill-pane', '-t', paneId], { encoding: 'utf8' });
+    return r.status === 0;
+}
 /** True when a tmux pane is still alive. */
 function paneAlive(paneId) {
     const r = spawnSync('tmux', ['display-message', '-p', '-t', paneId, '#{pane_id}'], {

package/dist/commands/human.js

@@ -13,13 +13,13 @@
 // run.json, never stdin.
 import { defineBranch } from '../core/command.js';
 import { humanAsk, humanApprove, humanReview, humanNotify, humanShow } from './human/prompts.js';
-import { humanInbox, humanList, humanRun } from './human/queue.js';
+import { humanInbox, humanList, humanCancel, humanRun } from './human/queue.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
         rootEntry: {
             concept: 'human-in-the-loop decisions, document review, and live display: ask puts a structured choice to a person, approve gates a handoff on a Yes/No sign-off, review collects anchored comments on a plan or spec, notify informs without blocking, show puts a file live on screen',
-            desc: 'ask, approve, review, notify, show, inbox, list',
+            desc: 'ask, approve, review, notify, show, cancel, inbox, list',
             useWhen: 'you have a question for the user or want their feedback — always reach for human instead of guessing or assuming when a person can decide',
         },
         help: {
@@ -32,6 +32,7 @@ export function registerHuman() {
                 { name: 'review', desc: 'anchored-comment review of a .md', useWhen: 'a human should comment on a plan or spec' },
                 { name: 'notify', desc: 'fire-and-forget acknowledgement', useWhen: 'informing a person without blocking' },
                 { name: 'show', desc: 'put a file live on screen', useWhen: 'displaying a doc while a human comments' },
+                { name: 'cancel', desc: 'retract a pending ask/approve/review', useWhen: 'a question went stale before the human answered' },
                 { name: 'inbox', desc: 'interactively drain pending interactions', useWhen: 'a human clears the queue at their terminal' },
                 { name: 'list', desc: 'enumerate pending interactions', useWhen: 'discovering what is blocked on a human' },
             ],
@@ -44,6 +45,7 @@ export function registerHuman() {
             humanShow,
             humanInbox,
             humanList,
+            humanCancel,
             humanRun,
         ],
     });