@crouton-kit/humanloop 0.3.37 → 0.3.39

package/dist/tui/render.js

@@ -74,7 +74,7 @@ export function renderOverview(state, cols, rows) {
         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`);
+    lines.push(`  ${DIM}enter${RESET} review  ${DIM}j/k${RESET} navigate  ${DIM}w${RESET} browser  ${DIM}q${RESET} finish`);
     while (lines.length < rows)
         lines.push('');
     // Overview content extends roughly cols-16 wide for option labels; center
@@ -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,7 +216,7 @@ 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));
@@ -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,16 +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.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];

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,9 @@ 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;
+    /** Durable identifier of the conversation session that originated this ask.
+     *  It is explicit metadata, never inferred from node identity or labels. */
+    originatingConversationSessionId?: string;
 }
 export interface Deck {
     title?: string;
@@ -103,8 +106,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 +131,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 +148,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,7 +256,9 @@ export interface DisplayOpts {
     /** Pane budget per window before `'auto'` opens a new window. Default 3. */
     maxPanes?: number;
 }
-export type GenerateVisual = (interaction: Interaction) => Promise<{
+export type GenerateVisual = (interaction: Interaction, 
+/** Render width owned by the mounting surface. */
+cols: number) => Promise<{
     ok: true;
     ansi: string;
     markdown: string;
@@ -240,6 +270,11 @@ export interface MountedPanelOpts {
     deck: Deck;
     progressPath?: string;
     generateVisual?: GenerateVisual;
+    /** 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;
@@ -259,6 +294,8 @@ export interface MountedPanel {
     loadDeck(deck: Deck, opts?: {
         progressPath?: string;
     }): 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

package/dist/visuals/conversation.d.ts

@@ -0,0 +1,7 @@
+import type { GenerateVisual, Interaction } from '../types.js';
+import { defaultGenerateVisual } from './generate.js';
+type VisualGenerator = (interaction: Interaction, conversationContext: string, cols?: number) => ReturnType<typeof defaultGenerateVisual>;
+type ConversationTextReader = (sessionId: string) => Promise<string>;
+/** Build the standard visual generator from explicit originating-session metadata. */
+export declare function visualGeneratorForConversationSession(sessionId: string, generateVisual?: VisualGenerator, readContext?: ConversationTextReader): GenerateVisual;
+export {};

package/dist/visuals/conversation.js

@@ -0,0 +1,16 @@
+import { readConversationText } from '../conversation/reader.js';
+import { defaultGenerateVisual } from './generate.js';
+/** Build the standard visual generator from explicit originating-session metadata. */
+export function visualGeneratorForConversationSession(sessionId, generateVisual = defaultGenerateVisual, readContext = readConversationText) {
+    // One lookup feeds every interaction and resize regeneration in this mounted panel.
+    // A failed lookup remains a failed visual rather than falling through to a generic prompt.
+    const context = readContext(sessionId);
+    return async (interaction, cols) => {
+        try {
+            return await generateVisual(interaction, await context, cols);
+        }
+        catch {
+            return { ok: false, error: 'visual context unavailable' };
+        }
+    };
+}

package/dist/visuals/generate.d.ts

@@ -1,5 +1,7 @@
 import type { Interaction } from '../types.js';
-export declare function defaultGenerateVisual(interaction: Interaction, conversationContext: string): Promise<{
+/** Width shared by model-time and local resize-time visual rendering. */
+export declare function visualRenderWidth(cols: number): number;
+export declare function defaultGenerateVisual(interaction: Interaction, conversationContext: string, cols?: number): Promise<{
     ok: true;
     ansi: string;
     markdown: string;

package/dist/visuals/generate.js

@@ -42,16 +42,18 @@ async function callHaiku(prompt, systemPrompt) {
         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
-// in the correct width.
+// The mounting surface supplies its actual render width; generated ANSI must
+// fit an embedded panel just as it fits a standalone terminal.
 // Cap on how much conversation we hand the generator. Recency is what grounds
 // the decision in front of the human, so when history is long we keep the tail
 // (most recent messages) rather than the head.
 const MAX_CONTEXT_CHARS = 24000;
-export async function defaultGenerateVisual(interaction, conversationContext) {
-    const width = Math.max(40, Math.min((process.stdout.columns || 80) - 4, 76));
+/** Width shared by model-time and local resize-time visual rendering. */
+export function visualRenderWidth(cols) {
+    return Math.max(1, Math.min(cols - 4, 76));
+}
+export async function defaultGenerateVisual(interaction, conversationContext, cols = (process.stdout.columns || 80)) {
+    const width = visualRenderWidth(cols);
     const optionsSummary = interaction.options.length > 0
         ? `\nOptions: ${interaction.options.map((o) => o.label).join(' | ')}`
         : '';