@crouton-kit/crouter 0.3.81 → 0.3.83

package/dist/commands/human/prompts.js

@@ -2,16 +2,22 @@ import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { spawnNode } from '../../core/runtime/nodes.js';
 import { interactionDir } from '../../core/artifact.js';
-import { tmuxServerReachable } from '../../core/spawn.js';
 import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { validateDeck, notifyDeck, atomicWriteJson, deckPath, display, } from '@crouton-kit/humanloop';
-import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, detachHumanTui, resolveMaxPanes, } from './shared.js';
+import { tmuxServerReachable } from '../../core/spawn.js';
+import { validateDeck, notifyDeck, atomicWriteJson, submitDeck, submitReview, display, } from '@crouton-kit/humanloop';
+import { DECK_SCHEMA_HINT, registerCrouterRoot, resolveMaxPanes } from './shared.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
 }
+/** Attribution stamp so C2's attention chrome can bucket the ticket by the
+ *  agent that raised it. A bare-shell prompt has no node and stays unattributed. */
+function sourceStamp() {
+    const nodeId = askingNode();
+    return nodeId !== null && nodeId !== '' ? { nodeId } : {};
+}
 function buildHumanAskDeck(question) {
     return validateDeck({
         title: question,
@@ -26,6 +32,7 @@ function buildHumanAskDeck(question) {
         ],
     });
 }
+const QUEUED_FOLLOW_UP = "Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block. Press ⌥I (or run `hl inbox open` at a terminal) to see the queue.";
 // ---------------------------------------------------------------------------
 // ask
 // ---------------------------------------------------------------------------
@@ -48,8 +55,8 @@ export const humanAsk = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Creates a kind:"human" node under you and writes deck.json/run.json to the interaction dir.',
-            'Spawns the decision TUI in a detached tmux pane (when in tmux).',
+            'Creates a kind:"human" node under you and enqueues a decision deck in the humanloop inbox.',
+            'Returns immediately; nothing opens on screen. The human answers from the inbox popup (⌥I) on their own time.',
         ],
     },
     run: async (input) => {
@@ -81,15 +88,19 @@ export const humanAsk = defineLeaf({
                 next: DECK_SCHEMA_HINT,
             });
         }
+        // Spread the stamp LAST so an agent-supplied source can carry labels
+        // (sessionName/askedBy/blockedSince) but can never override the authoritative
+        // nodeId. A bare shell stamps `{}`, leaving any agent source intact.
+        deck = { ...deck, source: { ...(deck.source ?? {}), ...sourceStamp() } };
         const cwd = process.cwd();
         const jobId = spawnNode({ kind: 'human', parent: askingNode(), cwd, name: 'human-ask', lifecycle: 'terminal' }).node_id;
         const idir = interactionDir(jobId, cwd);
         mkdirSync(idir, { recursive: true });
-        atomicWriteJson(deckPath(idir), deck);
         const rc = { mode: 'ask', job_id: jobId };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        const { follow_up } = spawnHumanJob(jobId, idir, cwd);
-        return { job_id: jobId, dir: idir, follow_up };
+        const root = registerCrouterRoot(cwd);
+        const { dir } = submitDeck({ root, id: jobId, deck });
+        return { job_id: jobId, dir, follow_up: QUEUED_FOLLOW_UP };
     },
 });
 // ---------------------------------------------------------------------------
