@crouton-kit/humanloop 0.1.4 → 0.2.1

package/dist/inbox/scan.d.ts

@@ -0,0 +1,2 @@
+import type { InboxItem } from '../types.js';
+export declare function scanInbox(roots: string[]): InboxItem[];

package/dist/inbox/scan.js

@@ -0,0 +1,62 @@
+import { readdirSync, statSync } from 'fs';
+import { resolve, basename } from 'path';
+import { deckPath, isResolved, isClaimed, readJson } from './convention.js';
+// ── scanInbox ─────────────────────────────────────────────────────────────────
+export function scanInbox(roots) {
+    const items = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            // root doesn't exist or isn't readable — skip silently
+            continue;
+        }
+        for (const entry of entries) {
+            const dir = resolve(root, entry);
+            try {
+                const stat = statSync(dir);
+                if (!stat.isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            // Skip resolved or actively claimed dirs
+            if (isResolved(dir) || isClaimed(dir))
+                continue;
+            const dp = deckPath(dir);
+            const deck = readJson(dp);
+            if (deck === null)
+                continue;
+            // Derive blockedSince: prefer deck.source.blockedSince, fall back to mtime
+            let blockedSince;
+            if (deck.source?.blockedSince !== undefined) {
+                blockedSince = deck.source.blockedSince;
+            }
+            else {
+                try {
+                    blockedSince = new Date(statSync(dp).mtime).toISOString();
+                }
+                catch {
+                    blockedSince = new Date().toISOString();
+                }
+            }
+            const firstInteraction = deck.interactions[0];
+            const item = {
+                dir,
+                id: firstInteraction?.id ?? basename(dir),
+                title: deck.title ?? firstInteraction?.title,
+                subtitle: firstInteraction?.subtitle,
+                kind: firstInteraction?.kind,
+                source: deck.source,
+                blockedSince,
+            };
+            items.push(item);
+        }
+    }
+    // Sort ascending by blockedSince (ISO string compare is monotonic)
+    items.sort((a, b) => (a.blockedSince < b.blockedSince ? -1 : a.blockedSince > b.blockedSince ? 1 : 0));
+    return items;
+}

package/dist/inbox/tui.d.ts

@@ -0,0 +1,9 @@
+import type { InboxItem } from '../types.js';
+export declare const KIND_ICON: Record<string, string>;
+export declare const KIND_COLOR: Record<string, string>;
+export declare function formatTimeAgo(iso: string): string;
+export declare function buildInboxLines(items: InboxItem[], width: number, selectedIndex: number): string[];
+export declare function pickFromInbox(items: InboxItem[], opts: {
+    cols: number;
+    rows: number;
+}): Promise<InboxItem | null>;

package/dist/inbox/tui.js

