@crouton-kit/humanloop 0.3.37 → 0.3.38

package/dist/inbox/controller.d.ts

@@ -1,11 +1,14 @@
 import type { InteractionResponse, TicketSummary } from '../types.js';
 import type { Key } from '../tui/terminal.js';
+import { startWebServer } from '../browser/server.js';
 export interface InboxControllerOptions {
     roots?: string[];
     cols?: number;
     rows?: number;
     scan?: (roots?: string[]) => TicketSummary[];
     completeDeck?: (dir: string, responses: InteractionResponse[], token: string) => Promise<unknown>;
+    startDeckBrowser?: typeof startWebServer;
+    openBrowser?: (url: string) => void;
 }
 type Screen = 'list' | 'detail';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
@@ -19,6 +22,8 @@ export declare class InboxController {
     private screen;
     private adapter;
     private reviewAdapter;
+    private deckBrowser;
+    private deckBrowserStarting;
     private claim;
     private reconciling;
     private suspended;
@@ -51,6 +56,12 @@ export declare class InboxController {
      *  in ReviewAdapter; the controller only owns the terminal handoff. */
     private activateReview;
     reloadSelectedDeck(): void;
+    /** Hand the selected deck to its browser surface while retaining this ticket's claim. */
+    private openDeckBrowser;
+    /** The browser has atomically published the response; reconcile its owner delivery. */
+    private finishDeckBrowser;
+    /** Return browser authority to the terminal deck without changing its draft. */
+    private takeBackDeckBrowser;
     close(): void;
     run(): Promise<void>;
     private complete;

package/dist/inbox/controller.js

@@ -2,6 +2,9 @@ import { readFileSync, watch } from 'node:fs';
 import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
 import { diffFrame } from '../tui/render.js';
 import { renderMarkdown } from '../render/termrender.js';
+import { startWebServer } from '../browser/server.js';
+import { openBrowser } from '../browser/open.js';
+import { renderHandoff } from '../tui/render.js';
 import { BOLD, CYAN, DIM, GRAY, RESET, YELLOW, clipLine } from '../tui/ansi.js';
 import { buildInboxLines } from './tui.js';
 import { inboxLayout } from './layout.js';
@@ -24,6 +27,8 @@ export class InboxController {
     screen = 'list';
     adapter;
     reviewAdapter;
+    deckBrowser;
+    deckBrowserStarting = false;
     claim;
     reconciling = false;
     suspended = false;
@@ -121,7 +126,16 @@ export class InboxController {
             this.close();
             return;
         }
+        if (this.deckBrowser !== undefined) {
+            if (input === 'w' || input === 'W')
+                void this.takeBackDeckBrowser();
+            return;
+        }
         if (this.screen === 'detail' && this.adapter !== undefined) {
+            if ((input === 'w' || input === 'W') && this.adapter.canAcceptHostKeys()) {
+                void this.openDeckBrowser();
+                return;
+            }
             this.adapter.handleKey(input, key);
             this.repaint();
             return;
@@ -221,11 +235,69 @@ export class InboxController {
         }
     }
     reloadSelectedDeck() { this.adapter?.reload(); this.repaint(); }
+    /** Hand the selected deck to its browser surface while retaining this ticket's claim. */
+    async openDeckBrowser() {
+        if (this.deckBrowser !== undefined || this.deckBrowserStarting || this.adapter === undefined || this.claim === undefined)
+            return;
+        const item = this.items[this.selectedIndex];
+        if (item?.kind !== 'deck' || item.dir !== this.claim.dir)
+            return;
+        const deck = readJson(deckPath(item.dir));
+        if (deck === null)
+            return;
+        this.deckBrowserStarting = true;
+        try {
+            const start = this.options.startDeckBrowser ?? startWebServer;
+            let browser;
+            browser = await start({
+                dir: item.dir,
+                deck,
+                onSubmit: () => { void this.finishDeckBrowser(item.dir, browser); },
+            });
+            this.deckBrowser = browser;
+            (this.options.openBrowser ?? openBrowser)(browser.url);
+        }
+        catch (error) {
+            this.status = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.deckBrowserStarting = false;
+            this.repaint();
+        }
+    }
+    /** The browser has atomically published the response; reconcile its owner delivery. */
+    async finishDeckBrowser(dir, browser) {
+        if (this.deckBrowser === browser)
+            this.deckBrowser = undefined;
+        await browser.stop();
+        if (this.claim?.dir === dir)
+            this.leaveDetail();
+        this.rescan();
+        this.reconcileRoots();
+        this.repaint();
+    }
+    /** Return browser authority to the terminal deck without changing its draft. */
+    async takeBackDeckBrowser() {
+        const browser = this.deckBrowser;
+        if (browser === undefined)
+            return;
+        this.deckBrowser = undefined;
+        try {
+            await browser.requestTakeBack();
+            await browser.stop();
+        }
+        finally {
+            this.repaint(true);
+        }
+    }
     close() {
         if (this.closed)
             return;
         this.closed = true;
         void this.reviewAdapter?.stop();
+        const browser = this.deckBrowser;
+        this.deckBrowser = undefined;
+        void browser?.stop();
         this.leaveDetail();
         for (const watcher of this.watchers)
             watcher.close();
@@ -355,6 +427,10 @@ export class InboxController {
         return { cols: Math.max(1, layout.detailWidth - 2), rows: layout.height };
     }
     detailLines(width, rows) {
+        if (this.deckBrowser !== undefined)
+            return renderHandoff(this.deckBrowser.url, width, rows);
+        if (this.deckBrowserStarting)
+            return [`  ${DIM}Opening browser review…${RESET}`];
         if (this.adapter !== undefined)
             return this.adapter.render();
         const selected = this.items[this.selectedIndex];

package/dist/render/termrender.js

@@ -1,7 +1,7 @@
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, statSync, openSync, closeSync, unlinkSync, renameSync, accessSync, realpathSync, constants, } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, statSync, mkdirSync, openSync, closeSync, unlinkSync, renameSync, accessSync, realpathSync, constants, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
 import stringWidth from 'string-width';
 import { TERMRENDER_VERSION } from './version.js';
 // ── The sole org-wide termrender binding ─────────────────────────────────────
@@ -10,23 +10,10 @@ import { TERMRENDER_VERSION } from './version.js';
 // TERMRENDER_VERSION, installed into a venv humanloop owns. The binary is
 // resolved by ABSOLUTE PATH inside that venv — never `$PATH` — so a user's
 // own `pip install termrender` can never shadow or break the pin.
-function findPkgRoot() {
-    let dir = dirname(fileURLToPath(import.meta.url));
-    for (let i = 0; i < 12; i++) {
-        if (existsSync(join(dir, 'package.json')))
-            return dir;
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    // dist/render/termrender.js or src/render/termrender.ts → two up is pkgRoot.
-    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
-}
-const PKG_ROOT = findPkgRoot();
-const VENV_DIR = resolve(PKG_ROOT, '.venv');
-const VENV_BIN = resolve(PKG_ROOT, '.venv/bin/termrender');
-const VENV_PYTHON = resolve(PKG_ROOT, '.venv/bin/python');
+const RENDERER_CACHE_DIR = join(resolve(process.env.XDG_CACHE_HOME || join(homedir(), '.cache')), 'humanloop', 'termrender', TERMRENDER_VERSION);
+const VENV_DIR = join(RENDERER_CACHE_DIR, 'venv');
+const VENV_BIN = join(VENV_DIR, 'bin/termrender');
+const VENV_PYTHON = join(VENV_DIR, 'bin/python');
 // Readiness marker written by the single authoritative provisioning transition
 // after a verified install. It fingerprints the ACTUAL verified environment —
 // launcher + interpreter (mtime, size, mode) and the interpreter's realpath —
@@ -38,11 +25,12 @@ const VENV_PYTHON = resolve(PKG_ROOT, '.venv/bin/python');
 // marker (see invalidateRenderer), so the next process repairs. Together these
 // remove the ~149ms `termrender -h` + `importlib.metadata` spawn tax from the
 // steady path without letting a stale marker trust a broken renderer forever.
-const VENV_STAMP = resolve(PKG_ROOT, '.venv/.hl-termrender-stamp.json');
+const VENV_STAMP = join(VENV_DIR, '.hl-termrender-stamp.json');
 // Provisioning lock — lives OUTSIDE .venv (which `uv venv --clear` wipes) so it
-// survives a reinstall. Serializes venv mutation + stamp publication across
-// processes: a stamp can never certify a concurrently-changing venv.
-const VENV_LOCK = resolve(PKG_ROOT, '.hl-termrender.lock');
+// survives a reinstall. The user cache stays writable when humanloop is installed
+// in a read-only runtime image, and serializes venv mutation + stamp publication
+// across processes: a stamp can never certify a concurrently-changing venv.
+const VENV_LOCK = join(RENDERER_CACHE_DIR, '.hl-termrender.lock');
 // A lock older than this is from a crashed process and may be stolen. Set
 // comfortably above the worst-case held path (uv probe 5s + venv 60s + install
 // 120s + re-verify ~10s ≈ 195s) so a slow-but-alive holder is never judged
@@ -220,6 +208,14 @@ function stealStaleLock() {
     catch { /* best effort */ }
 }
 function withProvisionLock(provision) {
+    try {
+        mkdirSync(RENDERER_CACHE_DIR, { recursive: true });
+    }
+    catch (err) {
+        rendererState = 'unavailable';
+        process.stderr.write(`[hl] termrender unavailable — renderer cache cannot be created (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+        return;
+    }
     const giveUpAt = Date.now() + LOCK_GIVE_UP_MS;
     for (;;) {
         let fd;
@@ -227,8 +223,11 @@ function withProvisionLock(provision) {
             fd = openSync(VENV_LOCK, 'wx'); // O_CREAT | O_EXCL — atomic acquire
         }
         catch (err) {
-            if (err.code !== 'EEXIST')
-                throw err;
+            if (err.code !== 'EEXIST') {
+                rendererState = 'unavailable';
+                process.stderr.write(`[hl] termrender unavailable — renderer cache cannot be locked (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+                return;
+            }
             if (lockIsStale()) {
                 stealStaleLock();
                 continue;

package/dist/tui/render.js

@@ -74,7 +74,7 @@ export function renderOverview(state, cols, rows) {
         lines.push('');
     }
     lines.push(`  ${DIM}${hline(Math.min(cols - 4, 60))}${RESET}`);
-    lines.push(`  ${DIM}enter${RESET} review  ${DIM}j/k${RESET} navigate  ${DIM}q${RESET} finish`);
+    lines.push(`  ${DIM}enter${RESET} review  ${DIM}j/k${RESET} navigate  ${DIM}w${RESET} browser  ${DIM}q${RESET} finish`);
     while (lines.length < rows)
         lines.push('');
     // Overview content extends roughly cols-16 wide for option labels; center
@@ -272,6 +272,8 @@ export function renderItemReview(state, cols, rows) {
     if (overflows) {
         footerParts.unshift(state.inputMode ? `${DIM}pgup/pgdn${RESET} scroll` : `${DIM}u/d${RESET} scroll`);
     }
+    if (state.inputMode === null)
+        footerParts.push(`${DIM}w${RESET} browser`);
     const footer = `  ${footerParts.join('  ')}`;
     // Assemble — pad to fill rows so post-body sits at the bottom
     const lines = [...preLines, ...visibleBody, ...postLines];

package/package.json

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