@crouton-kit/humanloop 0.4.4 → 0.4.5

package/dist/editor/parked.d.ts

@@ -0,0 +1,16 @@
+import type { FeedbackResult } from '../types.js';
+export type ParkedReviewAction = {
+    type: 'submitted';
+    result: FeedbackResult;
+} | {
+    type: 'take-back';
+} | {
+    type: 'cancel';
+};
+/**
+ * Park the terminal while the browser owns the review. Watches raw stdin for
+ * `w` (take back) and Ctrl+C (cancel), racing those against the browser's
+ * submit promise. `takeBackTarget` names the surface `w` returns to in the
+ * parked notice (e.g. "nvim", "the terminal review").
+ */
+export declare function waitForParkedReviewSubmit(submitted: Promise<FeedbackResult>, signal: AbortSignal | undefined, takeBackTarget: string): Promise<ParkedReviewAction>;

package/dist/editor/parked.js

@@ -0,0 +1,50 @@
+/**
+ * Park the terminal while the browser owns the review. Watches raw stdin for
+ * `w` (take back) and Ctrl+C (cancel), racing those against the browser's
+ * submit promise. `takeBackTarget` names the surface `w` returns to in the
+ * parked notice (e.g. "nvim", "the terminal review").
+ */
+export async function waitForParkedReviewSubmit(submitted, signal, takeBackTarget) {
+    process.stderr.write('\nhumanloop: browser review handoff is active.\n' +
+        '  The terminal surface is parked; the browser is the editing authority.\n' +
+        `  Press w to take back into ${takeBackTarget}, or Ctrl+C to exit with an unsubmitted draft.\n\n`);
+    return new Promise((resolveAction) => {
+        const stdin = process.stdin;
+        const interactive = stdin.isTTY;
+        const wasRaw = stdin.isRaw;
+        let settled = false;
+        const cleanup = () => {
+            signal?.removeEventListener('abort', onAbort);
+            if (!interactive)
+                return;
+            stdin.off('data', onData);
+            if (stdin.setRawMode)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+        };
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolveAction(action);
+        };
+        const onAbort = () => finish({ type: 'cancel' });
+        const onData = (chunk) => {
+            const text = chunk.toString('utf8');
+            if (text === 'w' || text === 'W')
+                finish({ type: 'take-back' });
+            if (text === '\u0003')
+                finish({ type: 'cancel' });
+        };
+        if (interactive) {
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.on('data', onData);
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        submitted.then((result) => finish({ type: 'submitted', result }), () => finish({ type: 'cancel' }));
+    });
+}

package/dist/editor/review.d.ts

@@ -12,7 +12,8 @@ export interface ReviewOptions {
     onClose?: () => Promise<void> | void;
     /** Controller cancellation closes the editor/browser handoff without proposing a result. */
     signal?: AbortSignal;
-    /** Reuse this controller-owned directory for `review.vim`; an existing script is left untouched. */
+    /** Reuse this controller-owned directory for review artifacts (`review.vim`,
+     *  the browser-handoff job id); an existing script is left untouched. */
     jobDir?: string;
 }
 export declare function reviewVimscript(): string;

package/dist/editor/review.js

@@ -6,6 +6,7 @@ import { openBrowser } from '../browser/open.js';
 import { startReviewWebServer } from '../browser/server.js';
 import { buildFinalFeedbackResult, readReviewDraft, } from './feedback.js';
 import { launchTerminalReview } from './terminal-review.js';
