@crouton-kit/humanloop 0.3.33 → 0.3.35

package/dist/inbox/tui.js

@@ -1,7 +1,4 @@
-import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize, } from '../tui/terminal.js';
-import { diffFrame } from '../tui/render.js';
 import { RESET, BOLD, DIM, ITALIC, CYAN, RED, GRAY, YELLOW, truncateRow } from '../tui/ansi.js';
-// ── ANSI helpers (local to this module) ──────────────────────────────────────
 function ansiColor(text, color) {
     switch (color) {
         case 'gray': return `${GRAY}${text}${RESET}`;
@@ -11,124 +8,39 @@ function ansiColor(text, color) {
         default: return text;
     }
 }
-// ── Row model (ported verbatim from sisyphus cross-session-inbox.ts:8-21) ────
-export const KIND_ICON = {
-    notify: '✉',
-    decision: '◆',
-    context: '✎',
-    error: '⚠',
-};
-export const KIND_COLOR = {
-    notify: 'gray',
-    decision: 'cyan',
-    context: 'cyan',
-    error: 'red',
-};
-// ── formatTimeAgo (ported from sisyphus src/tui/lib/format.ts:5-12) ──────────
+export const KIND_ICON = { notify: '✉', decision: '◆', context: '✎', error: '⚠', review: '▤' };
+export const KIND_COLOR = { notify: 'gray', decision: 'cyan', context: 'cyan', error: 'red', review: 'yellow' };
 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`;
+    const minutes = Math.floor((Date.now() - new Date(iso).getTime()) / 60000);
+    if (minutes >= 60)
+        return `${Math.floor(minutes / 60)}h ago`;
     if (minutes > 0)
         return `${minutes}m ago`;
     return 'just now';
 }
-// ── buildInboxLines ───────────────────────────────────────────────────────────
+/** Pure inbox rows; selection and terminal ownership belong to InboxController. */
 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('');
+    if (items.length === 0)
+        return [`  ${DIM}${ITALIC}No pending interactions${RESET}`];
+    const lines = [`  ${BOLD}${items.length} pending${RESET}`, ''];
     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}${truncateRow(titleText, maxTitle)}${RESET}`;
-        row += `  ${DIM}${blocked}${RESET}`;
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
+        const icon = KIND_ICON[kind] ?? '·';
+        const source = item.source.sessionName ?? item.source.askedBy ?? item.source.nodeId ?? '';
+        const age = formatTimeAgo(item.blockedSince);
+        const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
+        const titleWidth = Math.max(10, contentWidth - source.length - age.length - 8);
+        let row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} `;
+        if (source)
+            row += `${ansiColor(source, 'yellow')} ${DIM}·${RESET} `;
+        row += `${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
         lines.push(row);
-        if (item.subtitle) {
+        if (item.claim)
+            lines.push(`      ${DIM}claimed by ${item.claim.owner}${RESET}`);
+        else if (item.subtitle)
             lines.push(`      ${DIM}${truncateRow(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, currentCols);
-            process.stdout.write('\x1b[?2026h');
-            for (const w of writes)
-                process.stdout.write(w);
-            process.stdout.write('\x1b[?2026l');
-            prevFrame = nextPrevFrame;
-        };
-        // Resize reflows/scrolls what's already on screen, invalidating the diff
-        // model — clear and redraw from scratch at the new size.
-        const onResize = () => {
-            prevFrame = [];
-            process.stdout.write('\x1b[2J\x1b[H');
-            flush();
-        };
-        const done = (result) => {
-            restoreTerminal();
-            process.stdin.removeListener('data', onData);
-            process.stdout.removeListener('resize', onResize);
-            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', onResize);
-    });
-}

package/dist/index.d.ts

@@ -3,15 +3,24 @@ export { defaultGenerateVisual } from './visuals/generate.js';
 export { launchReview } from './editor/review.js';
 export { launchReview as review } from './editor/review.js';
 export type { ReviewOptions } from './editor/review.js';
-export { ask, notify, inbox } from './api.js';
+export { ask, notify, openInbox } from './api.js';
+export { openInboxPopup } from './surfaces/inbox-popup.js';
+export { toggleInboxPopup, installInboxBinding, inspectInboxBinding, unbindInboxBinding, inboxPopupStyle } from './tui/tmux.js';
 export { display } from './surfaces/display.js';
 export { scanInbox } from './inbox/scan.js';
+export { registerInboxRoot, unregisterInboxRoot, listInboxRoots, managedInboxRoot } from './inbox/registry.js';
+export type { CompletionHandler, InboxRootRegistration, InboxRootStatus, RegisterInboxRootOptions } from './inbox/registry.js';
+export { submitDeck, submitReview, readTicketResult, finalizeDeck, finalizeReview, completeDeck, completeReview, cancelTicket, cancelTicketResult, } from './inbox/tickets.js';
+export type { SubmitDeckOptions, SubmitReviewOptions } from './inbox/tickets.js';
+export { dispatchCompletion, reconcileCompletions } from './inbox/completion.js';
+export { claimTicket, heartbeatClaim, releaseClaim, readTicketClaim } from './inbox/claim.js';
+export type { TicketClaim, ClaimOptions } from './inbox/claim.js';
 export { renderMarkdown, checkMarkdown, ensureRenderer, isRendererReady, } from './render/termrender.js';
 export { parseDeck, validateDeck, deckSchema, resolveDeckBodyPaths } from './inbox/deck-schema.js';
 export { notifyDeck } from './inbox/deck-factories.js';
 export type { NotifyDeckOpts } from './inbox/deck-factories.js';
-export { deckPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';
+export { deckPath, reviewPath, 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 { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, InboxBindingState, CompletionEvent, } from './types.js';
 export type { Key } from './tui/terminal.js';
 export type { ConversationMessage } from './conversation/reader.js';

package/dist/index.js

@@ -3,9 +3,15 @@ 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, notify, inbox } from './api.js';
+export { ask, notify, openInbox } from './api.js';
+export { openInboxPopup } from './surfaces/inbox-popup.js';
+export { toggleInboxPopup, installInboxBinding, inspectInboxBinding, unbindInboxBinding, inboxPopupStyle } from './tui/tmux.js';
 export { display } from './surfaces/display.js';
 export { scanInbox } from './inbox/scan.js';
+export { registerInboxRoot, unregisterInboxRoot, listInboxRoots, managedInboxRoot } from './inbox/registry.js';
+export { submitDeck, submitReview, readTicketResult, finalizeDeck, finalizeReview, completeDeck, completeReview, cancelTicket, cancelTicketResult, } from './inbox/tickets.js';
+export { dispatchCompletion, reconcileCompletions } from './inbox/completion.js';
+export { claimTicket, heartbeatClaim, releaseClaim, readTicketClaim } from './inbox/claim.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';
@@ -15,4 +21,4 @@ export { parseDeck, validateDeck, deckSchema, resolveDeckBodyPaths } from './inb
 // who want validated Yes/No or notify decks without inline construction).
 export { notifyDeck } from './inbox/deck-factories.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';
+export { deckPath, reviewPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';

package/dist/render/termrender.d.ts

@@ -5,6 +5,11 @@
  * degradation path: `uv` absent → one stderr remediation line + plaintext
  * fallback. win32 → plaintext (no renderer).
  *
+ * Steady state is subprocess-free: a valid stamp is trusted outright. The
+ * spawn-based verification (`binaryOk` + `installedVersion`) runs only when the
+ * stamp is absent or stale — once, after which the venv is re-stamped — and the
+ * full `uv` reinstall runs only when the binary is actually missing or drifted.
+ *
  * Invoked at postinstall AND lazily on the first render/check/display call,
  * so `npm ci --ignore-scripts` consumers still self-heal on first use.
  */

package/dist/render/termrender.js

@@ -1,5 +1,5 @@
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import stringWidth from 'string-width';
@@ -27,7 +27,48 @@ 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');
+// Stamp written after a verified install: records the pin we provisioned and
+// the binary's mtime at that moment. Steady-state validation is a stat + a
+// tiny JSON read against this — no subprocess — so attach no longer pays the
+// ~149ms `termrender -h` + `importlib.metadata` spawn tax on every launch.
+const VENV_STAMP = resolve(PKG_ROOT, '.venv/.hl-termrender-stamp.json');
 let rendererState = 'unchecked';
+function readStamp() {
+    try {
+        const parsed = JSON.parse(readFileSync(VENV_STAMP, 'utf8'));
+        if (typeof parsed.version === 'string' && typeof parsed.mtimeMs === 'number')
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeStamp() {
+    try {
+        writeFileSync(VENV_STAMP, JSON.stringify({ version: TERMRENDER_VERSION, mtimeMs: statSync(VENV_BIN).mtimeMs }));
+    }
+    catch {
+        // Best-effort: an unwritable stamp just means the next process re-verifies
+        // the slow way once and re-stamps. Correctness is unaffected.
+    }
+}
+// Cheap steady-state trust: the pinned binary is present and unchanged since
+// the verified install that wrote the stamp. A version bump or an out-of-band
+// rewrite of the binary changes the pin or the mtime and forces re-provision.
+function stampValid() {
+    if (!existsSync(VENV_BIN))
+        return false;
+    const stamp = readStamp();
+    if (!stamp || stamp.version !== TERMRENDER_VERSION)
+        return false;
+    try {
+        return statSync(VENV_BIN).mtimeMs === stamp.mtimeMs;
+    }
+    catch {
+        return false;
+    }
+}
 function binaryOk() {
     if (!existsSync(VENV_BIN))
         return false;
@@ -76,6 +117,11 @@ function uvAvailable() {
  * degradation path: `uv` absent → one stderr remediation line + plaintext
  * fallback. win32 → plaintext (no renderer).
  *
+ * Steady state is subprocess-free: a valid stamp is trusted outright. The
+ * spawn-based verification (`binaryOk` + `installedVersion`) runs only when the
+ * stamp is absent or stale — once, after which the venv is re-stamped — and the
+ * full `uv` reinstall runs only when the binary is actually missing or drifted.
+ *
  * Invoked at postinstall AND lazily on the first render/check/display call,
  * so `npm ci --ignore-scripts` consumers still self-heal on first use.
  */
@@ -86,7 +132,16 @@ export function ensureRenderer() {
         rendererState = 'unavailable';
         return;
     }
+    // Steady state: trust the stamp — zero subprocess spawns.
+    if (stampValid()) {
+        rendererState = 'ready';
+        return;
+    }
+    // No/stale stamp but the correct binary is already present (a venv from a
+    // pre-stamp humanloop, or an interrupted stamp write): verify once the slow
+    // way, stamp it, and skip the reinstall.
     if (binaryOk() && installedVersion() === TERMRENDER_VERSION) {
+        writeStamp();
         rendererState = 'ready';
         return;
     }
@@ -113,8 +168,12 @@ export function ensureRenderer() {
         rendererState = 'unavailable';
         return;
     }
-    rendererState = (binaryOk() && installedVersion() === TERMRENDER_VERSION) ? 'ready' : 'unavailable';
-    if (rendererState === 'unavailable') {
+    if (binaryOk() && installedVersion() === TERMRENDER_VERSION) {
+        writeStamp();
+        rendererState = 'ready';
+    }
+    else {
+        rendererState = 'unavailable';
         process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
     }
 }
@@ -124,7 +183,7 @@ export function isRendererReady() {
         return true;
     if (rendererState === 'unavailable')
         return false;
-    return process.platform !== 'win32' && binaryOk();
+    return process.platform !== 'win32' && (stampValid() || 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;

package/dist/summary.d.ts

@@ -2,8 +2,7 @@ import type { Deck, InteractionResponse } from './types.js';
 /**
  * Deterministic, no-LLM resolution summary — one line per answered
  * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
- * (envelope summary), `writeResponse` (persisted into response.json at write
- * time), and `hl job result` (fallback rebuild for legacy response.json files
- * written before the summary field existed).
+ * (envelope summary) and `writeResponse` (persisted into response.json at write
+ * time).
  */
 export declare function buildSummary(deck: Deck, responses: InteractionResponse[]): string;

package/dist/summary.js

@@ -1,9 +1,8 @@
 /**
  * Deterministic, no-LLM resolution summary — one line per answered
  * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
- * (envelope summary), `writeResponse` (persisted into response.json at write
- * time), and `hl job result` (fallback rebuild for legacy response.json files
- * written before the summary field existed).
+ * (envelope summary) and `writeResponse` (persisted into response.json at write
+ * time).
  */
 export function buildSummary(deck, responses) {
     const byId = new Map(responses.map((r) => [r.id, r]));

package/dist/surfaces/inbox-popup.d.ts

@@ -0,0 +1,2 @@
+/** Run the inbox controller in a popup-owned TTY and accept graceful close requests. */
+export declare function openInboxPopup(controlSocket?: string, roots?: string[]): Promise<void>;

package/dist/surfaces/inbox-popup.js

@@ -0,0 +1,32 @@
+import { createServer } from 'node:net';
+import { rmSync } from 'node:fs';
+import { InboxController } from '../inbox/controller.js';
+/** Run the inbox controller in a popup-owned TTY and accept graceful close requests. */
+export async function openInboxPopup(controlSocket, roots) {
+    const controller = new InboxController({ roots });
+    const server = controlSocket === undefined ? undefined : createServer((connection) => {
+        connection.once('data', (data) => {
+            if (data.toString('utf8').trim() === 'close')
+                controller.close();
+            connection.end();
+        });
+    });
+    if (server !== undefined && controlSocket !== undefined) {
+        try {
+            rmSync(controlSocket, { force: true });
+        }
+        catch { /* socket ownership is established by listen */ }
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(controlSocket, resolve);
+        });
+    }
+    try {
+        await controller.run();
+    }
+    finally {
+        await new Promise((resolve) => server?.close(() => resolve()) ?? resolve());
+        if (controlSocket !== undefined)
+            rmSync(controlSocket, { force: true });
+    }
+}

package/dist/tui/app.js

@@ -203,6 +203,7 @@ export function mountPanel(opts) {
         loadDeck(deck, loadOpts) {
             if (!internals.mounted)
                 return;
+            const prior = collectResponses(internals.state);
             internals.state = buildInitialState(deck);
             if (loadOpts !== undefined && loadOpts.progressPath !== undefined) {
                 internals.progressPath = loadOpts.progressPath;
@@ -212,6 +213,18 @@ export function mountPanel(opts) {
             if (internals.progressPath !== undefined) {
                 tryResume(internals.state, internals.progressPath, deck.interactions);
             }
+            // A live request replacement is allowed to add/remove questions but not
+            // discard answers the human has already made to surviving ids.
+            const validIds = new Set(deck.interactions.map((interaction) => interaction.id));
+            for (const response of prior) {
+                if (validIds.has(response.id))
+                    internals.state.responses.set(response.id, response);
+            }
+            const currentId = internals.state.interactions[internals.state.currentIndex]?.id;
+            if (currentId === undefined || !validIds.has(currentId)) {
+                const firstUnanswered = internals.state.interactions.findIndex((interaction) => !internals.state.responses.has(interaction.id));
+                internals.state.currentIndex = firstUnanswered >= 0 ? firstUnanswered : 0;
+            }
             fireVisuals(internals, deck.interactions);
         },
         canAcceptHostKeys() {

package/dist/tui/tmux.d.ts

@@ -1,8 +1,31 @@
-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;
+import type { InboxBindingState } from '../types.js';
+export interface TmuxPopupTarget {
+    socket: string;
+    client: string;
+    targetPane?: string;
 }
-export declare function dispatchToTmuxPane(file: string, opts: TmuxDispatchOpts): Promise<ResolutionEnvelope>;
+export type ToggleInboxPopupResult = 'opened' | 'closed' | 'other_popup' | 'ambiguous_client' | 'not_in_tmux' | 'failed';
+export declare function popupPaths(target: TmuxPopupTarget): {
+    controlSocket: string;
+    startupLock: string;
+};
+export declare function inspectInboxBinding(socket?: string | undefined): InboxBindingState;
+export declare function installInboxBinding(opts?: {
+    socket?: string;
+    key?: string;
+}): InboxBindingState;
+export declare function unbindInboxBinding(socket?: string | undefined): InboxBindingState;
+export declare function tmuxSocketFromEnvironment(): string | undefined;
+export declare function inferTmuxClient(socket: string, pane?: string | undefined): string | undefined | 'ambiguous';
+export declare function toggleInboxPopup(target?: Partial<TmuxPopupTarget>): Promise<ToggleInboxPopupResult>;
+/** The static tmux `display-popup` geometry and style flags; the client and target pane are added per-invocation. */
+export declare function inboxPopupFlags(): string[];
+export declare const inboxPopupStyle: {
+    readonly width: "90%";
+    readonly height: "90%";
+    readonly border: "rounded";
+    readonly title: "humanloop · inbox";
+    readonly background: "#20242d";
+    readonly chrome: "#2b3245";
+    readonly borderColor: "#5c6370";
+};