@crouton-kit/humanloop 0.3.1 → 0.3.4

package/dist/api.js

@@ -55,13 +55,15 @@ export async function ask(deck, opts = {}) {
     const dir = opts.dir ?? managedDir();
     mkdirSync(dir, { recursive: true });
     atomicWriteJson(deckPath(dir), deck);
-    const { responses, completedAt, responsePath } = await resolveInteractionDir(dir, deck, {
+    const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {
         sessionId: opts.sessionId,
         cols: opts.cols,
         rows: opts.rows,
     });
     return {
-        summary: buildSummary(deck, responses),
+        // `answeredDeck` === `deck` unless an agent ran `hl deck update`
+        // mid-flight; the summary must describe the questions actually answered.
+        summary: buildSummary(answeredDeck, responses),
         responsePath,
         schema: RESPONSE_SCHEMA_ID,
         responses,

package/dist/cli.js

@@ -313,7 +313,17 @@ program
     .helpOption('-h, --help', 'Show help')
     .addHelpCommand(false);
 // ── deck ──────────────────────────────────────────────────────────────────────
-const deckCmd = program.command('deck').description('Write questions, get answers from the human.');
+const deckCmd = program.command('deck').description('Write questions, get answers from the human.\n' +
+    '\n' +
+    'Children:\n' +
+    '  hl deck ask      — spawn the decisions TUI, return a job handle | use when: posing material decisions\n' +
+    '  hl deck update   — replace the deck of a LIVE ask job in place   | use when: the questions changed after ask\n' +
+    '  hl deck validate — preflight a deck object, no side effects      | use when: checking a deck before ask\n' +
+    '\n' +
+    'A `deck update` rewrites the live job\'s deck.json; the TUI pane the\n' +
+    'human is looking at reloads it automatically within ~1s (answers whose\n' +
+    'interaction ids still exist are kept). Read this leaf\'s -h before calling\n' +
+    'it — it mutates a session a human is actively in.');
 deckCmd
     .command('ask')
     .description('Kickoff: spawn the decisions TUI and return immediately.\n' +
@@ -324,7 +334,9 @@ deckCmd
     '\n' +
     'Effects: writes <dir>/deck.json, <dir>/progress.json (live),\n' +
     '         <dir>/response.json (on finish), <dir>/job.log (JSONL).\n' +
-    '         Spawns TUI detached in a tmux pane when tmux=true and $TMUX set.\n')
+    '         Spawns TUI detached in a tmux pane when tmux=true and $TMUX set.\n' +
+    '         While the job is live the TUI watches <dir>/deck.json: a later\n' +
+    '         `hl deck update` rewrites it and the pane reloads automatically.\n')
     .helpOption('-h, --help', 'Show help')
     .action(async () => {
     const input = parseStdinJson();
@@ -407,7 +419,7 @@ deckCmd
         process.stdout.write(JSON.stringify({
             job_id: jobId,
             dir,
-            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes.`,
+            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes. If the questions change before they answer, pipe {"job_id":"${jobId}","deck":{...}} to hl deck update — the pane reloads automatically.`,
         }) + '\n');
         process.exit(0);
     }
@@ -435,6 +447,74 @@ deckCmd
         });
     }
 });
