@crouton-kit/humanloop 0.3.38 → 0.4.0

package/dist/tui/render.js

@@ -134,30 +134,46 @@ function buildItemReviewLayout(state, cols, rows) {
     // and live in the scrollable region so long content never overflows the fixed
     // header — agents put rich prose in either field, so both must render markdown.
     const bodyLines = [];
-    if (interaction.subtitle) {
-        bodyLines.push('');
-        for (const line of renderMarkdown(interaction.subtitle, maxW)) {
-            bodyLines.push(`  ${line}`);
+    if (state.bodyMode === 'question') {
+        if (interaction.subtitle) {
+            bodyLines.push('');
+            for (const line of renderMarkdown(interaction.subtitle, maxW)) {
+                bodyLines.push(`  ${line}`);
+            }
         }
-    }
-    if (interaction.body) {
-        bodyLines.push('');
-        for (const line of renderMarkdown(interaction.body, maxW)) {
-            bodyLines.push(`  ${line}`);
+        if (interaction.body) {
+            bodyLines.push('');
+            for (const line of renderMarkdown(interaction.body, maxW)) {
+                bodyLines.push(`  ${line}`);
+            }
         }
     }
-    if (visual && visual.status === 'ready' && state.detailExpanded) {
-        bodyLines.push('');
-        bodyLines.push(`  ${DIM}── context ${hline(maxW - 12)}${RESET}`);
-        for (const vl of visual.content.split('\n')) {
-            bodyLines.push(`  ${vl}`);
+    if (state.bodyMode === 'visual') {
+        if (visual?.status === 'ready') {
+            bodyLines.push('');
+            bodyLines.push(`  ${DIM}── context ${hline(maxW - 12)}${RESET}`);
+            for (const vl of visual.content.split('\n')) {
+                bodyLines.push(`  ${vl}`);
+            }
+            bodyLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
+        }
+        if (state.followUp !== undefined && state.followUp.status !== 'idle') {
+            bodyLines.push('');
+            bodyLines.push(`  ${DIM}── follow-up ${hline(Math.max(0, maxW - 14))}${RESET}`);
+            if (state.followUp.status === 'running')
+                bodyLines.push(`  ${DIM}consulting…${RESET}`);
+            else if (state.followUp.status === 'ready') {
+                for (const line of renderMarkdown(state.followUp.markdown, maxW))
+                    bodyLines.push(`  ${line}`);
+            }
+            else
+                bodyLines.push(`  ${YELLOW}${state.followUp.error}${RESET}`);
         }
-        bodyLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
     }
     // Post-body: visual status hint, input buffer or actions, footer (always visible)
     const postLines = [];
     postLines.push('');
-    if (visual) {
+    if (state.bodyMode === 'visual' && visual) {
         if (visual.status === 'loading') {
             postLines.push(`  ${DIM}loading context...${RESET}`);
             postLines.push('');
@@ -166,10 +182,6 @@ function buildItemReviewLayout(state, cols, rows) {
             postLines.push(`  ${YELLOW}visual context unavailable${RESET}`);
             postLines.push('');
         }
-        else if (!state.detailExpanded) {
-            postLines.push(`  ${DIM}[space] expand context${RESET}`);
-            postLines.push('');
-        }
     }
     if (state.inputMode) {
         postLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
@@ -204,10 +216,10 @@ function buildItemReviewLayout(state, cols, rows) {
             postLines.push(attachedLine);
         }
         postLines.push('');
-        postLines.push(`  ${DIM}enter${RESET} submit  ${DIM}^J/⌥⏎${RESET} newline  ${DIM}^O${RESET} editor  ${DIM}esc${RESET} cancel`);
+        postLines.push(`  ${DIM}enter${RESET} submit  ${DIM}^J/⌥⏎${RESET} newline${state.editorAvailable ? `  ${DIM}^O${RESET} editor` : ''}  ${DIM}esc${RESET} cancel`);
     }
     else {
-        postLines.push(...renderActions(interaction, state.selectedAction, maxW, response));
+        postLines.push(...renderActions(interaction, state.selectedAction, maxW, response, state.followUp?.status !== 'running'));
     }
     // Transient hint (e.g. an empty multi-select Enter that was rejected). Sits
     // just above the footer; cleared on the next keypress.
@@ -236,6 +248,7 @@ function buildItemReviewLayout(state, cols, rows) {
 export function clampItemReviewScroll(state, cols, rows) {
     const { maxScroll } = buildItemReviewLayout(state, cols, rows);
     state.scrollOffset = Math.max(0, Math.min(state.scrollOffset || 0, maxScroll));
+    state.bodyScrollOffsets[state.bodyMode] = state.scrollOffset;
 }
 export function renderItemReview(state, cols, rows) {
     const { interaction, preLines, bodyLines, postLines, maxW, bodyHeight, maxScroll, overflows } = buildItemReviewLayout(state, cols, rows);
@@ -262,18 +275,22 @@ export function renderItemReview(state, cols, rows) {
             `${DIM}n/p${RESET} prev/next`,
             `${DIM}space${RESET} toggle`,
             `${DIM}enter${RESET} confirm`,
+            `${DIM}shift-tab${RESET} ${state.bodyMode === 'question' ? 'visual' : 'question'}`,
             `${DIM}q${RESET} overview`,
         ]
         : [
             `${DIM}n/p${RESET} prev/next`,
-            `${DIM}space${RESET} expand`,
+            `${DIM}shift-tab${RESET} ${state.bodyMode === 'question' ? 'visual' : 'question'}`,
             `${DIM}q${RESET} overview`,
         ];
     if (overflows) {
         footerParts.unshift(state.inputMode ? `${DIM}pgup/pgdn${RESET} scroll` : `${DIM}u/d${RESET} scroll`);
     }
-    if (state.inputMode === null)
+    if (state.inputMode === null) {
+        if (state.followUpAvailable)
+            footerParts.push(`${DIM}?${RESET} follow-up`);
         footerParts.push(`${DIM}w${RESET} browser`);
+    }
     const footer = `  ${footerParts.join('  ')}`;
     // Assemble — pad to fill rows so post-body sits at the bottom
     const lines = [...preLines, ...visibleBody, ...postLines];
@@ -288,7 +305,7 @@ export function renderItemReview(state, cols, rows) {
     // whole block when the terminal is wider than that.
     return centerHorizontal(clamped, cols, maxW + 2);
 }
-function renderActions(interaction, selectedAction, maxW, existing) {
+function renderActions(interaction, selectedAction, maxW, existing, showFocus = true) {
     const lines = [];
     const opts = interaction.options;
     // Prefix on first row: "  X [s] " — 2 + 1 (cursor) + 1 + 3 ([s]) + 1 = 8 visible cols.
@@ -301,7 +318,7 @@ function renderActions(interaction, selectedAction, maxW, existing) {
     const optionComments = existing !== undefined ? existing.optionComments : undefined;
     for (let i = 0; i < opts.length; i++) {
         const o = opts[i];
-        const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
+        const cursor = showFocus && i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
         const sc = o.shortcut === undefined ? ' ' : o.shortcut;
         const keyBadge = `${DIM}[${sc}]${RESET}`;
         const box = multi
@@ -329,7 +346,7 @@ function renderActions(interaction, selectedAction, maxW, existing) {
         }
     }
     if (interaction.allowFreetext && opts.length > 0) {
-        const cursor = opts.length === selectedAction ? `${CYAN}▸${RESET}` : ' ';
+        const cursor = showFocus && opts.length === selectedAction ? `${CYAN}▸${RESET}` : ' ';
         let label;
         if (interaction.freetextLabel !== undefined)
             label = interaction.freetextLabel;

package/dist/tui/terminal.d.ts

@@ -19,6 +19,7 @@ export interface Key {
     ctrl: boolean;
     meta: boolean;
     tab: boolean;
+    backTab: boolean;
     backspace: boolean;
 }
 export type KeypressHandler = (input: string, key: Key) => void;

package/dist/tui/terminal.js

@@ -17,6 +17,7 @@ function emptyKey() {
         ctrl: false,
         meta: false,
         tab: false,
+        backTab: false,
         backspace: false,
     };
 }
@@ -69,6 +70,10 @@ export function parseKeypress(data) {
         key.del = true;
         return { input: '', key };
     }
+    if (str === '\x1b[Z') {
+        key.backTab = true;
+        return { input: '', key };
+    }
     // Alt+Enter inserts a newline in freetext (distinct from Enter=submit). Must
     // precede the bare-ESC and meta-backspace checks so the two-byte sequence
     // isn't swallowed as a lone escape.

package/dist/tui/tmux.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { existsSync, mkdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { logPopupEvent } from './log.js';
 const POPUP_TITLE = 'humanloop · inbox';
 const POPUP_STYLE = 'bg=#20242d';
 const POPUP_BORDER_STYLE = 'fg=#5c6370';
@@ -54,33 +55,42 @@ function acquireStartupLock(path) {
 }
 export async function toggleInboxPopup(target) {
     const socket = target?.socket ?? tmuxSocketFromEnvironment();
-    if (socket === undefined)
+    if (socket === undefined) {
+        logPopupEvent('toggle.rejected', { reason: 'not_in_tmux' });
         return 'not_in_tmux';
+    }
     const inferred = target?.client ?? inferTmuxClient(socket, target?.targetPane);
-    if (inferred === 'ambiguous')
-        return 'ambiguous_client';
-    if (inferred === undefined)
+    if (inferred === 'ambiguous' || inferred === undefined) {
+        logPopupEvent('toggle.rejected', { reason: 'ambiguous_client', socket, targetPane: target?.targetPane });
         return 'ambiguous_client';
+    }
     const resolved = { socket, client: inferred, targetPane: target?.targetPane };
     const paths = popupPaths(resolved);
+    logPopupEvent('toggle.requested', { ...resolved, controlSocket: paths.controlSocket });
     mkdirSync(join(paths.controlSocket, '..'), { recursive: true, mode: 0o700 });
-    if (await requestPopupClose(paths.controlSocket))
+    if (await requestPopupClose(paths.controlSocket)) {
+        logPopupEvent('toggle.closed', { ...resolved, controlSocket: paths.controlSocket });
         return 'closed';
-    // A concurrent toggle for this same client won the startup lock and is opening the popup.
-    // This gesture must not launch a second one; report a benign no-op close rather than a
-    // generic failure, so exactly one popup exists and the loser never exits with an error.
-    if (!acquireStartupLock(paths.startupLock))
+    }
+    // A concurrent toggle for this same client owns popup startup. This gesture
+    // leaves that startup as the sole owner and reports a benign close result.
+    if (!acquireStartupLock(paths.startupLock)) {
+        logPopupEvent('toggle.coalesced', { ...resolved, controlSocket: paths.controlSocket });
         return 'closed';
+    }
     try {
-        // Re-probe under the lock: between the first probe and acquiring the lock a concurrent
-        // toggle may have brought a live popup up. Deleting its control socket now would orphan
-        // that popup, so close it instead. The finally below releases the lock on every path.
-        if (await requestPopupClose(paths.controlSocket))
+        // Re-probe under the lock so a popup that became live during lock acquisition
+        // is closed through its controller rather than orphaned.
+        if (await requestPopupClose(paths.controlSocket)) {
+            logPopupEvent('toggle.closed', { ...resolved, controlSocket: paths.controlSocket, phase: 'locked-reprobe' });
             return 'closed';
+        }
         if (existsSync(paths.controlSocket))
             rmSync(paths.controlSocket, { force: true });
         const command = `${quote(process.execPath)} ${quote(fileURLToPath(new URL('../cli.js', import.meta.url)))} inbox open --control-socket ${quote(paths.controlSocket)}`;
-        return await launchPopup(socket, resolved, paths.controlSocket, command);
+        const result = await launchPopup(socket, resolved, paths.controlSocket, command);
+        logPopupEvent('toggle.completed', { ...resolved, controlSocket: paths.controlSocket, result });
+        return result;
     }
     finally {
         rmSync(paths.startupLock, { recursive: true, force: true });
@@ -100,17 +110,27 @@ async function requestPopupClose(controlSocket) {
 /** Launch one popup and report `opened` only once its controller owns the control socket. */
 async function launchPopup(socket, target, controlSocket, command) {
     const args = ['-S', socket, 'display-popup', '-E', '-c', target.client, ...inboxPopupFlags(), ...(target.targetPane === undefined ? [] : ['-t', target.targetPane]), command];
+    const startedAt = Date.now();
     const child = spawn('tmux', args, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+    logPopupEvent('popup.spawned', { ...target, controlSocket, pid: child.pid, args });
     let stderr = '';
-    child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+    child.stderr.on('data', (chunk) => {
+        stderr += chunk.toString('utf8');
+        if (stderr.length > 8192)
+            stderr = stderr.slice(-8192);
+    });
     const exited = new Promise((resolve) => {
-        // `display-popup -E` blocks until our popup closes, so a successful open keeps the child
-        // alive while the control socket comes up (detected below). An early exit before that means
-        // the popup command never ran: tmux 3.x silently declines to stack a popup on a client that
-        // already shows one (exit 0, command dropped), which is exactly the foreign-popup case the
-        // design must report as `other_popup` without disturbing the existing popup or its process.
-        child.once('exit', (code) => resolve(code === 0 || /popup/i.test(stderr) ? 'other_popup' : 'failed'));
-        child.once('error', () => resolve('failed'));
+        // `display-popup -E` blocks until the popup closes. An exit before the
+        // controller socket is live means tmux declined or failed the launch.
+        child.once('exit', (code, signal) => {
+            const result = code === 0 || /popup/i.test(stderr) ? 'other_popup' : 'failed';
+            logPopupEvent('popup.exited', { ...target, controlSocket, pid: child.pid, code, signal, result, stderr: stderr.trim(), elapsedMs: Date.now() - startedAt });
+            resolve(result);
+        });
+        child.once('error', (error) => {
+            logPopupEvent('popup.error', { ...target, controlSocket, pid: child.pid, error: error.message, stderr: stderr.trim(), elapsedMs: Date.now() - startedAt });
+            resolve('failed');
+        });
     });
     const { Socket } = await import('node:net');
     for (let attempt = 0; attempt < 50; attempt++) {
@@ -125,12 +145,14 @@ async function launchPopup(socket, target, controlSocket, command) {
             }),
         ]);
         if (outcome === 'opened') {
+            logPopupEvent('popup.opened', { ...target, controlSocket, pid: child.pid, elapsedMs: Date.now() - startedAt });
             child.unref();
             return 'opened';
         }
         if (outcome !== 'pending')
             return outcome;
     }
+    logPopupEvent('popup.startup_timeout', { ...target, controlSocket, pid: child.pid, stderr: stderr.trim(), elapsedMs: Date.now() - startedAt });
     return 'failed';
 }
 /** The static tmux `display-popup` geometry and style flags; the client and target pane are added per-invocation. */

package/dist/types.d.ts

@@ -68,6 +68,8 @@ export interface DeckSource {
      *  a crouter canvas node. Lets per-node attention scoping attribute the ask
      *  to the node that raised it rather than every sibling sharing the cwd. */
     nodeId?: string;
+    /** Host-owned durable Visual capability marker. A registered handler is also required. */
+    visual?: 'humanloop.visual/v1';
 }
 export interface Deck {
     title?: string;
@@ -103,8 +105,21 @@ export interface FeedbackResult {
 export interface VisualBlock {
     questionId: string;
     content: string;
+    /** Original model output, retained so resize can re-render locally. */
+    markdown?: string;
     status: 'loading' | 'ready' | 'error';
 }
+export type FollowUpState = {
+    status: 'idle';
+} | {
+    status: 'running';
+} | {
+    status: 'ready';
+    markdown: string;
+} | {
+    status: 'error';
+    error: string;
+};
 export type Phase = 'overview' | 'item-review' | 'final';
 export type InputMode = null | {
     kind: 'comment';
@@ -115,6 +130,10 @@ export type InputMode = null | {
     kind: 'freetext';
     buffer: string;
     cursor: number;
+} | {
+    kind: 'follow-up';
+    buffer: string;
+    cursor: number;
 };
 export interface TuiState {
     phase: Phase;
@@ -128,8 +147,16 @@ export interface TuiState {
     preAnsweredIds: Set<string>;
     inputMode: InputMode;
     selectedAction: number;
-    detailExpanded: boolean;
+    bodyMode: 'question' | 'visual';
     scrollOffset: number;
+    bodyScrollOffsets: {
+        question: number;
+        visual: number;
+    };
+    /** The mounting host provided an active Ctrl+O editor callback. */
+    editorAvailable: boolean;
+    followUpAvailable: boolean;
+    followUp?: FollowUpState;
     /** Transient one-line notice shown in item-review (e.g. an empty multi-select
      *  Enter that was rejected). Cleared on the next keypress. */
     hint?: string;
@@ -228,18 +255,52 @@ export interface DisplayOpts {
     /** Pane budget per window before `'auto'` opens a new window. Default 3. */
     maxPanes?: number;
 }
-export type GenerateVisual = (interaction: Interaction) => Promise<{
-    ok: true;
-    ansi: string;
+/** Width-free Interaction snapshot shared by the panel and durable Visual protocol. */
+export interface CanonicalInteractionOption {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface CanonicalInteraction {
+    id: string;
+    title: string;
+    subtitle?: string;
+    body?: string;
+    options: CanonicalInteractionOption[];
+    multiSelect?: boolean;
+    allowFreetext?: boolean;
+    freetextLabel?: string;
+    kind?: InteractionKind;
+    preAnswered?: InteractionPreAnswer;
+}
+export interface VisualRequest {
+    requestId: string;
+    generationId: string;
+    interaction: CanonicalInteraction;
+}
+export type VisualResult = {
+    status: 'ready';
     markdown: string;
 } | {
-    ok: false;
+    status: 'error';
     error: string;
-}>;
+};
+export interface VisualHandle {
+    result: Promise<VisualResult>;
+    /** Synchronous and idempotent. A canceled handle has no renderable result. */
+    cancel(): void;
+}
+/** Host-injected, Markdown-only Visual capability. Rendering width belongs to the panel. */
+export type VisualProvider = (request: VisualRequest) => VisualHandle;
 export interface MountedPanelOpts {
     deck: Deck;
     progressPath?: string;
-    generateVisual?: GenerateVisual;
+    visualProvider?: VisualProvider;
+    /** Host callback for Ctrl+O while a comment/freetext buffer is active. */
+    onEditorRequest?: () => void;
+    followUpAvailable?: boolean;
+    onFollowUpRequest?: (question: string) => void;
+    onFollowUpCancel?: () => void;
     cols: number;
     rows: number;
     onProgress?: (responses: InteractionResponse[]) => void;
@@ -258,7 +319,10 @@ export interface MountedPanel {
     unmount(): void;
     loadDeck(deck: Deck, opts?: {
         progressPath?: string;
+        visualProvider?: VisualProvider;
     }): void;
+    setFollowUpHandlers(available: boolean, onRequest?: (question: string) => void, onCancel?: () => void): void;
+    setFollowUpState(state: FollowUpState): void;
     canAcceptHostKeys(): boolean;
     /**
      * True when the deck is at its top level: overview phase with no active