@crouton-kit/humanloop 0.1.4 → 0.2.1

package/dist/tui/app.js

@@ -1,105 +1,17 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } 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';
 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';
+/** 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. */
 export function validateInput(parsed) {
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error('Deck file must be a JSON object with an `interactions` array');
-    }
-    const obj = parsed;
-    if (!Array.isArray(obj.interactions)) {
-        throw new Error('`interactions` must be an array');
-    }
-    if (obj.interactions.length === 0) {
-        throw new Error('No interactions in deck 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.interactions.length; i++) {
-        const raw = obj.interactions[i];
-        const where = `interactions[${i}]`;
-        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-            throw new Error(`${where} must be an object`);
-        }
-        if (typeof raw.id !== 'string' || raw.id === '') {
-            throw new Error(`${where}.id must be a non-empty string`);
-        }
-        if (seen.has(raw.id)) {
-            throw new Error(`Duplicate interaction id: ${JSON.stringify(raw.id)}`);
-        }
-        seen.add(raw.id);
-        if (typeof raw.title !== 'string' || raw.title === '') {
-            throw new Error(`${where}.title must be a non-empty string`);
-        }
-        if (!Array.isArray(raw.options)) {
-            throw new Error(`${where}.options must be an array`);
-        }
-        const opts = [];
-        for (let j = 0; j < raw.options.length; j++) {
-            const o = raw.options[j];
-            const owhere = `${where}.options[${j}]`;
-            if (typeof o !== 'object' || o === null || Array.isArray(o)) {
-                throw new Error(`${owhere} must be an object`);
-            }
-            if (typeof o.id !== 'string' || o.id === '') {
-                throw new Error(`${owhere}.id must be a non-empty string`);
-            }
-            if (typeof o.label !== 'string') {
-                throw new Error(`${owhere}.label must be a string`);
-            }
-            const opt = { id: o.id, label: o.label };
-            if (o.description !== undefined) {
-                if (typeof o.description !== 'string')
-                    throw new Error(`${owhere}.description must be a string`);
-                opt.description = o.description;
-            }
-            if (o.shortcut !== undefined) {
-                if (typeof o.shortcut !== 'string')
-                    throw new Error(`${owhere}.shortcut must be a string`);
-                opt.shortcut = o.shortcut;
-            }
-            opts.push(opt);
-        }
-        const interaction = { id: raw.id, title: raw.title, options: opts };
-        if (raw.subtitle !== undefined) {
-            if (typeof raw.subtitle !== 'string')
-                throw new Error(`${where}.subtitle must be a string`);
-            interaction.subtitle = raw.subtitle;
-        }
-        if (raw.body !== undefined) {
-            if (typeof raw.body !== 'string')
-                throw new Error(`${where}.body must be a string`);
-            interaction.body = raw.body;
-        }
-        if (raw.bodyPath !== undefined) {
-            if (typeof raw.bodyPath !== 'string')
-                throw new Error(`${where}.bodyPath must be a string`);
-            interaction.bodyPath = raw.bodyPath;
-        }
-        if (raw.freetextLabel !== undefined) {
-            if (typeof raw.freetextLabel !== 'string')
-                throw new Error(`${where}.freetextLabel must be a string`);
-            interaction.freetextLabel = raw.freetextLabel;
-        }
-        if (raw.allowFreetext !== undefined) {
-            if (typeof raw.allowFreetext !== 'boolean')
-                throw new Error(`${where}.allowFreetext must be a boolean`);
-            interaction.allowFreetext = raw.allowFreetext;
-        }
-        if (raw.kind !== undefined) {
-            interaction.kind = raw.kind;
-        }
-        validated.push(interaction);
-    }
-    const deck = { interactions: validated };
-    if (obj.title !== undefined)
-        deck.title = obj.title;
-    return deck;
+    return validateDeck(parsed);
 }
 // ── Internal helpers ──────────────────────────────────────────────────────────
 function buildInitialState(deck) {
@@ -269,17 +181,18 @@ export function mountPanel(opts) {
         },
     };
 }
