@crouton-kit/humanloop 0.1.0 → 0.1.2

package/dist/cli.js

@@ -139,6 +139,9 @@ program
         else if (msg.includes('JSON')) {
             process.stderr.write('\nFix: the decisions file must be valid JSON matching `hl schema`.\n');
         }
+        else if (msg.startsWith('questions[') || msg.includes('Duplicate question id') || msg.includes('must be')) {
+            process.stderr.write('\nFix: the decisions file must match `hl schema`. Run `hl schema` to see the required shape.\n');
+        }
         process.exit(1);
     }
 });

package/dist/tui/app.d.ts

@@ -1,2 +1,3 @@
-import type { DecisionsOutput } from '../types.js';
+import type { DecisionsInput, DecisionsOutput } from '../types.js';
+export declare function validateInput(parsed: unknown): DecisionsInput;
 export declare function launchTui(decisionsPath: string, sessionId?: string): Promise<DecisionsOutput>;

package/dist/tui/app.js

@@ -4,15 +4,81 @@ import { flush, renderOverview, renderItemReview, renderFinal } from './render.j
 import { handleKeypress } from './input.js';
 import { readConversation } from '../conversation/reader.js';
 import { generateVisuals } from '../visuals/generate.js';
+// Validate the parsed JSON before opening the terminal so bad agent input
+// fails with a clear error instead of crashing inside the TUI.
+export function validateInput(parsed) {
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('Decisions file must be a JSON object with a `questions` array');
+    }
+    const obj = parsed;
+    if (!Array.isArray(obj.questions)) {
+        throw new Error('`questions` must be an array');
+    }
+    if (obj.questions.length === 0) {
+        throw new Error('No questions in decisions file');
+    }
+    if (obj.title !== undefined && typeof obj.title !== 'string') {
+        throw new Error('`title` must be a string when present');
+    }
+    const seen = new Set();
+    const validated = [];
+    for (let i = 0; i < obj.questions.length; i++) {
+        const q = obj.questions[i];
+        const where = `questions[${i}]`;
+        if (typeof q !== 'object' || q === null || Array.isArray(q)) {
+            throw new Error(`${where} must be an object`);
+        }
+        if (typeof q.id !== 'string' || q.id === '') {
+            throw new Error(`${where}.id must be a non-empty string`);
+        }
+        if (seen.has(q.id)) {
+            throw new Error(`Duplicate question id: ${JSON.stringify(q.id)}`);
+        }
+        seen.add(q.id);
+        if (q.type === 'validation') {
+            if (typeof q.statement !== 'string')
+                throw new Error(`${where}.statement must be a string`);
+            if (typeof q.rationale !== 'string')
+                throw new Error(`${where}.rationale must be a string`);
+            validated.push({ id: q.id, type: 'validation', statement: q.statement, rationale: q.rationale });
+        }
+        else if (q.type === 'choice') {
+            if (typeof q.question !== 'string')
+                throw new Error(`${where}.question must be a string`);
+            if (typeof q.rationale !== 'string')
+                throw new Error(`${where}.rationale must be a string`);
+            if (!Array.isArray(q.options))
+                throw new Error(`${where}.options must be an array`);
+            if (q.options.length < 2)
+                throw new Error(`${where}.options must have at least 2 items (got ${q.options.length})`);
+            const opts = [];
+            for (let j = 0; j < q.options.length; j++) {
+                if (typeof q.options[j] !== 'string')
+                    throw new Error(`${where}.options[${j}] must be a string`);
+                opts.push(q.options[j]);
+            }
+            validated.push({ id: q.id, type: 'choice', question: q.question, rationale: q.rationale, options: opts });
+        }
+        else if (q.type === 'freetext') {
+            if (typeof q.question !== 'string')
+                throw new Error(`${where}.question must be a string`);
+            if (typeof q.rationale !== 'string')
+                throw new Error(`${where}.rationale must be a string`);
+            validated.push({ id: q.id, type: 'freetext', question: q.question, rationale: q.rationale });
+        }
+        else {
+            throw new Error(`${where}.type must be "validation" | "choice" | "freetext" (got ${JSON.stringify(q.type)})`);
+        }
+    }
+    return { title: obj.title, questions: validated };
+}
 export async function launchTui(decisionsPath, sessionId) {
     if (!existsSync(decisionsPath)) {
         throw new Error(`Decisions file not found: ${decisionsPath}`);
     }
     const raw = readFileSync(decisionsPath, 'utf8');
-    const input = JSON.parse(raw);
-    if (!input.questions || input.questions.length === 0) {
-        throw new Error('No questions in decisions file');
-    }
+    const parsed = JSON.parse(raw);
+    const input = validateInput(parsed);
     const state = {
         phase: 'overview',
         currentIndex: 0,

package/dist/tui/input.js

@@ -181,12 +181,23 @@ function handleInputMode(input, key, state, render) {
         return;
     }
     if (key.backspace) {
-        mode.buffer = mode.buffer.slice(0, -1);
+        // Drop the last *codepoint*, not the last UTF-16 code unit, so backspace
+        // on an emoji removes the whole glyph instead of leaving a lone surrogate.
+        const chars = [...mode.buffer];
+        chars.pop();
+        mode.buffer = chars.join('');
         render();
         return;
     }
-    if (input.length === 1 && input.charCodeAt(0) >= 32) {
-        mode.buffer += input;
+    // Accept any printable input — including pasted multi-char chunks and
+    // multi-byte UTF-8 (emoji / CJK). Strip control bytes (ESC sequences,
+    // bracketed-paste markers, BEL, BS, CR) so they can't corrupt the TUI.
+    const cleaned = input
+        .replace(/\x1b\[20[01]~/g, '') // bracketed-paste start/end markers
+        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '') // CSI sequences
+        .replace(/[\x00-\x1F\x7F]/g, ''); // C0 controls and DEL
+    if (cleaned.length > 0) {
+        mode.buffer += cleaned;
         render();
     }
 }

package/dist/tui/render.d.ts

@@ -1,4 +1,5 @@
 import type { TuiState } from '../types.js';
+export declare function sanitize(text: string): string;
 export declare function flush(lines: string[]): void;
 export declare function renderOverview(state: TuiState): string[];
 export declare function renderItemReview(state: TuiState): string[];

package/dist/tui/render.js

@@ -14,18 +14,38 @@ const CYAN = `${ESC}36m`;
 const GRAY = `${ESC}90m`;
 const BG_BLUE = `${ESC}44m`;
 const WHITE = `${ESC}37m`;
+// Strip ANSI escape sequences and other C0/C1 control bytes from user-supplied
+// text so it can't poison the alt-screen buffer (cursor moves, color bleed,
+// embedded \x1b[2J that clears the screen, etc). Keeps \n and \t which the
+// wrappers handle explicitly.
+const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
+export function sanitize(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text.replace(CONTROL_CHARS_RE, '');
+}
+// For one-line displays (overview rows, summaries): collapse all whitespace
+// — including newlines and tabs — to single spaces so the row stays one line.
+function singleLine(text) {
+    return sanitize(text).replace(/\s+/g, ' ').trim();
+}
 function truncate(text, maxWidth) {
+    if (maxWidth < 1)
+        return '';
     if (stringWidth(text) <= maxWidth)
         return text;
+    // Iterate by codepoint, not UTF-16 code unit, so surrogate pairs don't split.
+    const chars = [...text];
     let w = 0;
-    let i = 0;
-    for (; i < text.length; i++) {
-        const cw = stringWidth(text[i]);
+    let out = '';
+    for (const ch of chars) {
+        const cw = stringWidth(ch);
         if (w + cw + 1 > maxWidth)
             break;
+        out += ch;
         w += cw;
     }
-    return text.slice(0, i) + '…';
+    return out + '…';
 }
 function padRight(text, width) {
     const w = stringWidth(text);
@@ -34,26 +54,67 @@ function padRight(text, width) {
     return text + ' '.repeat(width - w);
 }
 function hline(width, char = '─') {
+    if (width < 1)
+        return '';
     return char.repeat(width);
 }
+// Word-wrap that ALSO respects \n as a hard break and ALSO breaks oversized
+// words at maxWidth so a single 200-char token doesn't overflow the frame.
 function wrap(text, maxWidth) {
-    const words = text.split(/\s+/);
-    const lines = [];
-    let current = '';
-    for (const word of words) {
-        const candidate = current ? `${current} ${word}` : word;
-        if (stringWidth(candidate) <= maxWidth) {
-            current = candidate;
+    if (maxWidth < 1)
+        return [text];
+    const out = [];
+    const paragraphs = text.split('\n');
+    for (let p = 0; p < paragraphs.length; p++) {
+        const para = paragraphs[p];
+        if (para === '') {
+            out.push('');
+            continue;
         }
-        else {
-            if (current)
-                lines.push(current);
-            current = word;
+        const words = para.split(/[ \t]+/).filter(Boolean);
+        let current = '';
+        for (let word of words) {
+            // Hard-break a word that's wider than the line.
+            while (stringWidth(word) > maxWidth) {
+                if (current) {
+                    out.push(current);
+                    current = '';
+                }
+                const piece = sliceByWidth(word, maxWidth);
+                out.push(piece);
+                word = word.slice(piece.length);
+            }
+            const candidate = current ? `${current} ${word}` : word;
+            if (stringWidth(candidate) <= maxWidth) {
+                current = candidate;
+            }
+            else {
+                if (current)
+                    out.push(current);
+                current = word;
+            }
         }
+        if (current)
+            out.push(current);
     }
-    if (current)
-        lines.push(current);
-    return lines.length > 0 ? lines : [''];
+    return out.length > 0 ? out : [''];
+}
+// Take the longest prefix of `s` whose visible width is <= maxWidth.
+function sliceByWidth(s, maxWidth) {
+    let w = 0;
+    let out = '';
+    for (const ch of s) {
+        const cw = stringWidth(ch);
+        if (w + cw > maxWidth)
+            break;
+        out += ch;
+        w += cw;
+    }
+    // Always advance at least one character so we don't loop forever on
+    // a single zero-width or oversized glyph.
+    if (out === '' && s.length > 0)
+        out = [...s][0];
+    return out;
 }
 function hardWrap(text, maxWidth) {
     if (maxWidth < 1)
@@ -67,7 +128,8 @@ function hardWrap(text, maxWidth) {
         }
         let current = '';
         let currentW = 0;
-        for (const ch of seg) {
+        // Iterate by codepoint so emoji surrogate pairs stay intact.
+        for (const ch of [...seg]) {
             const cw = stringWidth(ch);
             if (currentW + cw > maxWidth) {
                 out.push(current);
@@ -107,25 +169,62 @@ export function renderOverview(state) {
     lines.push(`  ${title}  ${DIM}${progress}${RESET}`);
     lines.push(`  ${DIM}${hline(Math.min(cols - 4, 60))}${RESET}`);
     lines.push('');
+    const rowsBuf = [];
     for (let i = 0; i < state.questions.length; i++) {
         const q = state.questions[i];
         const answer = state.answers.get(q.id);
         const icon = answer ? `${GREEN}✓${RESET}` : `${DIM}○${RESET}`;
-        const label = q.type === 'validation' ? q.statement : q.question;
+        const label = singleLine(q.type === 'validation' ? q.statement : q.question);
         const typeTag = `${DIM}[${q.type}]${RESET}`;
         const cursor = i === state.currentIndex ? `${CYAN}▸${RESET} ` : '  ';
-        lines.push(`  ${cursor}${icon} ${truncate(label, cols - 20)} ${typeTag}`);
+        const labelMax = Math.max(10, cols - 20);
+        rowsBuf.push({
+            line: `  ${cursor}${icon} ${truncate(label, labelMax)} ${typeTag}`,
+            questionIndex: i,
+        });
         if (answer) {
-            const summary = answerSummary(answer);
-            lines.push(`      ${DIM}${truncate(summary, cols - 10)}${RESET}`);
+            const summary = singleLine(answerSummary(answer));
+            const summaryMax = Math.max(10, cols - 10);
+            rowsBuf.push({
+                line: `      ${DIM}${truncate(summary, summaryMax)}${RESET}`,
+                questionIndex: i,
+            });
         }
     }
-    lines.push('');
+    // Reserve space for header (4 already pushed) + footer (3) + scroll hints (2).
+    const reserved = 4 + 3 + 2;
+    const available = Math.max(1, rows - reserved);
+    let scroll = state.scrollOffset || 0;
+    // Find first row matching currentIndex; ensure it's in [scroll, scroll+available).
+    const focusRow = rowsBuf.findIndex((r) => r.questionIndex === state.currentIndex);
+    if (focusRow >= 0) {
+        if (focusRow < scroll)
+            scroll = focusRow;
+        if (focusRow >= scroll + available)
+            scroll = focusRow - available + 1;
+    }
+    scroll = Math.max(0, Math.min(scroll, Math.max(0, rowsBuf.length - available)));
+    state.scrollOffset = scroll;
+    if (scroll > 0) {
+        lines.push(`  ${DIM}↑ ${scroll} more above${RESET}`);
+    }
+    else {
+        lines.push('');
+    }
+    const end = Math.min(rowsBuf.length, scroll + available);
+    for (let i = scroll; i < end; i++)
+        lines.push(rowsBuf[i].line);
+    if (end < rowsBuf.length) {
+        lines.push(`  ${DIM}↓ ${rowsBuf.length - end} more below${RESET}`);
+    }
+    else {
+        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`);
     while (lines.length < rows)
         lines.push('');
-    return lines;
+    return lines.slice(0, rows);
 }
 export function renderItemReview(state) {
     const { cols, rows } = getTerminalSize();
@@ -141,11 +240,11 @@ export function renderItemReview(state) {
     lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
     lines.push('');
     // Question / Statement
-    const headline = q.type === 'validation' ? q.statement : q.question;
+    const headline = sanitize(q.type === 'validation' ? q.statement : q.question);
     for (const line of wrap(headline, maxW)) {
         lines.push(`  ${BOLD}${line}${RESET}`);
     }
-    for (const line of wrap(q.rationale, maxW)) {
+    for (const line of wrap(sanitize(q.rationale), maxW)) {
         lines.push(`  ${ITALIC}${GRAY}${line}${RESET}`);
     }
     lines.push('');
@@ -197,6 +296,12 @@ export function renderItemReview(state) {
         `${DIM}q${RESET} overview`,
     ];
     lines.push(`  ${footerParts.join('  ')}`);
+    // If the headline + visual + actions overflowed the viewport, the footer
+    // would otherwise scroll off the bottom. Clip to `rows` so flush() never
+    // writes more rows than the terminal has.
+    if (lines.length > rows) {
+        return [...lines.slice(0, rows - 1), lines[lines.length - 1]];
+    }
     return lines;
 }
 function renderActions(q, selectedAction, existing) {
@@ -218,12 +323,15 @@ function renderActions(q, selectedAction, existing) {
     else if (q.type === 'choice') {
         for (let i = 0; i < q.options.length; i++) {
             const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-            const keyBadge = `${DIM}[${i + 1}]${RESET}`;
-            lines.push(`  ${cursor} ${keyBadge} ${q.options[i]}`);
+            // Numeric shortcut only for 1..9 — past that, the digit '1' would fire
+            // before the user can type the second digit, so we use a blank pad.
+            const keyBadge = i < 9 ? `${DIM}[${i + 1}]${RESET}` : `${DIM}   ${RESET}`;
+            lines.push(`  ${cursor} ${keyBadge} ${sanitize(q.options[i])}`);
         }
         const otherIdx = q.options.length;
         const cursor = otherIdx === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-        lines.push(`  ${cursor} ${DIM}[${otherIdx + 1}]${RESET} ${ITALIC}Other (custom)${RESET}`);
+        const otherBadge = otherIdx < 9 ? `${DIM}[${otherIdx + 1}]${RESET}` : `${DIM}   ${RESET}`;
+        lines.push(`  ${cursor} ${otherBadge} ${ITALIC}Other (custom)${RESET}`);
     }
     else {
         lines.push(`  ${DIM}[r]${RESET} Enter response`);
@@ -236,44 +344,58 @@ function renderActions(q, selectedAction, existing) {
 }
 export function renderFinal(state) {
     const { cols, rows } = getTerminalSize();
-    const lines = [];
+    const header = [];
+    const footer = [];
     const maxW = Math.min(cols - 4, 60);
     const total = state.questions.length;
     const answered = state.answers.size;
-    lines.push('');
-    lines.push(`  ${BOLD}${CYAN} Summary ${RESET}`);
-    lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
-    lines.push('');
-    lines.push(`  ${answered}/${total} questions answered`);
-    lines.push('');
+    header.push('');
+    header.push(`  ${BOLD}${CYAN} Summary ${RESET}`);
+    header.push(`  ${DIM}${hline(maxW)}${RESET}`);
+    header.push('');
+    header.push(`  ${answered}/${total} questions answered`);
+    header.push('');
+    footer.push('');
+    footer.push(`  ${DIM}${hline(maxW)}${RESET}`);
+    if (answered < total) {
+        footer.push(`  ${YELLOW}${total - answered} unanswered — press p to go back${RESET}`);
+    }
+    footer.push(`  ${DIM}enter${RESET} submit  ${DIM}p${RESET} go back`);
+    // Build per-question rows so we can clip to fit the viewport while
+    // keeping the header + footer always visible (the keybind hint at the
+    // bottom is essential — without it the user can't submit).
+    const questionRows = [];
     for (const q of state.questions) {
         const answer = state.answers.get(q.id);
         const icon = answer ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
-        const label = q.type === 'validation' ? q.statement : q.question;
-        lines.push(`  ${icon} ${truncate(label, maxW - 4)}`);
+        const label = singleLine(q.type === 'validation' ? q.statement : q.question);
+        questionRows.push(`  ${icon} ${truncate(label, Math.max(10, maxW - 4))}`);
         if (answer) {
-            lines.push(`    ${DIM}${truncate(answerSummary(answer), maxW - 6)}${RESET}`);
+            questionRows.push(`    ${DIM}${truncate(singleLine(answerSummary(answer)), Math.max(10, maxW - 6))}${RESET}`);
         }
     }
-    lines.push('');
-    lines.push(`  ${DIM}${hline(maxW)}${RESET}`);
-    if (answered < total) {
-        lines.push(`  ${YELLOW}${total - answered} unanswered — press p to go back${RESET}`);
+    const available = Math.max(1, rows - header.length - footer.length - 1);
+    let visible = questionRows;
+    if (questionRows.length > available) {
+        visible = [
+            ...questionRows.slice(0, available - 1),
+            `  ${DIM}… ${questionRows.length - (available - 1)} more rows omitted${RESET}`,
+        ];
     }
-    lines.push(`  ${DIM}enter${RESET} submit  ${DIM}p${RESET} go back`);
+    const lines = [...header, ...visible, ...footer];
     while (lines.length < rows)
         lines.push('');
-    return lines;
+    return lines.slice(0, rows);
 }
 function answerSummary(a) {
     switch (a.type) {
         case 'validation':
             return a.approved
-                ? (a.comment ? `approved: "${a.comment}"` : 'approved')
-                : (a.comment ? `commented: "${a.comment}"` : 'commented');
+                ? (a.comment ? `approved: "${sanitize(a.comment)}"` : 'approved')
+                : (a.comment ? `commented: "${sanitize(a.comment)}"` : 'commented');
         case 'choice':
-            return a.isCustom ? `custom: "${a.selected}"` : a.selected;
+            return a.isCustom ? `custom: "${sanitize(a.selected)}"` : sanitize(a.selected);
         case 'freetext':
-            return a.response;
+            return sanitize(a.response);
     }
 }

package/dist/tui/terminal.js

@@ -41,6 +41,11 @@ export function parseKeypress(data) {
         const ch = String.fromCharCode(str.charCodeAt(0) + 64).toLowerCase();
         return { input: ch, key };
     }
+    // Multi-byte chunks (paste, multi-byte UTF-8, unknown escape sequences)
+    // are returned as-is in `input`; the input-mode handler is responsible for
+    // sanitising them before appending to its buffer. Top-level handlers
+    // ignore strings of length > 1, which is the desired behaviour for
+    // accidentally pasted text in overview/item-review.
     return { input: str, key };
 }
 export function setupTerminal() {

package/dist/tui/tmux.js

@@ -32,12 +32,30 @@ export async function dispatchToTmuxPane(file, opts) {
     const dir = mkdtempSync(join(tmpdir(), 'hl-'));
     const resultPath = join(dir, 'result.json');
     const cmd = buildChildCmd(file, resultPath, opts);
-    execFileSync('tmux', ['split-window', '-h', '-d', cmd], { stdio: 'ignore' });
-    await new Promise((resolve) => {
+    // Capture the spawned pane id so we can detect if the user closes it
+    // without finishing — otherwise the parent would poll forever.
+    const paneId = execFileSync('tmux', ['split-window', '-P', '-F', '#{pane_id}', '-h', '-d', cmd], { encoding: 'utf8' }).trim();
+    await new Promise((resolve, reject) => {
         const poll = setInterval(() => {
             if (existsSync(resultPath)) {
                 clearInterval(poll);
                 resolve();
+                return;
+            }
+            // Check the pane is still alive. If it's gone and there's still no
+            // result file, the child died (closed pane, crash, etc).
+            try {
+                const panes = execFileSync('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], {
+                    encoding: 'utf8',
+                });
+                if (!panes.split('\n').map((s) => s.trim()).includes(paneId)) {
+                    clearInterval(poll);
+                    reject(new Error(`tmux pane ${paneId} closed before writing a result`));
+                }
+            }
+            catch (err) {
+                clearInterval(poll);
+                reject(new Error(`tmux list-panes failed: ${err instanceof Error ? err.message : String(err)}`));
             }
         }, 150);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "bin": {