@@ -0,0 +1,158 @@
+import stringWidth from 'string-width';
+import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize, } from '../tui/terminal.js';
+import { diffFrame } from '../tui/render.js';
+// ── ANSI helpers (local to this module) ──────────────────────────────────────
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const BOLD = `${ESC}1m`;
+const DIM = `${ESC}2m`;
+const ITALIC = `${ESC}3m`;
+const CYAN = `${ESC}36m`;
+const RED = `${ESC}31m`;
+const GRAY = `${ESC}90m`;
+const YELLOW = `${ESC}33m`;
+function ansiColor(text, color) {
+    switch (color) {
+        case 'gray': return `${GRAY}${text}${RESET}`;
+        case 'cyan': return `${CYAN}${text}${RESET}`;
+        case 'red': return `${RED}${text}${RESET}`;
+        case 'yellow': return `${YELLOW}${text}${RESET}`;
+        default: return text;
+    }
+}
+// ── Row model (ported verbatim from sisyphus cross-session-inbox.ts:8-21) ────
+export const KIND_ICON = {
+    notify: '✉',
+    validation: '✓',
+    decision: '◆',
+    context: '✎',
+    error: '⚠',
+};
+export const KIND_COLOR = {
+    notify: 'gray',
+    validation: 'cyan',
+    decision: 'cyan',
+    context: 'cyan',
+    error: 'red',
+};
+// ── formatTimeAgo (ported from sisyphus src/tui/lib/format.ts:5-12) ──────────
+export function formatTimeAgo(iso) {
+    const diff = Date.now() - new Date(iso).getTime();
+    const minutes = Math.floor(diff / 60000);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0)
+        return `${hours}h ago`;
+    if (minutes > 0)
+        return `${minutes}m ago`;
+    return 'just now';
+}
+// ── truncate (ported from sisyphus src/tui/lib/format.ts:19-37) ──────────────
+function truncate(text, max) {
+    const clean = text.replace(/\n/g, ' ').replace(/✅/g, '✓').replace(/❌/g, '✗').replace(/\p{Emoji_Presentation}/gu, '');
+    if (max < 4)
+        return clean.slice(0, max);
+    const w = stringWidth(clean);
+    if (w <= max)
+        return clean;
+    let result = clean;
+    while (stringWidth(result) > max - 1 && result.length > 0) {
+        const cut = result.lastIndexOf(' ', result.length - 2);
+        if (cut > max * 0.4) {
+            result = result.slice(0, cut);
+        }
+        else {
+            result = result.slice(0, result.length - 1);
+        }
+    }
+    return result + '…';
+}
+// ── buildInboxLines ───────────────────────────────────────────────────────────
+export function buildInboxLines(items, width, selectedIndex) {
+    const lines = [];
+    if (items.length === 0) {
+        lines.push(`  ${DIM}${ITALIC}No pending interactions${RESET}`);
+        return lines;
+    }
+    lines.push(`  ${BOLD}${items.length} pending${RESET}`);
+    lines.push('');
+    const contentWidth = width - 4;
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const kindKey = item.kind ?? '';
+        const icon = kindKey in KIND_ICON ? KIND_ICON[kindKey] : '·';
+        const iconColor = kindKey in KIND_COLOR ? KIND_COLOR[kindKey] : 'cyan';
+        const sourceLabel = item.source?.sessionName ?? item.source?.askedBy ?? '';
+        const titleText = item.title ?? `(${item.id.slice(0, 8)})`;
+        const blocked = formatTimeAgo(item.blockedSince);
+        const cursor = i === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
+        const maxTitle = Math.max(10, contentWidth - sourceLabel.length - blocked.length - 8);
+        let row = cursor;
+        row += ansiColor(icon, iconColor);
+        if (sourceLabel) {
+            row += ` ${ansiColor(sourceLabel, 'yellow')}`;
+            row += ` ${DIM}·${RESET} `;
+        }
+        else {
+            row += ' ';
+        }
+        row += `${BOLD}${truncate(titleText, maxTitle)}${RESET}`;
+        row += `  ${DIM}${blocked}${RESET}`;
+        lines.push(row);
+        if (item.subtitle) {
+            lines.push(`      ${DIM}${truncate(item.subtitle, contentWidth - 6)}${RESET}`);
+        }
+    }
+    return lines;
+}
+// ── pickFromInbox ─────────────────────────────────────────────────────────────
+export function pickFromInbox(items, opts) {
+    if (items.length === 0)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let selectedIndex = 0;
+        let prevFrame = [];
+        let onData;
+        const flush = () => {
+            const { cols: currentCols, rows: currentRows } = getTerminalSize();
+            const lines = buildInboxLines(items, currentCols, selectedIndex);
+            const { writes, nextPrevFrame } = diffFrame(prevFrame, lines, currentRows);
+            process.stdout.write('\x1b[?2026h');
+            for (const w of writes)
+                process.stdout.write(w);
+            process.stdout.write('\x1b[?2026l');
+            prevFrame = nextPrevFrame;
+        };
+        const done = (result) => {
+            restoreTerminal();
+            process.stdin.removeListener('data', onData);
+            process.stdout.removeListener('resize', flush);
+            resolve(result);
+        };
+        setupTerminal();
+        flush();
+        onData = (data) => {
+            const { input, key } = parseKeypress(data);
+            if (key.downArrow || input === 'j') {
+                selectedIndex = Math.min(selectedIndex + 1, items.length - 1);
+                flush();
+                return;
+            }
+            if (key.upArrow || input === 'k') {
+                selectedIndex = Math.max(selectedIndex - 1, 0);
+                flush();
+                return;
+            }
+            if (key.return) {
+                const selected = items[selectedIndex];
+                done(selected ?? null);
+                return;
+            }
+            if (key.escape || (key.ctrl && input === 'c') || input === 'q') {
+                done(null);
+                return;
+            }
+        };
+        process.stdin.on('data', onData);
+        process.stdout.on('resize', flush);
+    });
+}

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 export { mountPanel, validateInput, launchTui } from './tui/app.js';
 export { defaultGenerateVisual } from './visuals/generate.js';