+deckCmd
+    .command('update')
+    .description('Replace the deck of a LIVE ask job; the human\'s TUI pane reloads.\n' +
+    '\n' +
+    'stdin  { job_id: string (required), deck: object (required) }\n' +
+    'stdout { ok: true, job_id: string, interactions: int, follow_up: string }\n' +
+    '\n' +
+    'The TUI watches deck.json and reloads within ~1s of this write. Answers\n' +
+    'whose interaction id still exists in the new deck are preserved; new or\n' +
+    'id-changed interactions appear unanswered. In-flight unsubmitted input\n' +
+    '(a comment being typed) is discarded on reload.\n' +
+    '\n' +
+    'Errors: job_not_found (no such job_id) | job_not_live (already\n' +
+    'done/failed/canceled — nothing to reload) | deck_invalid (deck rejected;\n' +
+    'the old deck stays in place, run hl deck validate first).\n' +
+    '\n' +
+    'Effects: atomically rewrites <dir>/deck.json; appends a deck_updated\n' +
+    'event to <dir>/job.log. No effect on response.json/progress.json.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    if (!input.job_id || typeof input.job_id !== 'string') {
+        emitError({ error: 'bad_input', message: 'job_id is required', field: 'job_id', next: 'Provide: {"job_id": "<id>", "deck": {...}}' });
+    }
+    if (!input.deck || typeof input.deck !== 'object') {
+        emitError({ error: 'bad_input', message: 'deck is required and must be an object', field: 'deck', next: "Run: echo '{\"kind\":\"deck\"}' | hl schema show" });
+    }
+    const dir = resolveJobDir(input.job_id);
+    if (!existsSync(dir) || !existsSync(deckPath(dir))) {
+        emitError({ error: 'job_not_found', message: `Job not found: ${input.job_id}`, next: 'Check the job_id returned by hl deck ask.' });
+    }
+    const state = detectJobState(dir);
+    if (state !== 'live') {
+        emitError({
+            error: 'job_not_live',
+            message: `Job is ${state}; its deck can no longer be reloaded.`,
+            received: state,
+            next: 'The human already finished. Start a fresh deck with hl deck ask.',
+        });
+    }
+    let deck;
+    try {
+        const _v = {};
+        void _v;
+        deck = validateDeck(input.deck);
+    }
+    catch (validationErr) {
+        emitError({
+            error: 'deck_invalid',
+            message: `deck validation failed: ${validationErr instanceof Error ? validationErr.message : String(validationErr)}`,
+            received: input.deck,
+            next: "The live deck is unchanged. Fix the deck, then: echo '{\"deck\":{...}}' | hl deck validate",
+        });
+    }
+    atomicWriteJson(deckPath(dir), deck);
+    appendJobLog(dir, {
+        level: 'info', event: 'deck_updated',
+        message: `deck replaced (${deck.interactions.length} interaction(s)); pane reloads on next watch tick`,
+        data: { jobId: basename(dir), interactions: deck.interactions.length },
+    });
+    process.stdout.write(JSON.stringify({
+        ok: true,
+        job_id: basename(dir),
+        interactions: deck.interactions.length,
+        follow_up: `The pane reloads within ~1s. Still resolve with hl job result {"job_id":"${basename(dir)}","wait":true}.`,
+    }) + '\n');
+    process.exit(0);
+});
 deckCmd
     .command('validate')
     .description('Preflight deck validation — no side effects.\n' +

package/dist/render/termrender.js

@@ -44,6 +44,22 @@ function binaryOk() {
         return false;
     }
 }
