@crouton-kit/humanloop 0.3.12 → 0.3.14

package/dist/api.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { resolveInteractionDir } from './tui/app.js';
 import { scanInbox } from './inbox/scan.js';
 import { pickFromInbox } from './inbox/tui.js';
-import { deckPath, atomicWriteJson, readJson } from './inbox/convention.js';
+import { deckPath, atomicWriteJson, readJson, stampCanvasNode } from './inbox/convention.js';
 import { getTerminalSize } from './tui/terminal.js';
 import { approveDeck, notifyDeck } from './inbox/deck-factories.js';
 const RESPONSE_SCHEMA_ID = 'humanloop.response/v2';
@@ -61,6 +61,7 @@ function buildSummary(deck, responses) {
 export async function ask(deck, opts = {}) {
     const dir = opts.dir ?? managedDir();
     mkdirSync(dir, { recursive: true });
+    stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {
         sessionId: opts.sessionId,

package/dist/cli.js

@@ -11,7 +11,7 @@ import { ask, inbox } from './api.js';
 import { display } from './surfaces/display.js';
 import { renderMarkdown, checkMarkdown } from './render/termrender.js';
 import { scanInbox } from './inbox/scan.js';
-import { deckPath, atomicWriteJson, readJson, responsePath, } from './inbox/convention.js';
+import { deckPath, atomicWriteJson, readJson, responsePath, stampCanvasNode, } from './inbox/convention.js';
 // ── Version ───────────────────────────────────────────────────────────────────
 const HL_VERSION = '0.2.1';
 function emitError(err, exitCode = 1) {
@@ -372,6 +372,7 @@ deckCmd
     }
     const dir = input.dir ? resolve(input.dir) : mkdtempSync(join(tmpdir(), 'hl-ix-'));
     mkdirSync(dir, { recursive: true });
+    stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const jobId = basename(dir);
     const visuals = input.visuals !== false;
@@ -558,19 +559,20 @@ function parseValidationErrors(e) {
 const reviewCmd = program.command('review').description('Markdown document review with anchored comments.');
 reviewCmd
     .command('open')
-    .description('Kickoff: spawn the read-only editor review and return immediately.\n' +
+    .description('Open a read-only editor review and BLOCK until the human submits.\n' +
     '\n' +
     'stdin  { file: string (required, .md), output?: string|null,\n' +
     '         editor?: string|null, tmux?: bool=true }\n' +
-    'stdout { job_id: string, output: string (absolute), follow_up: string }\n' +
+    'stdout { job_id: string, output: string (absolute),\n' +
+    '         status: "done"|"failed"|"canceled", result?: FeedbackResult }\n' +
     '\n' +
-    'Effects: spawns nvim/vim read-only DETACHED in a tmux pane when tmux=true\n' +
-    '         and $TMUX set; returns before the human starts. Writes\n' +
+    'Effects: spawns nvim/vim read-only in a tmux pane when tmux=true and $TMUX\n' +
+    '         set, then blocks until the human finishes and submits. Writes\n' +
     '         <dir>/review.vim, <dir>/feedback.json (on finish), <dir>/job.log.\n' +
     '         autosaves feedback JSON; the open pane live-reloads the source on\n' +
     '         disk edits. The review is open-ended (a human may take many\n' +
-    '         minutes) — collect via `hl job result` with wait:true, run\n' +
-    '         backgrounded so the call does not block on the human.\n')
+    '         minutes) — if you want to keep working, run this BACKGROUNDED; your\n' +
+    '         harness notifies you when it returns with the result.\n')
     .helpOption('-h, --help', 'Show help')
     .action(async () => {
     const input = parseStdinJson();
@@ -613,12 +615,32 @@ reviewCmd
             appendJobLog(jobDir, { level: 'error', event: 'job_failed', message: `tmux spawn failed: ${msg}` });
             emitError({ error: 'internal', message: `tmux spawn failed: ${msg}`, next: 'Check that $TMUX is set. Or pass tmux:false.' });
         }
-        process.stdout.write(JSON.stringify({
-            job_id: jobId,
-            output,
-            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes the review. They may take many minutes — run this backgrounded; you will be notified on completion.`,
-        }) + '\n');
-        process.exit(0);
+        // BLOCK until the human submits (or the job ends). The review is
+        // open-ended — a human may take many minutes — so callers that want to
+        // keep working should background this invocation; their harness notifies
+        // them when it returns. Poll the shared job dir for feedback.json the
+        // same way `hl job result --wait` does.
+        await new Promise((resolvePromise) => {
+            const poll = setInterval(() => {
+                const fp = join(jobDir, 'feedback.json');
+                if (existsSync(fp)) {
+                    const result = tryParseJson(readFileSync(fp, 'utf8'));
+                    if (result !== null) {
+                        clearInterval(poll);
+                        process.stdout.write(JSON.stringify({ job_id: jobId, output, status: 'done', result }) + '\n');
+                        process.exit(0);
+                    }
+                }
+                const state = detectJobState(jobDir);
+                if (state === 'failed' || state === 'canceled') {
+                    clearInterval(poll);
+                    process.stdout.write(JSON.stringify({ job_id: jobId, output, status: state }) + '\n');
+                    process.exit(state === 'canceled' ? 0 : 1);
+                }
+            }, 200);
+            void resolvePromise;
+        });
+        return;
     }
     // In-process path: the detached child (this pane is its TTY), or a degraded
     // top-level call with no tmux. launchReview blocks until the editor exits.
@@ -634,7 +656,8 @@ reviewCmd
         process.stdout.write(JSON.stringify({
             job_id: jobId,
             output,
-            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to retrieve the feedback.`,
+            status: 'done',
+            result,
             ...(input.dir ? {} : { _note: 'No tmux: launchReview blocked synchronously. Result is already available.' }),
         }) + '\n');
         process.exit(0);

package/dist/inbox/convention.d.ts

@@ -1,4 +1,4 @@
-import type { InteractionResponse } from '../types.js';
+import type { Deck, InteractionResponse } from '../types.js';
 export declare function deckPath(dir: string): string;
 export declare function responsePath(dir: string): string;
 export declare function progressPath(dir: string): string;
@@ -10,6 +10,15 @@ export declare function interactionState(dir: string): InteractionState;
 export declare function isResolved(dir: string): boolean;
 /** Returns true if a live resolver owns this dir (progress.json mtime < 300s). */
 export declare function isClaimed(dir: string): boolean;
+/**
+ * Stamp the originating canvas node id onto a deck's `source` so per-node
+ * attention scoping (crouter's nav chrome) can attribute the ask to the node
+ * that raised it rather than every sibling node sharing the same cwd.
+ *
+ * No-op when not inside a canvas node (CRTR_NODE_ID unset) or when the deck
+ * already carries a nodeId. Mutates `deck` in place.
+ */
+export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 export declare function readJson<T>(path: string): T | null;
 export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string): string;

package/dist/inbox/convention.js

@@ -47,6 +47,23 @@ export function isClaimed(dir) {
         return false;
     }
 }
+// ── Canvas-node attribution ─────────────────────────────────────────
+/**
+ * Stamp the originating canvas node id onto a deck's `source` so per-node
+ * attention scoping (crouter's nav chrome) can attribute the ask to the node
+ * that raised it rather than every sibling node sharing the same cwd.
+ *
+ * No-op when not inside a canvas node (CRTR_NODE_ID unset) or when the deck
+ * already carries a nodeId. Mutates `deck` in place.
+ */
+export function stampCanvasNode(deck) {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id.trim() === '')
+        return;
+    if (deck.source?.nodeId != null && deck.source.nodeId !== '')
+        return;
+    deck.source = { ...(deck.source ?? {}), nodeId: id };
+}
 // ── Atomic I/O ────────────────────────────────────────────────────────────────
 export function atomicWriteJson(path, value) {
     const payload = JSON.stringify(value, null, 2);

package/dist/inbox/deck-schema.d.ts

@@ -18,6 +18,7 @@ export declare const deckSchema: z.ZodObject<{
         sessionName: z.ZodOptional<z.ZodString>;
         askedBy: z.ZodOptional<z.ZodString>;
         blockedSince: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     interactions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;

package/dist/inbox/deck-schema.js

@@ -33,6 +33,7 @@ const deckSourceSchema = z.object({
     sessionName: z.string().optional(),
     askedBy: z.string().optional(),
     blockedSince: z.string().optional(),
+    nodeId: z.string().optional(),
 });
 export const deckSchema = z.object({
     title: z.string().optional(),

package/dist/types.d.ts

@@ -54,6 +54,10 @@ export interface DeckSource {
     sessionName?: string;
     askedBy?: string;
     blockedSince?: string;
+    /** Originating canvas node id (CRTR_NODE_ID) when the ask was raised inside
+     *  a crouter canvas node. Lets per-node attention scoping attribute the ask
+     *  to the node that raised it rather than every sibling sharing the cwd. */
+    nodeId?: string;
 }
 export interface Deck {
     title?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",