@@ -101,8 +112,8 @@ export const humanReview = defineLeaf({
     whenToUse: 'a human should comment line-by-line on a document rather than give one overall answer: reviewing a plan or spec before you build it, marking up a draft, flagging specific sections to change. The comments come back anchored to the lines they touch. Use `ask` instead for a single yes/no sign-off on the whole thing, or to pose a discrete choice',
     help: {
         name: 'human review',
-        summary: "put a .md live on the human's screen for anchored, line-by-line comments; returns a job handle instantly (a non-blocking kickoff, like ask). The pane tracks the file and re-renders on every save, so edit in place rather than re-presenting.",
-        guide: "A kickoff, not a blocking call: it returns at once and the human reviews on their own time. When they submit, the FeedbackResult (anchored comments, plus any line edits they made) is pushed to your inbox — waking you — and autosaved to `output`; you never poll, verify it opened, or background it. The pane is a LIVE view of the file: keep editing the .md in place and it updates, so do not cancel and re-present to show a change. The .md is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.",
+        summary: "queue a .md for anchored, line-by-line human comments; returns a job handle instantly (a non-blocking kickoff, like ask). The human opens it from the inbox popup, which previews the live doc and re-reads it on every save, so edit in place rather than re-presenting.",
+        guide: "A kickoff, not a blocking call: it returns at once and the human reviews on their own time from the inbox (⌥I). When they submit, the FeedbackResult (anchored comments, plus any line edits they made) is pushed to your inbox — waking you — and autosaved to `output`; you never poll, verify it opened, or background it. The inbox preview is a LIVE view of the file: keep editing the .md in place and it updates, so do not cancel and re-present to show a change. The .md is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.",
         params: [
             { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Absolute path to an existing .md file.' },
             { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where the FeedbackResult JSON is written. Default: <dir>/feedback.json.' },
@@ -111,13 +122,12 @@ export const humanReview = defineLeaf({
             { name: 'job_id', type: 'string', required: true, constraint: 'Node id of the kind:"human" node backing this review. Its FeedbackResult is pushed to your inbox when the human submits.' },
             { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding run.json and the autosaved feedback.json.' },
             { name: 'output', type: 'string', required: true, constraint: 'Path the FeedbackResult JSON is autosaved to when the human submits.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking road sign. The human may take minutes to hours; do not block, poll, or verify the pane — just end your turn and you are woken when they submit.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking road sign. The human may take minutes to hours; do not block, poll, or verify — just end your turn and you are woken when they submit.' },
         ],
         outputKind: 'object',
         effects: [
-            'Creates a kind:"human" node under you and writes run.json to the interaction dir.',
-            'Spawns a live review surface (detached tmux panes when in tmux): the raw source in a read-only editor for anchoring comments, beside a termrender-rendered view of the doc; both track the file and re-render on save.',
-            'Returns instantly; the anchored comments fan into your inbox when the human submits (off-tmux, drain via `crtr human inbox`).',
+            'Creates a kind:"human" node under you and enqueues an anchored review in the humanloop inbox.',
+            'Returns immediately; nothing opens on screen. The human reviews from the inbox popup (⌥I); comments fan into your inbox when they submit.',
         ],
     },
     run: async (input) => {
@@ -143,19 +153,22 @@ export const humanReview = defineLeaf({
         const jobId = spawnNode({ kind: 'human', parent: askingNode(), cwd, name: 'human-review', lifecycle: 'terminal' }).node_id;
         const idir = interactionDir(jobId, cwd);
         mkdirSync(idir, { recursive: true });
-        const outputArg = input['output'];
-        const output = outputArg !== undefined ? outputArg : join(idir, 'feedback.json');
-        const rc = { mode: 'review', job_id: jobId, file: abs, output };
+        const rc = { mode: 'review', job_id: jobId };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        // review is a non-blocking kickoff, exactly like ask: the detached
-        // `_run` worker pushes the FeedbackResult as this node's final report when
-        // the human submits, which fans into our inbox and wakes us (and is also
-        // autosaved to `output`). There is nothing to block on — the doc is live on
-        // the human's screen and tracks the file, so the caller keeps editing in
-        // place or simply ends its turn.
-        const { spawned, follow_up: drainFollowUp } = spawnHumanJob(jobId, idir, cwd);
-        const follow_up = spawned ? followUpReview(jobId) : drainFollowUp;
-        return { job_id: jobId, dir: idir, output, follow_up };
+        const outputArg = input['output'];
+        const root = registerCrouterRoot(cwd);
+        const { dir } = submitReview({
+            root,
+            id: jobId,
+            review: {
+                file: abs,
+                ...(outputArg !== undefined ? { output: resolve(outputArg) } : {}),
+                title: abs.split('/').pop() ?? abs,
+                source: sourceStamp(),
+            },
+        });
+        const output = outputArg !== undefined ? resolve(outputArg) : join(dir, 'feedback.json');
+        return { job_id: jobId, dir, output, follow_up: QUEUED_FOLLOW_UP };
     },
 });
 // ---------------------------------------------------------------------------
@@ -167,42 +180,42 @@ export const humanNotify = defineLeaf({
     whenToUse: 'informing a person without blocking or expecting an answer',
     help: {
         name: 'human notify',
-        summary: 'show a fire-and-forget acknowledgement; creates no job',
+        summary: 'enqueue a fire-and-forget acknowledgement in the human inbox; creates no job',
         guide: 'The body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
         params: [
             { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The notification headline.' },
             { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body.' },
         ],
         output: [
-            { name: 'shown', type: 'boolean', required: true, constraint: 'True if the TUI pane was spawned; false when not in tmux (deck surfaces in `human inbox`).' },
+            { name: 'queued', type: 'boolean', required: true, constraint: 'Always true — the notify deck is durable inbox state the human acknowledges from the popup.' },
             { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding deck.json.' },
         ],
         outputKind: 'object',
         effects: [
-            'Writes a notify deck to the per-project interactions root.',
-            'Spawns the acknowledgement TUI in a detached tmux pane when in tmux. Creates no node.',
+            'Enqueues a durable notify deck in the per-project human inbox. Creates no node; nothing opens on screen.',
         ],
     },
     run: async (input) => {
         const title = input['title'];
         const body = input['body'];
-        const deck = notifyDeck(title, body !== undefined ? { body } : {});
+        let deck = notifyDeck(title, body !== undefined ? { body } : {});
+        // Stamp LAST so nodeId cannot be spoofed (see humanAsk).
+        deck = { ...deck, source: { ...(deck.source ?? {}), ...sourceStamp() } };
         const cwd = process.cwd();
         const id = `nfy-${randomBytes(4).toString('hex')}`;
         const idir = interactionDir(id, cwd);
         mkdirSync(idir, { recursive: true });
-        atomicWriteJson(deckPath(idir), deck);
         const rc = { mode: 'notify' };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        let shown = false;
-        if (tmuxServerReachable()) {
-            shown = detachHumanTui(idir, cwd).status === 'spawned';
-        }
-        return { shown, dir: idir };
+        const root = registerCrouterRoot(cwd);
+        const { dir } = submitDeck({ root, id, deck });
+        return { queued: true, dir };
     },
 });
 // ---------------------------------------------------------------------------
-// show (no job, non-blocking passthrough)
+// show (no job, non-blocking passthrough) — passive live document display, NOT
+// a ticket surface. Retained per the tmux-inbox cutover: `display()` puts a
+// file live in a watch pane and never enqueues anything.
 // ---------------------------------------------------------------------------
 export const humanShow = defineLeaf({
     name: 'show',

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

@@ -1,32 +1,5 @@
-/** Deliver-back + reap an interaction whose answer is on disk but was never
- *  delivered. The detached `_run` worker's `pushFinal` is normally the SOLE
- *  deliver-back + reap step; when it never ran (e.g. a broker asker pre-fix, or
- *  a human draining via `crtr human inbox`, which writes response.json directly
- *  and never calls pushFinal), the answer strands and the bridge node leaks.
- *
- *  Idempotent and self-gating: a no-op unless the bridge node is still LIVE
- *  (active|idle) AND its interaction is resolved on disk — so it never
- *  double-delivers an interaction the `_run` worker already finalized (pushFinal
- *  flips status=done). Reconstructs the same pushFinal body `_run` would have
- *  emitted, per mode; a canceled-on-disk response reaps the node without
- *  delivering a result (mirrors `human cancel`). Returns true iff it acted. */
-export declare function finalizeResolvedInteraction(jobId: string, claim?: InteractionClaim): Promise<boolean>;
-/** Sweep every interaction under the cwd's interactions root and deliver-back +
- *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
- *  Interaction dir names ARE the bridge node ids. Returns how many it healed. */
-export declare function healStrandedInteractions(cwd: string): Promise<number>;
-export declare const humanInbox: import("../../core/command.js").LeafDef;
 export declare const humanList: import("../../core/command.js").LeafDef;
 export declare const humanDeck: import("../../core/command.js").LeafDef;
-interface InteractionClaim {
-    release: () => void;
-}
-export declare function acquireInteractionClaim(dir: string, jobId: string, opts?: {
-    allowResolved?: boolean;
-    markProgress?: boolean;
-    respectProgress?: boolean;
-}): InteractionClaim | 'already_resolved' | 'claimed';
 export declare const humanResolve: import("../../core/command.js").LeafDef;
 export declare const humanCancel: import("../../core/command.js").LeafDef;
-export declare const humanRun: import("../../core/command.js").LeafDef;
-export {};
+export declare const humanDeliver: import("../../core/command.js").LeafDef;