@crouton-kit/humanloop 0.3.11 → 0.3.13

package/dist/cli.js

@@ -558,19 +558,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 +614,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 +655,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);
@@ -657,7 +679,9 @@ viewCmd
     .command('show')
     .description('Render a file live in a tmux pane — passive, no result.\n' +
     '\n' +
-    'stdin  { path: string (required), watch?: bool=true, window?: "split"|"new"="split" }\n' +
+    'The pane always watches the file and live-updates on every save.\n' +
+    '\n' +
+    'stdin  { path: string (required), window?: "split"|"new"="split" }\n' +
     'stdout { pane_id: string|null, reason: string|null }\n' +
     'exit   0 always (not-in-tmux / renderer-unavailable is NOT an error)\n')
     .helpOption('-h, --help', 'Show help')
@@ -667,9 +691,8 @@ viewCmd
         emitError({ error: 'bad_input', message: 'path is required', field: 'path', next: 'Provide: {"path": "/abs/path/file.md"}' });
     }
     const absPath = resolve(input.path);
-    const watch = input.watch !== false;
     const window = input.window === 'new' ? 'new' : 'split';
-    const res = display(absPath, { watch, window });
+    const res = display(absPath, { window });
     if (res.paneId) {
         process.stdout.write(JSON.stringify({ pane_id: res.paneId, reason: null }) + '\n');
     }

package/dist/render/termrender.d.ts

@@ -21,8 +21,6 @@ export declare function checkMarkdown(md: string): {
     error: string;
 };
 export interface DisplayInPaneOpts {
-    /** Pass watch so the pane live-updates on file edits. Default true. */
-    watch?: boolean;
     /** Open in a new tmux window instead of splitting the current one. */
     newWindow?: boolean;
 }

package/dist/render/termrender.js

@@ -263,9 +263,8 @@ export function displayInPane(path, opts = {}) {
     ensureRenderer();
     if (rendererState !== 'ready')
         return {};
-    const args = ['pane', 'open', path];
-    if (opts.watch !== false)
-        args.push('--watch');
+    // Always watch: a displayed pane is a live view of the file by definition.
+    const args = ['pane', 'open', path, '--watch'];
     args.push('--window', opts.newWindow ? 'new' : 'split');
     const result = spawnSync(VENV_BIN, args, {
         encoding: 'utf-8',

package/dist/surfaces/display.js

@@ -10,10 +10,10 @@ export function countPanesInCurrentWindow() {
     return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
 }
 export function display(path, opts) {
-    const watch = opts?.watch !== false;
     const window = (opts?.window === 'split' || opts?.window === 'new') ? opts.window : 'auto';
     const maxPanes = (opts?.maxPanes !== undefined && opts.maxPanes > 0) ? opts.maxPanes : 3;
     const newWindow = window === 'new' ||
         (window === 'auto' && countPanesInCurrentWindow() >= maxPanes);
-    return displayInPane(path, { watch, newWindow });
+    // The pane always watches the file — displayed docs are live by definition.
+    return displayInPane(path, { newWindow });
 }

package/dist/types.d.ts

@@ -146,10 +146,9 @@ export interface InboxItem {
     blockedSince: string;
     source?: DeckSource;
 }
-/** Options for `display()` — the live-watch tmux pane surface. */
+/** Options for `display()` — the live-watch tmux pane surface. The pane always
+ *  watches the file and live-updates on edits; there is no non-watched mode. */
 export interface DisplayOpts {
-    /** Pass `--watch` so the pane live-updates on edits. Default true. */
-    watch?: boolean;
     /** `'auto'` (default) splits until the pane budget, then opens a new window. */
     window?: 'auto' | 'split' | 'new';
     /** Pane budget per window before `'auto'` opens a new window. Default 3. */

package/package.json

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