+import { waitForParkedReviewSubmit } from './parked.js';
 function resolveEditor(override) {
     const candidates = override ? [override] : ['nvim', 'vim'];
     for (const bin of candidates) {
@@ -551,50 +552,6 @@ function draftFeedback(path, absFile) {
         savedAt: draft?.savedAt ?? new Date().toISOString(),
     };
 }
-async function waitForParkedReviewSubmit(submitted, signal) {
-    process.stderr.write('\nhumanloop: browser review handoff is active.\n' +
-        '  The terminal editor is parked; the browser is the editing authority.\n' +
-        '  Press w to take back into nvim, or Ctrl+C to exit with an unsubmitted draft.\n\n');
-    return new Promise((resolveAction) => {
-        const stdin = process.stdin;
-        const interactive = stdin.isTTY;
-        const wasRaw = stdin.isRaw;
-        let settled = false;
-        const cleanup = () => {
-            signal?.removeEventListener('abort', onAbort);
-            if (!interactive)
-                return;
-            stdin.off('data', onData);
-            if (stdin.setRawMode)
-                stdin.setRawMode(wasRaw);
-            stdin.pause();
-        };
-        const finish = (action) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            resolveAction(action);
-        };
-        const onAbort = () => finish({ type: 'cancel' });
-        const onData = (chunk) => {
-            const text = chunk.toString('utf8');
-            if (text === 'w' || text === 'W')
-                finish({ type: 'take-back' });
-            if (text === '\u0003')
-                finish({ type: 'cancel' });
-        };
-        if (interactive) {
-            stdin.setRawMode(true);
-            stdin.resume();
-            stdin.on('data', onData);
-        }
-        signal?.addEventListener('abort', onAbort, { once: true });
-        if (signal?.aborted)
-            onAbort();
-        submitted.then((result) => finish({ type: 'submitted', result }), () => finish({ type: 'cancel' }));
-    });
-}
 async function stopReviewServer(handle) {
     if (handle !== null)
         await handle.stop();
@@ -690,12 +647,16 @@ async function launchNeovimReview(file, opts) {
                 server.activate();
                 process.stderr.write(`humanloop: browser review handoff active — ${server.url}\n`);
                 openBrowser(server.url);
-                const action = await waitForParkedReviewSubmit(submitted, opts.signal);
+                const action = await waitForParkedReviewSubmit(submitted, opts.signal, 'nvim');
                 if (action.type === 'submitted') {
                     await stopReviewServer(server);
                     clearFlag(handoffFlagPath);
-                    if (!opts.signal?.aborted)
-                        await opts.onPropose?.(action.result);
+                    // An abort landing during the async stop must not produce a submitted
+                    // result whose canonical onPropose convergence was skipped — fall
+                    // back to the disk draft (the browser submit already persisted it).
+                    if (opts.signal?.aborted)
+                        return draftFeedback(outPath, absFile);
+                    await opts.onPropose?.(action.result);
                     return action.result;
                 }
                 if (action.type === 'take-back') {
@@ -711,9 +672,12 @@ async function launchNeovimReview(file, opts) {
             }
             await stopReviewServer(server);
             if (existsSync(submitFlagPath)) {
+                // Same abort-during-stop race as the parked branch above: an aborted
+                // review must resolve as a draft, never as an unconverged proposal.
+                if (opts.signal?.aborted)
+                    return draftFeedback(outPath, absFile);
                 const proposal = proposedFeedback(outPath, absFile);
-                if (!opts.signal?.aborted)
-                    await opts.onPropose?.(proposal);
+                await opts.onPropose?.(proposal);
                 return proposal;
             }
             return draftFeedback(outPath, absFile);

package/dist/editor/terminal-review.d.ts

@@ -107,9 +107,11 @@ export declare function renderReviewFrame(state: ReviewState, fileLabel: string,
  * document renders via termrender (Mermaid included), the anchor is a
  * highlighted block in the rendered document itself (gutter bar + tint via
  * termrender's row→source map), and the human explicitly submits a proposal.
- * Never edits the source file. Autosaves the comment draft to `opts.output`
- * (the `progress.json` convention). Canonical ticket finalization stays with
- * the caller's `onPropose` (the adapter calls `completeReview`); this function
- * never writes `response.json`.
+ * `space w` hands the review off to the browser surface (same park/take-back
+ * semantics as the Neovim path); the draft round-trips between surfaces via
+ * `opts.output`. Never edits the source file. Autosaves the comment draft to
+ * `opts.output` (the `progress.json` convention). Canonical ticket
+ * finalization stays with the caller's `onPropose` (the adapter calls
+ * `completeReview`); this function never writes `response.json`.
  */
 export declare function launchTerminalReview(file: string, opts: ReviewOptions): Promise<FeedbackResult>;

package/dist/editor/terminal-review.js

@@ -1,7 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
 import stringWidth from 'string-width';
+import { waitForParkedReviewSubmit } from './parked.js';
+import { openBrowser } from '../browser/open.js';
+import { startReviewWebServer } from '../browser/server.js';
 import { buildDraftFeedbackResult, buildFinalFeedbackResult, readReviewDraft, writeReviewDraft } from './feedback.js';
 import { renderMarkdownWithMap } from '../render/termrender.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress } from '../tui/terminal.js';
@@ -280,7 +284,7 @@ export function reservedRows(state, cols) {
     }
     if (state.mode === 'list')
         return header + Math.max(1, state.comments.length) + 2;
-    return header + 8; // help
+    return header + 9; // help
 }
 export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
     const maxW = Math.min(Math.max(20, cols - 4), 120);
@@ -321,13 +325,14 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
         footer.push(`  ${DIM}u/d, pgup/pgdn${RESET}  scroll document`);
         footer.push(`  ${DIM}space c${RESET}     compose comment        ${DIM}space l${RESET}     list comments`);
         footer.push(`  ${DIM}space u${RESET}     undo last comment      ${DIM}space s${RESET}     submit review`);
+        footer.push(`  ${DIM}space w${RESET}     hand off to browser`);
         footer.push(`  ${DIM}?${RESET}           toggle this help       ${DIM}esc${RESET}         close/cancel`);
         footer.push('');
         footer.push(`  ${DIM}esc / ?${RESET} close`);
     }
     else {
         footer.push(`  ${DIM}j/k${RESET} block  ${DIM}shift-j/k${RESET} extend  ${DIM}u/d${RESET} scroll  ${DIM}space c${RESET} comment  ` +
-            `${DIM}space l${RESET} list  ${DIM}space u${RESET} undo  ${DIM}space s${RESET} submit  ${DIM}?${RESET} help  ${DIM}esc${RESET} close`);
+            `${DIM}space l${RESET} list  ${DIM}space u${RESET} undo  ${DIM}space s${RESET} submit  ${DIM}space w${RESET} browser  ${DIM}?${RESET} help  ${DIM}esc${RESET} close`);
     }
     const reserved = header.length + footer.length;
     const bodyHeight = Math.max(1, rows - reserved);
@@ -363,26 +368,85 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
         lines.push('');
     return lines.slice(0, rows);
 }
