@crouton-kit/humanloop 0.2.1 → 0.3.2

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

@@ -25,6 +25,7 @@ export declare const deckSchema: z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
             shortcut: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        multiSelect: z.ZodOptional<z.ZodBoolean>;
         allowFreetext: z.ZodOptional<z.ZodBoolean>;
         freetextLabel: z.ZodOptional<z.ZodString>;
         kind: z.ZodOptional<z.ZodEnum<{

package/dist/inbox/deck-schema.js

@@ -17,6 +17,7 @@ const interactionSchema = z.object({
     body: z.string().optional(),
     bodyPath: z.string().optional(),
     options: z.array(interactionOptionSchema),
+    multiSelect: z.boolean().optional(),
     allowFreetext: z.boolean().optional(),
     freetextLabel: z.string().optional(),
     kind: z.enum(['notify', 'validation', 'decision', 'context', 'error']).optional(),

package/dist/render/termrender.d.ts

@@ -13,7 +13,7 @@ export declare function ensureRenderer(): void;
 export declare function isRendererReady(): boolean;
 /** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
 export declare function renderMarkdown(md: string, width: number): string[];
-/** Validate markdown via `termrender --check` (exit 0 ok / non-zero error). */
+/** Validate markdown via `termrender doc check`. */
 export declare function checkMarkdown(md: string): {
     ok: true;
 } | {
@@ -21,7 +21,7 @@ export declare function checkMarkdown(md: string): {
     error: string;
 };
 export interface DisplayInPaneOpts {
-    /** Pass `--watch` so the pane live-updates on file edits. Default true. */
+    /** 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

@@ -32,18 +32,34 @@ function binaryOk() {
     if (!existsSync(VENV_BIN))
         return false;
     try {
-        const out = execFileSync(VENV_BIN, ['--version'], {
+        // v2 contract: no --version flag; use -h (exit 0) as a liveness check.
+        execFileSync(VENV_BIN, ['-h'], {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
             timeout: 5000,
         });
-        const m = out.match(/\d+\.\d+\.\d+/);
-        return m?.[0] === TERMRENDER_VERSION;
+        return true;
     }
     catch {
         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,9 +110,9 @@ 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 version check failed; using plaintext fallback\n');
+        process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
     }
 }
 /** Cheap predicate — true when the pinned managed binary is present and correct. Does not install. */
@@ -172,12 +193,12 @@ export function renderMarkdown(md, width) {
     ensureRenderer();
     if (rendererState === 'ready') {
         try {
-            const out = execFileSync(VENV_BIN, ['--width', String(width)], {
-                input: md,
+            const input = JSON.stringify({ source: md, width, color: true });
+            const out = execFileSync(VENV_BIN, ['doc', 'render'], {
+                input,
                 encoding: 'utf-8',
                 timeout: 5000,
                 stdio: ['pipe', 'pipe', 'pipe'],
-                env: { ...process.env, TERMRENDER_COLOR: '1' },
             });
             const lines = out.split('\n');
             if (lines.length > 0 && lines[lines.length - 1] === '')
@@ -193,23 +214,42 @@ export function renderMarkdown(md, width) {
     _bodyCache.set(key, fallback);
     return fallback;
 }
-/** Validate markdown via `termrender --check` (exit 0 ok / non-zero error). */
+/** Validate markdown via `termrender doc check`. */
 export function checkMarkdown(md) {
     ensureRenderer();
     // Renderer unavailable → don't block validation; the body just renders as
     // plaintext later. Bricking deck validation here would be the wrong default.
     if (rendererState !== 'ready')
         return { ok: true };
-    const result = spawnSync(VENV_BIN, ['--check'], {
-        input: md,
+    const input = JSON.stringify({ source: md });
+    const result = spawnSync(VENV_BIN, ['doc', 'check'], {
+        input,
         encoding: 'utf-8',
         timeout: 5000,
     });
     if (result.error) {
-        return { ok: false, error: `termrender invocation failed: ${result.error.message}` };
+        return { ok: false, error: `termrender: invocation failed: ${result.error.message}` };
+    }
+    let parsed = null;
+    const rawStdout = typeof result.stdout === 'string' ? result.stdout : '';
+    if (rawStdout) {
+        try {
+            parsed = JSON.parse(rawStdout.trim());
+        }
+        catch {
+            // stdout not parseable — fall through to exit-code handling
+        }
     }
+    if (parsed !== null) {
+        if (parsed.ok)
+            return { ok: true };
+        const first = Array.isArray(parsed.errors) ? parsed.errors[0] : undefined;
+        const msg = (first && typeof first.message === 'string' && first.message) ? first.message : 'invalid markdown';
+        return { ok: false, error: `termrender: ${msg}` };
+    }
+    // exit code 2 = invalid per contract; any non-zero is an error
     if (result.status !== 0) {
-        return { ok: false, error: `termrender --check exited ${result.status}: ${(result.stderr || '').toString().trim()}` };
+        return { ok: false, error: `termrender: doc check exited ${result.status}` };
     }
     return { ok: true };
 }
@@ -222,15 +262,31 @@ export function displayInPane(path, opts = {}) {
     ensureRenderer();
     if (rendererState !== 'ready')
         return {};
-    const args = ['--tmux'];
-    if (opts.watch !== false)
-        args.push('--watch');
-    if (opts.newWindow)
-        args.push('--tmux-new-window');
-    args.push(path);
-    const result = spawnSync(VENV_BIN, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const input = JSON.stringify({
+        path,
+        watch: opts.watch !== false,
+        window: opts.newWindow ? 'new' : 'split',
+    });
+    const result = spawnSync(VENV_BIN, ['pane', 'open'], {
+        input,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
     if (result.error || result.status !== 0)
         return {};
-    const paneId = (result.stdout?.toString() || '').trim();
-    return paneId ? { paneId } : {};
+    // `encoding: 'utf-8'` makes spawnSync return stdout as a string.
+    const rawStdout = result.stdout;
+    if (!rawStdout)
+        return {};
+    let parsed = null;
+    try {
+        parsed = JSON.parse(rawStdout.trim());
+    }
+    catch {
+        return {};
+    }
+    if (parsed && typeof parsed.pane_id === 'string' && parsed.pane_id) {
+        return { paneId: parsed.pane_id };
+    }
+    return {};
 }

package/dist/render/version.d.ts

@@ -1 +1 @@
-export declare const TERMRENDER_VERSION = "1.0.0";
+export declare const TERMRENDER_VERSION = "2.1.0";

package/dist/render/version.js

@@ -1 +1 @@
-export const TERMRENDER_VERSION = '1.0.0';
+export const TERMRENDER_VERSION = '2.1.0';

package/dist/tui/input.js

@@ -92,7 +92,12 @@ function handleOverview(input, key, state, render, exit) {
     if (interaction !== undefined) {
         const matched = interaction.options.find((o) => o.shortcut === input);
         if (matched !== undefined) {
-            submitOption(state, interaction, matched.id, undefined);
+            if (interaction.multiSelect) {
+                toggleMulti(state, interaction, matched.id);
+            }
+            else {
+                submitOption(state, interaction, matched.id, undefined);
+            }
             // Don't auto-advance the cursor — users may want to re-answer the same
             // question. The response icon flips ✓ and they can j/k away when ready.
             render();
@@ -117,6 +122,13 @@ function handleItemReview(input, key, state, render) {
         render();
         return;
     }
+    // Space toggles the focused option for multi-select; otherwise expand context.
+    if (input === ' ' && interaction.multiSelect
+        && state.selectedAction < interaction.options.length) {
+        toggleMulti(state, interaction, interaction.options[state.selectedAction].id);
+        render();
+        return;
+    }
     if (input === ' ') {
         state.detailExpanded = !state.detailExpanded;
         render();
@@ -151,18 +163,23 @@ function handleItemReview(input, key, state, render) {
 }
 function handleInteractionAction(input, key, state, interaction, render) {
     const opts = interaction.options;
-    // Match by shortcut
+    // Match by shortcut. Multi-select toggles (stay put); single-select submits.
     const matched = opts.find((o) => o.shortcut === input);
     if (matched !== undefined) {
+        if (interaction.multiSelect) {
+            toggleMulti(state, interaction, matched.id);
+            render();
+            return;
+        }
         submitOption(state, interaction, matched.id, undefined);
         advanceItem(state, 1);
         render();
         return;
     }
-    // Comment mode: allowFreetext + options exist
-    // If the cursor is on an option row, pre-attach that option to the comment.
+    // Comment mode: allowFreetext + options exist. Multi-select carries its
+    // checked set on submit, so don't pre-attach a single option.
     if (input === 'c' && interaction.allowFreetext && opts.length > 0) {
-        const preselected = state.selectedAction < opts.length
+        const preselected = !interaction.multiSelect && state.selectedAction < opts.length
             ? opts[state.selectedAction].id
             : undefined;
         state.inputMode = preselected !== undefined
@@ -181,8 +198,15 @@ function handleInteractionAction(input, key, state, interaction, render) {
             return;
         }
     }
-    // Enter on selected option row
+    // Enter on selected option row. Multi-select confirms the accumulated set
+    // and advances; single-select picks that one option.
     if (key.return && state.selectedAction < opts.length) {
+        if (interaction.multiSelect) {
+            commitMulti(state, interaction);
+            advanceItem(state, 1);
+            render();
+            return;
+        }
         const o = opts[state.selectedAction];
         submitOption(state, interaction, o.id, undefined);
         advanceItem(state, 1);
@@ -225,8 +249,13 @@ function handleInputMode(input, key, state, render) {
     }
     if (key.return) {
         const interaction = state.interactions[state.currentIndex];
-        const attached = mode.kind === 'comment' ? mode.selectedOptionId : undefined;
-        submitOption(state, interaction, attached, mode.buffer);
+        if (interaction.multiSelect) {
+            commitMulti(state, interaction, mode.buffer);
+        }
+        else {
+            const attached = mode.kind === 'comment' ? mode.selectedOptionId : undefined;
+            submitOption(state, interaction, attached, mode.buffer);
+        }
         state.inputMode = null;
         advanceItem(state, 1);
         render();
@@ -285,3 +314,33 @@ function submitOption(state, interaction, selectedOptionId, freetext) {
     state.responses.set(interaction.id, response);
     state.persist?.();
 }
+// ── Multi-select ─────────────────────────────────────────────────────────────
+// Toggle/commit write progressively into state.responses (mirrors single-select
+// submitOption immediacy); Enter just confirms the accumulated set + advances.
+function toggleMulti(state, interaction, optionId) {
+    const existing = state.responses.get(interaction.id);
+    const set = new Set(existing?.selectedOptionIds ?? []);
+    if (set.has(optionId))
+        set.delete(optionId);
+    else
+        set.add(optionId);
+    const response = { id: interaction.id, selectedOptionIds: [...set] };
+    if (existing?.freetext !== undefined)
+        response.freetext = existing.freetext;
+    state.responses.set(interaction.id, response);
+    state.persist?.();
+}
+/** Ensure a (possibly empty) response exists so the interaction counts as
+ *  answered, optionally setting/replacing freetext. */
+function commitMulti(state, interaction, freetext) {
+    const existing = state.responses.get(interaction.id);
+    const response = {
+        id: interaction.id,
+        selectedOptionIds: [...(existing?.selectedOptionIds ?? [])],
+    };
+    const ft = freetext ?? existing?.freetext;
+    if (ft !== undefined)
+        response.freetext = ft;
+    state.responses.set(interaction.id, response);
+    state.persist?.();
+}

package/dist/tui/render.js

@@ -276,9 +276,10 @@ export function renderItemReview(state, cols, rows) {
         const label = interaction.freetextLabel !== undefined
             ? interaction.freetextLabel
             : state.inputMode.kind === 'comment' ? 'Comment' : 'Response';
-        // Show attached option (comment mode only) — Tab cycles
+        // Show attached option (single-select comment mode only) — Tab cycles.
+        // Multi-select comments carry the checked set, so no attach line.
         let attachedLine;
-        if (state.inputMode.kind === 'comment') {
+        if (state.inputMode.kind === 'comment' && !interaction.multiSelect) {
             const attachedId = state.inputMode.selectedOptionId;
             const opts = interaction.options;
             if (opts.length > 0) {
@@ -330,11 +331,18 @@ export function renderItemReview(state, cols, rows) {
         visibleBody = bodyLines;
     }
     // Footer hint — mention scroll keys when body overflows
-    const footerParts = [
-        `${DIM}n/p${RESET} prev/next`,
-        `${DIM}space${RESET} expand`,
-        `${DIM}q${RESET} overview`,
-    ];
+    const footerParts = interaction.multiSelect === true
+        ? [
+            `${DIM}n/p${RESET} prev/next`,
+            `${DIM}space${RESET} toggle`,
+            `${DIM}enter${RESET} confirm`,
+            `${DIM}q${RESET} overview`,
+        ]
+        : [
+            `${DIM}n/p${RESET} prev/next`,
+            `${DIM}space${RESET} expand`,
+            `${DIM}q${RESET} overview`,
+        ];
     if (overflows)
         footerParts.unshift(`${DIM}u/d${RESET} scroll`);
     const footer = `  ${footerParts.join('  ')}`;
@@ -356,7 +364,9 @@ function renderActions(interaction, selectedAction, maxW, existing) {
     const opts = interaction.options;
     // Prefix on first row: "  X [s] " — 2 + 1 (cursor) + 1 + 3 ([s]) + 1 = 8 visible cols.
     // Continuation rows align under the label so each option reads as a block.
-    const prefixWidth = 8;
+    const multi = interaction.multiSelect === true;
+    const checked = new Set(existing?.selectedOptionIds ?? []);
+    const prefixWidth = multi ? 12 : 8;
     const indent = ' '.repeat(prefixWidth);
     const contentMax = Math.max(20, maxW - prefixWidth);
     for (let i = 0; i < opts.length; i++) {
@@ -364,9 +374,12 @@ function renderActions(interaction, selectedAction, maxW, existing) {
         const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
         const sc = o.shortcut ?? ' ';
         const keyBadge = `${DIM}[${sc}]${RESET}`;
+        const box = multi
+            ? (checked.has(o.id) ? `${GREEN}[x]${RESET}` : `${DIM}[ ]${RESET}`) + ' '
+            : '';
         const labelLines = wrap(sanitize(o.label), contentMax);
         for (let j = 0; j < labelLines.length; j++) {
-            const prefix = j === 0 ? `  ${cursor} ${keyBadge} ` : indent;
+            const prefix = j === 0 ? `  ${cursor} ${box}${keyBadge} ` : indent;
             lines.push(`${prefix}${labelLines[j]}`);
         }
         if (o.description) {
@@ -433,6 +446,16 @@ export function renderFinal(state, cols, rows) {
     return centerHorizontal(lines.slice(0, rows), cols, maxW + 2);
 }
 export function responseSummary(r, interaction) {
+    if (r.selectedOptionIds !== undefined) {
+        const labels = r.selectedOptionIds
+            .map((id) => interaction.options.find((o) => o.id === id))
+            .filter((o) => o !== undefined)
+            .map((o) => sanitize(o.label));
+        const picks = labels.length > 0 ? labels.join(', ') : '(none)';
+        if (r.freetext)
+            return `${picks}: "${sanitize(r.freetext)}"`;
+        return picks;
+    }
     const opt = r.selectedOptionId
         ? interaction.options.find((o) => o.id === r.selectedOptionId)
         : undefined;

package/dist/types.d.ts

@@ -13,13 +13,19 @@ export interface Interaction {
     body?: string;
     bodyPath?: string;
     options: InteractionOption[];
+    /** When true the human can check multiple options; the response carries
+     *  `selectedOptionIds`. Absent/false = single-select (unchanged). */
+    multiSelect?: boolean;
     allowFreetext?: boolean;
     freetextLabel?: string;
     kind?: InteractionKind;
 }
 export interface InteractionResponse {
     id: string;
+    /** Single-select pick. */
     selectedOptionId?: string;
+    /** Multi-select picks (set only for `multiSelect` interactions). */
+    selectedOptionIds?: string[];
     freetext?: string;
 }
 export interface DeckSource {

package/package.json

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