+// Returns the termrender version installed in the managed venv (via
+// importlib.metadata), or null if the venv is missing/broken or termrender is
+// not installed. Used by ensureRenderer() to detect drift from the pin and
+// trigger a reinstall — otherwise a venv provisioned at an older pin sticks
+// forever (binaryOk passes for any working binary, regardless of version).
+function installedVersion() {
+    if (!existsSync(VENV_PYTHON))
+        return null;
+    try {
+        const out = execFileSync(VENV_PYTHON, ['-c', 'import importlib.metadata as m; print(m.version("termrender"))'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
 function uvAvailable() {
     try {
         execFileSync('uv', ['--version'], { stdio: 'pipe', timeout: 5000 });
@@ -70,7 +86,7 @@ export function ensureRenderer() {
         rendererState = 'unavailable';
         return;
     }
-    if (binaryOk()) {
+    if (binaryOk() && installedVersion() === TERMRENDER_VERSION) {
         rendererState = 'ready';
         return;
     }
@@ -81,7 +97,12 @@ export function ensureRenderer() {
         return;
     }
     try {
-        execFileSync('uv', ['venv', VENV_DIR], { stdio: 'pipe', timeout: 60000 });
+        // Skip venv creation on drift (venv exists with wrong termrender version)
+        // — `uv pip install` into the existing venv replaces it in place. Only
+        // create when the venv directory is genuinely absent.
+        if (!existsSync(VENV_DIR)) {
+            execFileSync('uv', ['venv', VENV_DIR], { stdio: 'pipe', timeout: 60000 });
+        }
         execFileSync('uv', ['pip', 'install', '--python', VENV_PYTHON, `termrender==${TERMRENDER_VERSION}`], { stdio: 'pipe', timeout: 120000 });
     }
     catch (err) {
@@ -89,7 +110,7 @@ export function ensureRenderer() {
         rendererState = 'unavailable';
         return;
     }
-    rendererState = binaryOk() ? 'ready' : 'unavailable';
+    rendererState = (binaryOk() && installedVersion() === TERMRENDER_VERSION) ? 'ready' : 'unavailable';
     if (rendererState === 'unavailable') {
         process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
     }

package/dist/tui/app.d.ts

@@ -18,11 +18,18 @@ export interface ResolveDirOpts {
  * with skips) write `<dir>/response.json` atomically and drop the progress
  * file. A hard process kill leaves `progress.json` for a later resume —
  * `tryResume` (unchanged logic) reads the new dir-derived path.
+ *
+ * While the panel is mounted, `<dir>/deck.json` is polled for changes (an
+ * agent calling `hl deck update`). On a valid rewrite the panel is reloaded
+ * in place via `loadDeck`, so the human's pane reflects the new questions
+ * without a respawn; answers for surviving interaction ids are kept. The
+ * returned `deck` is the one actually answered (post-reload).
  */
 export declare function resolveInteractionDir(dir: string, deck: Deck, opts?: ResolveDirOpts): Promise<{
     responses: InteractionResponse[];
     completedAt: string;
     responsePath: string;
+    deck: Deck;
 }>;
 export declare function launchTui(decisionsPath: string, sessionId?: string): Promise<{
     responses: InteractionResponse[];

package/dist/tui/app.js

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
 import { diffFrame, renderOverview, renderItemReview, renderFinal } from './render.js';
@@ -6,7 +6,7 @@ import { handleKeypress, assignShortcuts } from './input.js';
 import { readConversation } from '../conversation/reader.js';
 import { defaultGenerateVisual } from '../visuals/generate.js';
 import { validateDeck } from '../inbox/deck-schema.js';
-import { progressPath as progressPathFor, writeResponse, clearProgress } from '../inbox/convention.js';
+import { progressPath as progressPathFor, deckPath as deckPathFor, writeResponse, clearProgress } from '../inbox/convention.js';
 /** Validate an arbitrary parsed value as a Deck. Delegates to the canonical
  * Zod validator in `inbox/deck-schema.ts` (the single source of truth shared
  * with sisyphus). Kept exported for back-compat. */
@@ -179,6 +179,11 @@ export function mountPanel(opts) {
                 return false;
             return internals.state.inputMode === null;
         },
+        atDeckTop() {
+            if (!internals.mounted)
+                return true;
+            return internals.state.phase === 'overview' && internals.state.inputMode === null;
+        },
     };
 }
 /**
@@ -187,6 +192,12 @@ export function mountPanel(opts) {
  * with skips) write `<dir>/response.json` atomically and drop the progress
  * file. A hard process kill leaves `progress.json` for a later resume —
  * `tryResume` (unchanged logic) reads the new dir-derived path.
+ *
+ * While the panel is mounted, `<dir>/deck.json` is polled for changes (an
+ * agent calling `hl deck update`). On a valid rewrite the panel is reloaded
+ * in place via `loadDeck`, so the human's pane reflects the new questions
+ * without a respawn; answers for surviving interaction ids are kept. The
+ * returned `deck` is the one actually answered (post-reload).
  */
 export async function resolveInteractionDir(dir, deck, opts = {}) {
     let conversationContext = '';
@@ -212,6 +223,12 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
         let prevFrameLocal = [];
         let lastResponses = [];
         let onData;
+        // The deck the human is actually answering. An agent may replace it
+        // mid-flight via `hl deck update` (atomic deck.json rewrite); the poller
+        // below reloads the panel in place and tracks the live deck here so the
+        // returned envelope/summary describes what was answered, not the kickoff.
+        let currentDeck = deck;
+        let deckWatch = null;
         const flushHost = (lines) => {
             const { rows: currentRows } = getTerminalSize();
             const { writes, nextPrevFrame } = diffFrame(prevFrameLocal, lines, currentRows);
@@ -222,6 +239,10 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             prevFrameLocal = nextPrevFrame;
         };
         const finalize = (responses) => {
+            if (deckWatch !== null) {
+                clearInterval(deckWatch);
+                deckWatch = null;
+            }
             restoreTerminal();
             process.stdin.removeListener('data', onData);
             panel?.unmount();
@@ -229,7 +250,7 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             // Resolved supersedes in-progress: write response.json, drop progress.json.
             const rp = writeResponse(dir, responses, completedAt);
             clearProgress(dir);
-            resolve({ responses, completedAt, responsePath: rp });
+            resolve({ responses, completedAt, responsePath: rp, deck: currentDeck });
         };
         panel = mountPanel({
             deck,
@@ -248,6 +269,49 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             },
         });
         flushHost(panel.render());
+        // ── Live deck reload ──────────────────────────────────────────────────
+        // Poll deck.json mtime (cheap stat; full read only on change). atomicWrite
+        // does write-tmp + rename, so stat/read always see a whole file — no
+        // fs.watch rename flakiness. The TUI never writes deck.json, so there is
+        // no feedback loop. A structurally identical rewrite is ignored so a
+        // no-op touch never disrupts the human mid-answer.
+        const deckFile = deckPathFor(dir);
+        const deckMtime = () => {
+            try {
+                return statSync(deckFile).mtimeMs;
+            }
+            catch {
+                return 0;
+            }
+        };
+        let lastDeckMtime = deckMtime();
+        let lastDeckJson = JSON.stringify(currentDeck);
+        deckWatch = setInterval(() => {
+            if (panel === null)
+                return;
+            const m = deckMtime();
+            if (m === 0 || m === lastDeckMtime)
+                return;
+            lastDeckMtime = m;
+            let nextDeck;
+            try {
+                const parsed = JSON.parse(readFileSync(deckFile, 'utf8'));
+                nextDeck = validateDeck(parsed);
+            }
+            catch {
+                // Mid-rename, invalid, or rejected by schema: keep the live deck,
+                // retry on the next tick. `hl deck update` validates before writing,
+                // so a persistently bad file is an out-of-band edit, not our concern.
+                return;
+            }
+            const nextJson = JSON.stringify(nextDeck);
+            if (nextJson === lastDeckJson)
+                return; // touch / identical content
+            lastDeckJson = nextJson;
+            currentDeck = nextDeck;
+            panel.loadDeck(nextDeck, { progressPath: progressPathFor(dir) });
+            flushHost(panel.render());
+        }, 500);
         onData = (data) => {
             const { input: inp, key } = parseKeypress(data);
             panel.handleKey(inp, key);

package/dist/tui/input.js

@@ -117,7 +117,8 @@ function handleItemReview(input, key, state, render) {
         render();
         return;
     }
-    if (input === 'q') {
+    // q / Esc step back to the deck overview (one level up from a card).
+    if (input === 'q' || key.escape) {
         state.phase = 'overview';
         render();
         return;
@@ -261,6 +262,11 @@ function handleInputMode(input, key, state, render) {
         render();
         return;
     }
+    if (key.backspace && key.meta) {
+        mode.buffer = deleteWordBack(mode.buffer);
+        render();
+        return;
+    }
     if (key.backspace) {
         const chars = [...mode.buffer];
         chars.pop();
@@ -277,11 +283,23 @@ function handleInputMode(input, key, state, render) {
         render();
     }
 }
+function deleteWordBack(buffer) {
+    const chars = [...buffer];
+    while (chars.length > 0 && /\s/.test(chars[chars.length - 1]))
+        chars.pop();
+    while (chars.length > 0 && !/\s/.test(chars[chars.length - 1]))
+        chars.pop();
+    return chars.join('');
+}
 // ── Final ────────────────────────────────────────────────────────────────────
 function handleFinal(input, key, state, render, exit) {
     if (key.return) {
         exit();
     }
+    else if (key.escape) {
+        state.phase = 'overview';
+        render();
+    }
     else if (input === 'p') {
         state.phase = 'item-review';
         state.currentIndex = state.interactions.length - 1;

package/dist/tui/terminal.d.ts

@@ -4,6 +4,7 @@ export interface Key {
     return: boolean;
     escape: boolean;
     ctrl: boolean;
+    meta: boolean;
     tab: boolean;
     backspace: boolean;
 }

package/dist/tui/terminal.js

@@ -5,6 +5,7 @@ function emptyKey() {
         return: false,
         escape: false,
         ctrl: false,
+        meta: false,
         tab: false,
         backspace: false,
     };
@@ -24,6 +25,13 @@ export function parseKeypress(data) {
         key.return = true;
         return { input: '', key };
     }
+    // Alt+Backspace: terminals send ESC followed by DEL/BS. Must precede the
+    // bare-ESC check so the two-byte sequence isn't swallowed as plain escape.
+    if (str === '\x1b\x7f' || str === '\x1b\b') {
+        key.meta = true;
+        key.backspace = true;
+        return { input: '', key };
+    }
     if (str === '\x1b') {
         key.escape = true;
         return { input: '', key };

package/dist/types.d.ts

@@ -156,4 +156,10 @@ export interface MountedPanel {
         progressPath?: string;
     }): void;
     canAcceptHostKeys(): boolean;
+    /**
+     * True when the deck is at its top level: overview phase with no active
+     * comment/freetext input. A host that owns mount/unmount uses this to decide
+     * whether Esc should step back inside the deck (false) or tear it down (true).
+     */
+    atDeckTop(): boolean;
 }

package/package.json

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