-// ── Host loop (impure — the only part that touches the real TTY) ───────────
+function diskDraftResult(absFile, outPath) {
+    const draft = readReviewDraft(outPath);
+    return buildDraftFeedbackResult(absFile, draft?.comments ?? [], draft?.savedAt);
+}
 /**
  * Open a Markdown file in humanloop's own terminal review surface: the
  * document renders via termrender (Mermaid included), the anchor is a
  * highlighted block in the rendered document itself (gutter bar + tint via
  * termrender's row→source map), and the human explicitly submits a proposal.
- * Never edits the source file. Autosaves the comment draft to `opts.output`
- * (the `progress.json` convention). Canonical ticket finalization stays with
- * the caller's `onPropose` (the adapter calls `completeReview`); this function
- * never writes `response.json`.
+ * `space w` hands the review off to the browser surface (same park/take-back
+ * semantics as the Neovim path); the draft round-trips between surfaces via
+ * `opts.output`. Never edits the source file. Autosaves the comment draft to
+ * `opts.output` (the `progress.json` convention). Canonical ticket
+ * finalization stays with the caller's `onPropose` (the adapter calls
+ * `completeReview`); this function never writes `response.json`.
  */
 export async function launchTerminalReview(file, opts) {
     const absFile = resolve(file);
     const content = readFileSync(absFile, 'utf8');
-    const sourceLines = content.split('\n');
     const outPath = resolve(opts.output);
-    const draft = readReviewDraft(outPath);
     const fileLabel = basename(absFile);
-    if (opts.signal?.aborted)
-        return buildDraftFeedbackResult(absFile, draft?.comments ?? [], draft?.savedAt);
+    // Created lazily on the first browser handoff, reused across take-backs.
+    let jobDir = opts.jobDir ?? null;
+    while (true) {
+        if (opts.signal?.aborted)
+            return diskDraftResult(absFile, outPath);
+        const outcome = await runTerminalReviewSession(absFile, content, outPath, fileLabel, opts);
+        if (outcome.type === 'done')
+            return outcome.result;
+        // Browser handoff: the TUI is parked (terminal already restored, draft
+        // persisted); the browser is the editing authority until it submits, the
+        // human takes back with `w`, or the review is cancelled.
+        if (jobDir === null)
+            jobDir = mkdtempSync(join(tmpdir(), 'hl-review-'));
+        let resolveSubmitted;
+        const submitted = new Promise((resolveSubmittedPromise) => {
+            resolveSubmitted = resolveSubmittedPromise;
+        });
+        const server = await startReviewWebServer({
+            jobDir,
+            file: absFile,
+            output: outPath,
+            onSubmit: (result) => resolveSubmitted(result),
+        });
+        if (opts.signal?.aborted) {
+            await server.stop();
+            return diskDraftResult(absFile, outPath);
+        }
+        server.activate();
+        process.stderr.write(`humanloop: browser review handoff active — ${server.url}\n`);
+        openBrowser(server.url);
+        const action = await waitForParkedReviewSubmit(submitted, opts.signal, 'the terminal review');
+        if (action.type === 'submitted') {
+            await server.stop();
+            // An abort landing during the async stop() must not produce a submitted
+            // result whose canonical onPropose convergence was skipped — fall back
+            // to the disk draft (the browser submit already persisted its comments).
+            if (opts.signal?.aborted)
+                return diskDraftResult(absFile, outPath);
+            await opts.onPropose?.(action.result);
+            return action.result;
+        }
+        if (action.type === 'take-back') {
+            await server.requestTakeBack();
+            await server.stop();
+            process.stderr.write('humanloop: taking review back into the terminal review.\n');
+            continue; // re-enter the TUI; the next session re-reads the draft from disk
+        }
+        await server.stop();
+        return diskDraftResult(absFile, outPath);
+    }
+}
+/** One TUI session over the document. Resolves when the review reaches a
+ *  final result (submit/close/cancel) or the human requests browser handoff;
+ *  either way the terminal is restored before resolution. Re-reads the draft
+ *  from disk on entry so browser edits survive a take-back. */
+function runTerminalReviewSession(absFile, content, outPath, fileLabel, opts) {
+    const sourceLines = content.split('\n');
+    const draft = readReviewDraft(outPath);
     setupTerminal();
     let { cols, rows } = getTerminalSize();
     let doc = renderMarkdownWithMap(content, renderWidthForCols(cols));
@@ -410,7 +474,7 @@ export async function launchTerminalReview(file, opts) {
             process.stdout.write('\x1b[?2026l');
             prevFrame = nextPrevFrame;
         };
-        const finish = (result) => {
+        const finishWith = (outcome) => {
             if (settled)
                 return;
             settled = true;
@@ -418,8 +482,9 @@ export async function launchTerminalReview(file, opts) {
             process.stdout.removeListener('resize', onResize);
             opts.signal?.removeEventListener('abort', onAbort);
             restoreTerminal();
-            resolvePromise(result);
+            resolvePromise(outcome);
         };
+        const finish = (result) => finishWith({ type: 'done', result });
         const onResize = () => {
             ({ cols, rows } = getTerminalSize());
             doc = renderMarkdownWithMap(content, renderWidthForCols(cols));
@@ -575,6 +640,11 @@ export async function launchTerminalReview(file, opts) {
                     void submit();
                     return;
                 }
+                else if (input === 'w') {
+                    persist();
+                    finishWith({ type: 'handoff' });
+                    return;
+                }
                 paint();
                 return;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "engines": {
     "node": ">=22.19.0"