-// ── launchTui shim ────────────────────────────────────────────────────────────
-export async function launchTui(decisionsPath, sessionId) {
-    if (!existsSync(decisionsPath)) {
-        throw new Error(`Decisions file not found: ${decisionsPath}`);
-    }
-    const raw = readFileSync(decisionsPath, 'utf8');
-    const deck = validateInput(JSON.parse(raw));
+/**
+ * Resolve an interaction directory in place: mount the panel TUI keyed off
+ * `<dir>/progress.json`, and on finish (full completion OR human-finished
+ * 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.
+ */
+export async function resolveInteractionDir(dir, deck, opts = {}) {
     let conversationContext = '';
-    if (sessionId !== undefined) {
+    if (opts.sessionId !== undefined) {
         try {
-            const conv = readConversation(sessionId);
+            const conv = readConversation(opts.sessionId);
             conversationContext = conv.map((m) => `${m.role}: ${m.content}`).join('\n\n');
         }
         catch {
@@ -287,7 +200,13 @@ export async function launchTui(decisionsPath, sessionId) {
         }
     }
     setupTerminal();
-    const { cols, rows } = getTerminalSize();
+    const term = getTerminalSize();
+    const cols = opts.cols ?? term.cols;
+    const rows = opts.rows ?? term.rows;
+    const generateVisual = opts.generateVisual ??
+        (opts.sessionId !== undefined
+            ? (interaction) => defaultGenerateVisual(interaction, conversationContext)
+            : undefined);
     return new Promise((resolve) => {
         let panel = null;
         let prevFrameLocal = [];
@@ -302,28 +221,30 @@ export async function launchTui(decisionsPath, sessionId) {
             process.stdout.write('\x1b[?2026l');
             prevFrameLocal = nextPrevFrame;
         };
-        const onComplete = (responses) => {
+        const finalize = (responses) => {
             restoreTerminal();
             process.stdin.removeListener('data', onData);
             panel?.unmount();
-            resolve({ responses, completedAt: new Date().toISOString() });
+            const completedAt = new Date().toISOString();
+            // Resolved supersedes in-progress: write response.json, drop progress.json.
+            const rp = writeResponse(dir, responses, completedAt);
+            clearProgress(dir);
+            resolve({ responses, completedAt, responsePath: rp });
         };
         panel = mountPanel({
             deck,
-            progressPath: `${decisionsPath}.progress.json`,
+            progressPath: progressPathFor(dir),
             cols,
             rows,
-            generateVisual: sessionId !== undefined
-                ? (interaction) => defaultGenerateVisual(interaction, conversationContext)
-                : undefined,
+            generateVisual,
             onProgress: (responses) => {
                 lastResponses = responses;
                 if (panel !== null)
                     flushHost(panel.render());
             },
-            onComplete,
+            onComplete: finalize,
             onExit: () => {
-                onComplete(lastResponses);
+                finalize(lastResponses);
             },
         });
         flushHost(panel.render());
@@ -335,3 +256,17 @@ export async function launchTui(decisionsPath, sessionId) {
         process.stdin.on('data', onData);
     });
 }
+// ── launchTui — file-path entry over the dir resolver (a kept public export
+//    per the interaction-layer plan; consumed until consumers move to ask()) ──
+export async function launchTui(decisionsPath, sessionId) {
+    if (!existsSync(decisionsPath)) {
+        throw new Error(`Decisions file not found: ${decisionsPath}`);
+    }
+    const raw = readFileSync(decisionsPath, 'utf8');
+    const deck = validateInput(JSON.parse(raw));
+    // The interaction dir is the deck file's directory; progress/response live
+    // there per the convention.
+    const dir = dirname(resolvePath(decisionsPath));
+    const { responses, completedAt } = await resolveInteractionDir(dir, deck, { sessionId });
+    return { responses, completedAt };
+}

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}`);
         }
     }

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

@@ -32,6 +32,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 +84,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.2.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",