-export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, } from './types.js';
+export { launchReview } from './editor/review.js';
+export { launchReview as review } from './editor/review.js';
+export type { ReviewOptions } from './editor/review.js';
+export { ask, approve, notify, inbox } from './api.js';
+export { display } from './surfaces/display.js';
+export { scanInbox } from './inbox/scan.js';
+export { renderMarkdown, checkMarkdown, ensureRenderer, isRendererReady, } from './render/termrender.js';
+export { parseDeck, validateDeck, deckSchema } from './inbox/deck-schema.js';
+export { deckPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';
+export type { InteractionState } from './inbox/convention.js';
+export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, } from './types.js';
 export type { Key } from './tui/terminal.js';
 export type { ConversationMessage } from './conversation/reader.js';

package/dist/index.js

@@ -1,2 +1,15 @@
 export { mountPanel, validateInput, launchTui } from './tui/app.js';
 export { defaultGenerateVisual } from './visuals/generate.js';
+export { launchReview } from './editor/review.js';
+export { launchReview as review } from './editor/review.js';
+// Interaction-layer surface (SDK).
+export { ask, approve, notify, inbox } from './api.js';
+export { display } from './surfaces/display.js';
+export { scanInbox } from './inbox/scan.js';
+// Renderer binding — the sole org-wide termrender caller. Consumers
+// (sisyphus md-render / ask-schema) route markdown through these.
+export { renderMarkdown, checkMarkdown, ensureRenderer, isRendererReady, } from './render/termrender.js';
+// Canonical deck schema + parsing/validation (consumers stop forking it).
+export { parseDeck, validateDeck, deckSchema } from './inbox/deck-schema.js';
+// Interaction-directory convention helpers (§B) — names humanloop owns.
+export { deckPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';

package/dist/render/termrender.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Memoized, self-healing. Ensures the pinned termrender binary exists inside
+ * the humanloop-managed venv; (re)provisions it via `uv` when missing or the
+ * version drifts from the pin. Runs at most once per process. Single
+ * degradation path: `uv` absent → one stderr remediation line + plaintext
+ * fallback. win32 → plaintext (no renderer).
+ *
+ * Invoked at postinstall AND lazily on the first render/check/display call,
+ * so `npm ci --ignore-scripts` consumers still self-heal on first use.
+ */
+export declare function ensureRenderer(): void;
+/** Cheap predicate — true when the pinned managed binary is present and correct. Does not install. */
+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). */
+export declare function checkMarkdown(md: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DisplayInPaneOpts {
+    /** 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;
+}
+/**
+ * Spawn termrender into a live tmux pane. The pane-budget policy (whether to
+ * split vs open a new window) is decided by the caller (`src/surfaces/
+ * display.ts`); this is the thin managed-binary spawn it delegates to.
+ */
+export declare function displayInPane(path: string, opts?: DisplayInPaneOpts): {
+    paneId?: string;
+};

package/dist/render/termrender.js

@@ -0,0 +1,236 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import stringWidth from 'string-width';
+import { TERMRENDER_VERSION } from './version.js';
+// ── The sole org-wide termrender binding ─────────────────────────────────────
+//
+// termrender is a humanloop-managed dependency: a pure-Python tool pinned to
+// TERMRENDER_VERSION, installed into a venv humanloop owns. The binary is
+// resolved by ABSOLUTE PATH inside that venv — never `$PATH` — so a user's
+// own `pip install termrender` can never shadow or break the pin.
+function findPkgRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 12; i++) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // dist/render/termrender.js or src/render/termrender.ts → two up is pkgRoot.
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+const PKG_ROOT = findPkgRoot();
+const VENV_DIR = resolve(PKG_ROOT, '.venv');
+const VENV_BIN = resolve(PKG_ROOT, '.venv/bin/termrender');
+const VENV_PYTHON = resolve(PKG_ROOT, '.venv/bin/python');
+let rendererState = 'unchecked';
+function binaryOk() {
+    if (!existsSync(VENV_BIN))
+        return false;
+    try {
+        const out = execFileSync(VENV_BIN, ['--version'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        const m = out.match(/\d+\.\d+\.\d+/);
+        return m?.[0] === TERMRENDER_VERSION;
+    }
+    catch {
+        return false;
+    }
+}
+function uvAvailable() {
+    try {
+        execFileSync('uv', ['--version'], { stdio: 'pipe', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Memoized, self-healing. Ensures the pinned termrender binary exists inside
+ * the humanloop-managed venv; (re)provisions it via `uv` when missing or the
+ * version drifts from the pin. Runs at most once per process. Single
+ * degradation path: `uv` absent → one stderr remediation line + plaintext
+ * fallback. win32 → plaintext (no renderer).
+ *
+ * Invoked at postinstall AND lazily on the first render/check/display call,
+ * so `npm ci --ignore-scripts` consumers still self-heal on first use.
+ */
+export function ensureRenderer() {
+    if (rendererState !== 'unchecked')
+        return;
+    if (process.platform === 'win32') {
+        rendererState = 'unavailable';
+        return;
+    }
+    if (binaryOk()) {
+        rendererState = 'ready';
+        return;
+    }
+    if (!uvAvailable()) {
+        process.stderr.write('[hl] termrender unavailable — install uv to enable rich rendering:\n' +
+            '  curl -LsSf https://astral.sh/uv/install.sh | sh\n');
+        rendererState = 'unavailable';
+        return;
+    }
+    try {
+        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) {
+        process.stderr.write(`[hl] termrender install failed (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+        rendererState = 'unavailable';
+        return;
+    }
+    rendererState = binaryOk() ? 'ready' : 'unavailable';
+    if (rendererState === 'unavailable') {
+        process.stderr.write('[hl] termrender install completed but version check failed; using plaintext fallback\n');
+    }
+}
+/** Cheap predicate — true when the pinned managed binary is present and correct. Does not install. */
+export function isRendererReady() {
+    if (rendererState === 'ready')
+        return true;
+    if (rendererState === 'unavailable')
+        return false;
+    return process.platform !== 'win32' && binaryOk();
+}
+// ── Plaintext fallback helpers (kept here so this is the only termrender site) ─
+const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
+function sanitize(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text.replace(CONTROL_CHARS_RE, '');
+}
+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;
+    }
+    if (out === '' && s.length > 0)
+        out = [...s][0];
+    return out;
+}
+function wrap(text, maxWidth) {
+    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;
+        }
+        const words = para.split(/[ \t]+/).filter(Boolean);
+        let current = '';
+        for (let word of words) {
+            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);
+    }
+    return out.length > 0 ? out : [''];
+}
+// ── Render surface ───────────────────────────────────────────────────────────
+const _bodyCache = new Map();
+/** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
+export function renderMarkdown(md, width) {
+    const key = `${md}\0${width}`;
+    const cached = _bodyCache.get(key);
+    if (cached)
+        return cached;
+    ensureRenderer();
+    if (rendererState === 'ready') {
+        try {
+            const out = execFileSync(VENV_BIN, ['--width', String(width)], {
+                input: md,
+                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] === '')
+                lines.pop();
+            _bodyCache.set(key, lines);
+            return lines;
+        }
+        catch {
+            /* fall through to plaintext */
+        }
+    }
+    const fallback = wrap(sanitize(md), width);
+    _bodyCache.set(key, fallback);
+    return fallback;
+}
+/** Validate markdown via `termrender --check` (exit 0 ok / non-zero error). */
+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,
+        encoding: 'utf-8',
+        timeout: 5000,
+    });
+    if (result.error) {
+        return { ok: false, error: `termrender invocation failed: ${result.error.message}` };
+    }
+    if (result.status !== 0) {
+        return { ok: false, error: `termrender --check exited ${result.status}: ${(result.stderr || '').toString().trim()}` };
+    }
+    return { ok: true };
+}
+/**
+ * Spawn termrender into a live tmux pane. The pane-budget policy (whether to
+ * split vs open a new window) is decided by the caller (`src/surfaces/
+ * display.ts`); this is the thin managed-binary spawn it delegates to.
+ */
+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'] });
+    if (result.error || result.status !== 0)
+        return {};
+    const paneId = (result.stdout?.toString() || '').trim();
+    return paneId ? { paneId } : {};
+}

package/dist/render/version.d.ts

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

package/dist/render/version.js

@@ -0,0 +1 @@
+export const TERMRENDER_VERSION = '1.0.0';

package/dist/scripts/install-renderer.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/install-renderer.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { ensureRenderer, isRendererReady } from '../render/termrender.js';
+// postinstall hook. Best-effort: provision the pinned termrender venv now so
+// the first render is fast. NEVER fail — a renderer hiccup must not brick a
+// consumer's `npm install`. The lazy ensureRenderer() on first render covers
+// the `npm ci --ignore-scripts` case.
+try {
+    ensureRenderer();
+    if (!isRendererReady()) {
+        process.stderr.write('[hl] termrender not provisioned at install time; will retry lazily on first render.\n');
+    }
+}
+catch (err) {
+    process.stderr.write(`[hl] termrender postinstall skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+}
+process.exit(0);

package/dist/surfaces/display.d.ts

@@ -0,0 +1,5 @@
+import type { DisplayOpts } from '../types.js';
+export declare function countPanesInCurrentWindow(): number;
+export declare function display(path: string, opts?: DisplayOpts): {
+    paneId?: string;
+};

package/dist/surfaces/display.js

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { displayInPane } from '../render/termrender.js';
+export function countPanesInCurrentWindow() {
+    // -t '' targets the current window of the current session.
+    const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return 0;
+    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
+}
+export function display(path, opts) {
+    const watch = opts?.watch !== false;
+    const window = (opts?.window === 'split' || opts?.window === 'new') ? opts.window : 'auto';
+    const maxPanes = (opts?.maxPanes !== undefined && opts.maxPanes > 0) ? opts.maxPanes : 3;
+    const newWindow = window === 'new' ||
+        (window === 'auto' && countPanesInCurrentWindow() >= maxPanes);
+    return displayInPane(path, { watch, newWindow });
+}

package/dist/tui/app.d.ts

@@ -1,6 +1,29 @@
-import type { Deck, InteractionResponse, MountedPanel, MountedPanelOpts } from '../types.js';
+import type { Deck, InteractionResponse, MountedPanel, MountedPanelOpts, GenerateVisual } from '../types.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 declare function validateInput(parsed: unknown): Deck;
 export declare function mountPanel(opts: MountedPanelOpts): MountedPanel;
+export interface ResolveDirOpts {
+    /** Claude session id → per-interaction visual context from history. */
+    sessionId?: string;
+    /** Explicit visual generator; overrides the sessionId default. */
+    generateVisual?: GenerateVisual;
+    cols?: number;
+    rows?: number;
+}
+/**
+ * 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 declare function resolveInteractionDir(dir: string, deck: Deck, opts?: ResolveDirOpts): Promise<{
+    responses: InteractionResponse[];
+    completedAt: string;
+    responsePath: string;
+}>;
 export declare function launchTui(decisionsPath: string, sessionId?: string): Promise<{
     responses: InteractionResponse[];
     completedAt: string;