@crouton-kit/humanloop 0.1.4 → 0.3.1

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

@@ -1,45 +1,5 @@
-import { execFileSync } from 'node:child_process';
 import stringWidth from 'string-width';
-// ── Termrender body rendering ────────────────────────────────────────────────
-let _termrenderAvail = null;
-function isTermrenderAvailable() {
-    if (_termrenderAvail !== null)
-        return _termrenderAvail;
-    try {
-        execFileSync('termrender', ['--version'], { stdio: 'pipe', timeout: 3000 });
-        _termrenderAvail = true;
-    }
-    catch {
-        _termrenderAvail = false;
-    }
-    return _termrenderAvail;
-}
-const _bodyCache = new Map();
-function renderBody(text, width) {
-    const key = `${text}\0${width}`;
-    const cached = _bodyCache.get(key);
-    if (cached)
-        return cached;
-    if (isTermrenderAvailable()) {
-        try {
-            const out = execFileSync('termrender', ['--width', String(width)], {
-                input: text,
-                encoding: 'utf-8',
-                timeout: 5000,
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
-            const lines = out.split('\n');
-            if (lines.length > 0 && lines[lines.length - 1] === '')
-                lines.pop();
-            _bodyCache.set(key, lines);
-            return lines;
-        }
-        catch { /* fall through */ }
-    }
-    const fallback = wrap(sanitize(text), width);
-    _bodyCache.set(key, fallback);
-    return fallback;
-}
+import { renderMarkdown } from '../render/termrender.js';
 // ── ANSI helpers ─────────────────────────────────────────────────────────────
 const ESC = '\x1b[';
 const RESET = `${ESC}0m`;
@@ -282,7 +242,7 @@ export function renderItemReview(state, cols, rows) {
     const bodyLines = [];
     if (interaction.body) {
         bodyLines.push('');
-        for (const line of renderBody(interaction.body, maxW)) {
+        for (const line of renderMarkdown(interaction.body, maxW)) {
             bodyLines.push(`  ${line}`);
         }
     }
@@ -316,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) {
@@ -370,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('  ')}`;
@@ -396,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++) {
@@ -404,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) {
@@ -473,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/tui/tmux.d.ts

@@ -1,10 +1,8 @@
-import type { InteractionResponse } from '../types.js';
-export interface TuiOutput {
-    responses: InteractionResponse[];
-    completedAt: string;
-}
+import type { ResolutionEnvelope } from '../types.js';
 export interface TmuxDispatchOpts {
     sessionId?: string;
     visuals: boolean;
+    /** Interaction dir forwarded to the child so response.json lands there. */
+    dir: string;
 }
-export declare function dispatchToTmuxPane(file: string, opts: TmuxDispatchOpts): Promise<TuiOutput>;
+export declare function dispatchToTmuxPane(file: string, opts: TmuxDispatchOpts): Promise<ResolutionEnvelope>;

package/dist/tui/tmux.js

@@ -15,8 +15,10 @@ function buildChildCmd(file, resultPath, opts) {
     const parts = [
         shellQuote(process.execPath),
         shellQuote(scriptPath),
-        'create',
+        'ask',
         shellQuote(file),
+        '--dir',
+        shellQuote(opts.dir),
         '--write-to',
         shellQuote(resultPath),
     ];
@@ -29,8 +31,8 @@ function buildChildCmd(file, resultPath, opts) {
     return parts.join(' ');
 }
 export async function dispatchToTmuxPane(file, opts) {
-    const dir = mkdtempSync(join(tmpdir(), 'hl-'));
-    const resultPath = join(dir, 'result.json');
+    const parentTmp = mkdtempSync(join(tmpdir(), 'hl-'));
+    const resultPath = join(parentTmp, 'result.json');
     const cmd = buildChildCmd(file, resultPath, opts);
     // Capture the spawned pane id so we can detect if the user closes it
     // without finishing — otherwise the parent would poll forever.
@@ -65,7 +67,7 @@ export async function dispatchToTmuxPane(file, opts) {
     }
     catch { /* ignore */ }
     try {
-        rmdirSync(dir);
+        rmdirSync(parentTmp);
     }
     catch { /* ignore */ }
     return JSON.parse(json);

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 {
@@ -32,6 +38,32 @@ export interface Deck {
     source?: DeckSource;
     interactions: Interaction[];
 }
+export interface FeedbackComment {
+    id: string;
+    /** 1-based source line where the comment is anchored (start). */
+    line: number;
+    /** 1-based source line where the anchored range ends (== line for one line). */
+    endLine: number;
+    /** Exact selected substring when the human made a visual selection. */
+    quote?: string;
+    /** 0-based byte column where a partial (charwise) selection starts on `line`. */
+    colStart?: number;
+    /** 0-based exclusive byte column where the selection ends on `endLine`. */
+    colEnd?: number;
+    /** Full source text of the anchored line(s) — context for the agent. */
+    lineText: string;
+    comment: string;
+    createdAt: string;
+}
+export interface FeedbackResult {
+    file: string;
+    submitted: boolean;
+    /** True when submitted with zero comments — human signalled "looks good". */
+    approved: boolean;
+    comments: FeedbackComment[];
+    submittedAt?: string;
+    savedAt: string;
+}
 export interface VisualBlock {
     questionId: string;
     content: string;
@@ -58,6 +90,45 @@ export interface TuiState {
     scrollOffset: number;
     persist?: () => void;
 }
+/**
+ * Resolution contract returned by `ask`/`inbox`. On-disk `response.json` stays
+ * `{ responses, completedAt }`; `responsePath` points at it. `hl schema
+ * response` returns the JSON Schema this `schema` id names.
+ */
+export interface ResolutionEnvelope {
+    /** 1 line/interaction "<title>: <option label>[ — <freetext>]"; deterministic, no LLM. */
+    summary: string;
+    /** Absolute path to response.json. */
+    responsePath: string;
+    schema: 'humanloop.response/v2';
+    /** Inline (small). */
+    responses: InteractionResponse[];
+    /** ISO timestamp. */
+    completedAt: string;
+}
+/**
+ * One pending interaction discovered by `scanInbox`. Read from the
+ * `deck.json` header only — never the full deck.
+ */
+export interface InboxItem {
+    dir: string;
+    id: string;
+    title?: string;
+    subtitle?: string;
+    kind?: InteractionKind;
+    /** `deck.source.blockedSince` ?? `statSync(deck.json).mtime` (ISO). */
+    blockedSince: string;
+    source?: DeckSource;
+}
+/** Options for `display()` — the live-watch tmux pane surface. */
+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. */
+    maxPanes?: number;
+}
 export type GenerateVisual = (interaction: Interaction) => Promise<{
     ok: true;
     ansi: string;

package/dist/visuals/generate.js

@@ -1,5 +1,5 @@
 import { query } from '@r-cli/sdk';
-import { execSync } from 'child_process';
+import { renderMarkdown } from '../render/termrender.js';
 const VISUAL_SYSTEM_PROMPT = `You're briefing a CTO-level engineer in the 30 seconds before they decide. They've been off this problem for days; they need a fast re-ground in what *already exists* — the files, data flow, or constraint they're deciding inside of — not a lecture on tradeoffs.
 
 # Length
@@ -68,31 +68,6 @@ async function callHaiku(prompt, systemPrompt) {
         return null;
     }
 }
-function renderWithTermrender(markdown, width) {
-    // First attempt
-    const result = tryTermrender(markdown, width);
-    if (result !== null)
-        return result;
-    // Fallback: strip all directives and render as plain markdown
-    const stripped = markdown.replace(/^:{3,}\w*.*$/gm, '').trim();
-    const fallback = tryTermrender(stripped, width);
-    return fallback ?? markdown;
-}
-function tryTermrender(markdown, width) {
-    try {
-        return execSync(`termrender -w ${width}`, {
-            input: markdown,
-            encoding: 'utf8',
-            timeout: 5000,
-            env: { ...process.env, TERMRENDER_COLOR: '1' },
-        }).trimEnd();
-    }
-    catch (err) {
-        const stderr = err.stderr || '';
-        process.stderr.write(`[hl] termrender: ${stderr.split('\n')[0]}\n`);
-        return null;
-    }
-}
 // defaultGenerateVisual matches the GenerateVisual contract for use with
 // mountPanel. Width is read from process.stdout.columns so callers that
 // embed humanloop in a sub-region should supply their own closure that bakes
@@ -113,7 +88,7 @@ export async function defaultGenerateVisual(interaction, conversationContext) {
             .replace(/^```[\w]*\n?/gm, '')
             .replace(/^```\s*$/gm, '')
             .trim();
-        const ansi = renderWithTermrender(markdown, width);
+        const ansi = renderMarkdown(markdown, width).join('\n');
         return { ok: true, ansi, markdown };
     }
     return { ok: false, error: 'haiku returned no output' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.1.4",
+  "version": "0.3.1",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",
@@ -25,12 +25,14 @@
     "build": "tsc",
     "dev": "tsx src/cli.ts",
     "link": "npm link",
+    "postinstall": "node dist/scripts/install-renderer.js || true",
     "test": "tsx src/__tests__/mount-panel.test.ts"
   },
   "dependencies": {
     "@r-cli/sdk": "^1.3.0",
     "commander": "^13.0.0",
-    "string-width": "^7.0.0"
+    "string-width": "^7.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",