@crouton-kit/humanloop 0.3.38 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 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';
 export type { ReviewOptions } from './editor/review.js';
@@ -13,6 +12,10 @@ export type { CompletionHandler, InboxRootRegistration, InboxRootStatus, Registe
 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 { requestFollowUp, cancelFollowUp, submitFollowUpResult, readFollowUp } from './inbox/followup.js';
+export type { FollowUpRequestEvent, FollowUpRequest, FollowUpResult } from './inbox/followup.js';
+export { VISUAL_CAPABILITY, canonicalizeInteraction, canonicalInteractionJson, parseVisualRequestEvent, readVisualRequest, readVisualResult, readVisualRequestForEvent, startVisualRequest, submitVisualResult, cancelVisualRequest, cancelVisualRequestsForTicket, dispatchVisualCleanup, listVisualCleanupObligations, listVisualCleanupObligationsForRoot, reconcileVisualRequestsForTicket, reconcileStaleVisualRequestsForRoot, } from './inbox/visual.js';
+export type { VisualClaimIdentity, VisualCleanupObligation, VisualProtocolRequest, VisualRequestEvent, VisualProtocolResult, VisualResultSubmission, StartVisualRequestOptions, StartedVisualRequest, VisualStartDeliveryResult, VisualCleanupDeliveryResult, VisualCleanupTask, VisualRequestReconciliation, } from './inbox/visual.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';
@@ -21,6 +24,5 @@ export { notifyDeck } from './inbox/deck-factories.js';
 export type { NotifyDeckOpts } from './inbox/deck-factories.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, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, CompletionEvent, } from './types.js';
+export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, CanonicalInteractionOption, CanonicalInteraction, MountedPanel, MountedPanelOpts, VisualProvider, VisualRequest, VisualHandle, VisualResult, VisualBlock, FollowUpState, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, CompletionEvent, } from './types.js';
 export type { Key } from './tui/terminal.js';
-export type { ConversationMessage } from './conversation/reader.js';

package/dist/index.js

@@ -1,5 +1,4 @@
 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).
@@ -11,6 +10,8 @@ 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 { requestFollowUp, cancelFollowUp, submitFollowUpResult, readFollowUp } from './inbox/followup.js';
+export { VISUAL_CAPABILITY, canonicalizeInteraction, canonicalInteractionJson, parseVisualRequestEvent, readVisualRequest, readVisualResult, readVisualRequestForEvent, startVisualRequest, submitVisualResult, cancelVisualRequest, cancelVisualRequestsForTicket, dispatchVisualCleanup, listVisualCleanupObligations, listVisualCleanupObligationsForRoot, reconcileVisualRequestsForTicket, reconcileStaleVisualRequestsForRoot, } from './inbox/visual.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.

package/dist/tui/app.d.ts

@@ -1,14 +1,11 @@
-import type { Deck, InteractionResponse, MountedPanel, MountedPanelOpts, GenerateVisual } from '../types.js';
+import type { Deck, InteractionResponse, MountedPanel, MountedPanelOpts, VisualProvider } 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;
+    visualProvider?: VisualProvider;
     cols?: number;
     rows?: number;
 }
@@ -31,7 +28,7 @@ export declare function resolveInteractionDir(dir: string, deck: Deck, opts?: Re
     responsePath: string;
     deck: Deck;
 }>;
-export declare function launchTui(decisionsPath: string, sessionId?: string): Promise<{
+export declare function launchTui(decisionsPath: string, opts?: ResolveDirOpts): Promise<{
     responses: InteractionResponse[];
     completedAt: string;
 }>;

package/dist/tui/app.js

@@ -1,14 +1,13 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
-import { dirname, resolve as resolvePath, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
+import { dirname, resolve as resolvePath } from 'node:path';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
 import { diffFrame, renderOverview, renderItemReview, renderFinal, renderHandoff, clampItemReviewScroll } from './render.js';
 import { handleKeypress, assignShortcuts } from './input.js';
-import { readConversation } from '../conversation/reader.js';
-import { defaultGenerateVisual } from '../visuals/generate.js';
+import { renderMarkdown } from '../render/termrender.js';
+import { editBufferInEditor } from '../editor/roundtrip.js';
 import { validateDeck } from '../inbox/deck-schema.js';
+import { canonicalizeInteraction } from '../inbox/visual.js';
 import { progressPath as progressPathFor, deckPath as deckPathFor, writeResponse, clearProgress } from '../inbox/convention.js';
 import { startWebServer } from '../browser/server.js';
 import { openBrowser } from '../browser/open.js';
@@ -19,7 +18,7 @@ export function validateInput(parsed) {
     return validateDeck(parsed);
 }
 // ── Internal helpers ──────────────────────────────────────────────────────────
-function buildInitialState(deck) {
+function buildInitialState(deck, editorAvailable = false, followUpAvailable = false) {
     // Single-question decks skip the overview list — there's nothing to overview,
     // and overview hides the option hotkeys so users press 'y' and nothing happens.
     const initialPhase = deck.interactions.length === 1 ? 'item-review' : 'overview';
@@ -55,8 +54,12 @@ function buildInitialState(deck) {
         preAnsweredIds,
         inputMode: null,
         selectedAction: 0,
-        detailExpanded: false,
+        bodyMode: 'question',
         scrollOffset: 0,
+        bodyScrollOffsets: { question: 0, visual: 0 },
+        editorAvailable,
+        followUpAvailable,
+        followUp: undefined,
     };
 }
 function collectResponses(state) {
@@ -104,25 +107,72 @@ function rebindPersist(internals) {
         internals.callbacks.onProgress?.(responses);
     };
 }
+function visualRenderWidth(cols) {
+    return Math.max(1, Math.min(cols - 4, 76));
+}
+function renderVisualMarkdown(markdown, cols) {
+    return renderMarkdown(markdown, visualRenderWidth(cols)).join('\n');
+}
+/** Reflow ready Visual Markdown locally without issuing another request. */
+function rerenderVisuals(internals) {
+    for (const [id, visual] of internals.state.visuals) {
+        if (visual.status !== 'ready' || visual.markdown === undefined)
+            continue;
+        internals.state.visuals.set(id, { ...visual, content: renderVisualMarkdown(visual.markdown, internals.cols) });
+    }
+}
+function visualRequestInteraction(interaction) {
+    return canonicalizeInteraction(interaction);
+}
+function retireVisuals(internals) {
+    internals.visualGeneration += 1;
+    const handles = [...internals.visualHandles.values()];
+    internals.visualHandles.clear();
+    internals.state.visuals.clear();
+    for (const handle of handles) {
+        try {
+            handle.cancel();
+        }
+        catch { /* stale UI currency remains authoritative even if a host cancel fails */ }
+    }
+}
 function fireVisuals(internals, interactions) {
-    if (internals.generateVisual === undefined)
+    const provider = internals.visualProvider;
+    if (provider === undefined)
         return;
-    const gen = internals.generateVisual;
+    const generation = internals.visualGeneration;
+    const generationId = randomUUID();
     for (const interaction of interactions) {
+        const requestId = randomUUID();
         internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'loading' });
-        gen(interaction).then((r) => {
-            if (!internals.mounted)
+        let handle;
+        try {
+            handle = provider({ requestId, generationId, interaction: visualRequestInteraction(interaction) });
+        }
+        catch {
+            internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'error' });
+            continue;
+        }
+        internals.visualHandles.set(requestId, handle);
+        handle.result.then((result) => {
+            if (internals.visualHandles.get(requestId) !== handle)
+                return;
+            internals.visualHandles.delete(requestId);
+            if (!internals.mounted || generation !== internals.visualGeneration)
                 return;
-            if (!internals.state.interactions.some((x) => x.id === interaction.id))
+            if (!internals.state.interactions.some((candidate) => candidate.id === interaction.id))
                 return;
-            internals.state.visuals.set(interaction.id, r.ok
-                ? { questionId: interaction.id, content: r.ansi, status: 'ready' }
+            internals.state.visuals.set(interaction.id, result.status === 'ready' && typeof result.markdown === 'string'
+                ? { questionId: interaction.id, content: renderVisualMarkdown(result.markdown, internals.cols), markdown: result.markdown, status: 'ready' }
                 : { questionId: interaction.id, content: '', status: 'error' });
             internals.callbacks.onDirty?.();
         }).catch(() => {
-            if (!internals.mounted)
+            if (internals.visualHandles.get(requestId) !== handle)
                 return;
-            if (!internals.state.interactions.some((x) => x.id === interaction.id))
+            internals.visualHandles.delete(requestId);
+            if (!internals.mounted || generation !== internals.visualGeneration)
+                return;
+            if (!internals.state.interactions.some((candidate) => candidate.id === interaction.id))
                 return;
             internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'error' });
             internals.callbacks.onDirty?.();
@@ -130,14 +180,24 @@ function fireVisuals(internals, interactions) {
     }
 }
 export function mountPanel(opts) {
+    const followUpAvailable = opts.followUpAvailable !== false
+        && opts.onFollowUpRequest !== undefined
+        && opts.onFollowUpCancel !== undefined;
     const internals = {
-        state: buildInitialState(opts.deck),
+        state: buildInitialState(opts.deck, opts.onEditorRequest !== undefined, followUpAvailable),
         cols: opts.cols,
         rows: opts.rows,
         mounted: true,
-        generateVisual: opts.generateVisual,
+        visualProvider: opts.visualProvider,
+        visualGeneration: 0,
+        visualHandles: new Map(),
         progressPath: opts.progressPath,
-        callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit, onDirty: opts.onDirty },
+        followUpAvailable,
+        callbacks: {
+            onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit,
+            onDirty: opts.onDirty, onEditorRequest: opts.onEditorRequest,
+            onFollowUpRequest: opts.onFollowUpRequest, onFollowUpCancel: opts.onFollowUpCancel,
+        },
     };
     assignShortcuts(internals.state.interactions);
     rebindPersist(internals);
@@ -156,6 +216,10 @@ export function mountPanel(opts) {
         handleKey(input, key) {
             if (!internals.mounted)
                 return;
+            if (key.ctrl && input === 'o' && internals.state.inputMode !== null && internals.callbacks.onEditorRequest !== undefined) {
+                internals.callbacks.onEditorRequest();
+                return;
+            }
             const onAutoComplete = () => {
                 const responses = collectResponses(internals.state);
                 if (internals.progressPath !== undefined) {
@@ -174,6 +238,9 @@ export function mountPanel(opts) {
                 else {
                     internals.callbacks.onExit?.();
                 }
+            }, {
+                request: (question) => internals.callbacks.onFollowUpRequest?.(question),
+                cancel: () => internals.callbacks.onFollowUpCancel?.(),
             });
             // Pre-render clamp (input layer): keep scrollOffset within the current
             // body's bounds so u/d stay responsive. The renderer itself is pure.
@@ -189,22 +256,31 @@ export function mountPanel(opts) {
         handleResize(cols, rows) {
             internals.cols = cols;
             internals.rows = rows;
-            // New dimensions change the scroll bounds — re-clamp before laying out.
+            // Width changes reflow saved visual markdown, so clamp against the new
+            // content and geometry rather than the stale pre-resize wrapping.
+            rerenderVisuals(internals);
             if (internals.state.phase === 'item-review') {
                 clampItemReviewScroll(internals.state, cols, rows);
             }
             return renderLines();
         },
         unmount() {
+            if (!internals.mounted)
+                return;
             internals.mounted = false;
-            internals.state.visuals.clear();
+            retireVisuals(internals);
             internals.state.persist = undefined;
         },
         loadDeck(deck, loadOpts) {
             if (!internals.mounted)
                 return;
             const prior = collectResponses(internals.state);
-            internals.state = buildInitialState(deck);
+            // Retire before replacing capability: old handles become non-current,
+            // then the next generation uses only the freshly derived provider.
+            retireVisuals(internals);
+            if (loadOpts !== undefined && 'visualProvider' in loadOpts)
+                internals.visualProvider = loadOpts.visualProvider;
+            internals.state = buildInitialState(deck, internals.callbacks.onEditorRequest !== undefined, internals.followUpAvailable);
             if (loadOpts !== undefined && loadOpts.progressPath !== undefined) {
                 internals.progressPath = loadOpts.progressPath;
             }
@@ -227,6 +303,25 @@ export function mountPanel(opts) {
             }
             fireVisuals(internals, deck.interactions);
         },
+        setFollowUpHandlers(available, onRequest, onCancel) {
+            if (!internals.mounted)
+                return;
+            internals.callbacks.onFollowUpRequest = onRequest;
+            internals.callbacks.onFollowUpCancel = onCancel;
+            const enabled = available && onRequest !== undefined && onCancel !== undefined;
+            internals.followUpAvailable = enabled;
+            internals.state.followUpAvailable = enabled;
+            if (!enabled) {
+                internals.state.followUp = undefined;
+                if (internals.state.inputMode?.kind === 'follow-up')
+                    internals.state.inputMode = null;
+            }
+        },
+        setFollowUpState(state) {
+            if (!internals.mounted || !internals.state.followUpAvailable)
+                return;
+            internals.state.followUp = state;
+        },
         canAcceptHostKeys() {
             if (!internals.mounted)
                 return false;
@@ -264,24 +359,10 @@ export function mountPanel(opts) {
  * returned `deck` is the one actually answered (post-reload).
  */
 export async function resolveInteractionDir(dir, deck, opts = {}) {
-    let conversationContext = '';
-    if (opts.sessionId !== undefined) {
-        try {
-            const conv = readConversation(opts.sessionId);
-            conversationContext = conv.map((m) => `${m.role}: ${m.content}`).join('\n\n');
-        }
-        catch {
-            // empty context — proceed without visuals context
-        }
-    }
     setupTerminal();
     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 = [];
@@ -368,7 +449,12 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             progressPath: progressPathFor(dir),
             cols,
             rows,
-            generateVisual,
+            visualProvider: opts.visualProvider,
+            onEditorRequest: () => {
+                const buffer = panel?.getInputBuffer();
+                if (buffer !== undefined)
+                    runEditorEscapeHatch(buffer);
+            },
             onProgress: (responses) => {
                 lastResponses = responses;
                 if (panel !== null)
@@ -444,68 +530,22 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
                 return;
             process.stdin.removeListener('data', onData);
             process.stdout.removeListener('resize', onResize);
-            const tmpFile = join(tmpdir(), `hl-input-${randomUUID()}.txt`);
-            const editor = process.env.EDITOR || 'vi';
-            let next = buffer;
-            let errorMessage = null;
-            // Everything from suspending the TUI through the editor round-trip can
-            // throw (tmpfile write, spawn, readback) — a tmpdir write failure alone
-            // (e.g. /tmp full) used to escape with the listeners detached and the
-            // real terminal never restored. The try/finally below guarantees the
-            // finally branch — tmpfile cleanup, TUI restore, listener re-attach,
-            // resize-aware redraw — runs on every path, success or failure.
+            let result = { text: buffer };
             try {
                 restoreTerminal();
-                writeFileSync(tmpFile, buffer);
-                // $EDITOR is conventionally a shell fragment, not a bare binary —
-                // "code --wait", "emacsclient -t" — so run it through the shell (as
-                // git does) with the filename passed safely as a positional arg.
-                const result = spawnSync('/bin/sh', ['-c', `${editor} "$1"`, 'sh', tmpFile], { stdio: 'inherit' });
-                if (result.error) {
-                    errorMessage = `$EDITOR ("${editor}") failed to launch: ${result.error.message}`;
-                }
-                else if (result.signal !== null) {
-                    errorMessage = `$EDITOR ("${editor}") was killed by signal ${result.signal}`;
-                }
-                else if (result.status === 127 || result.status === 126) {
-                    // Shell couldn't exec the editor: 127 = not found, 126 = not executable.
-                    errorMessage = `$EDITOR ("${editor}") failed to launch (shell exit ${result.status})`;
-                }
-                else if (result.status !== 0) {
-                    errorMessage = `$EDITOR ("${editor}") exited with status ${result.status}`;
-                }
-                else {
-                    let read = readFileSync(tmpFile, 'utf8');
-                    // Editors conventionally append a trailing newline on save; strip
-                    // exactly one so a round-trip that added nothing doesn't grow the
-                    // buffer by a blank line.
-                    if (read.endsWith('\n') && !buffer.endsWith('\n'))
-                        read = read.slice(0, -1);
-                    next = read;
-                }
-            }
-            catch (err) {
-                errorMessage = `$EDITOR round-trip failed: ${err instanceof Error ? err.message : String(err)}`;
+                result = editBufferInEditor(buffer);
             }
             finally {
-                try {
-                    unlinkSync(tmpFile);
-                }
-                catch { /* best-effort cleanup — may never have been created */ }
                 setupTerminal();
                 process.stdin.on('data', onData);
                 process.stdout.on('resize', onResize);
-                // On any failure the original buffer is kept untouched. Re-sample the
-                // terminal size (it may have changed while the editor had it) so the
-                // post-editor redraw lays out for the CURRENT dimensions rather than
-                // the panel's stale cols/rows, same as the live resize listener does.
-                panel.setInputBuffer(errorMessage === null ? next : buffer);
+                panel.setInputBuffer(result.text);
                 const { cols: c, rows: r } = getTerminalSize();
                 const lines = panel.handleResize(c, r);
-                if (errorMessage !== null) {
+                if (result.error !== undefined) {
                     while (lines.length < r)
                         lines.push('');
-                    lines[r - 1] = `  ${errorMessage}`.slice(0, c);
+                    lines[r - 1] = `  ${result.error}`.slice(0, c);
                 }
                 prevFrameLocal = [];
                 process.stdout.write('\x1b[2J\x1b[H');
@@ -583,13 +623,6 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
                 }
                 return;
             }
-            if (key.ctrl && inp === 'o') {
-                const buf = panel.getInputBuffer();
-                if (buf !== undefined) {
-                    runEditorEscapeHatch(buf);
-                    return;
-                }
-            }
             // 'w' hands the current interaction off to the browser. Gated on
             // canAcceptHostKeys() (not mid comment/freetext) so it never shadows a
             // literal 'w' typed into a buffer; 'w' is also reserved from option
@@ -607,7 +640,7 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
 }
 // ── 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) {
+export async function launchTui(decisionsPath, opts = {}) {
     if (!existsSync(decisionsPath)) {
         throw new Error(`Decisions file not found: ${decisionsPath}`);
     }
@@ -616,6 +649,6 @@ export async function launchTui(decisionsPath, sessionId) {
     // 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 });
+    const { responses, completedAt } = await resolveInteractionDir(dir, deck, opts);
     return { responses, completedAt };
 }

package/dist/tui/input.d.ts

@@ -2,5 +2,9 @@ import type { TuiState, Interaction } from '../types.js';
 import type { Key } from './terminal.js';
 export type RenderFn = () => void;
 export type ExitFn = () => void;
+export interface FollowUpActions {
+    request(question: string): void;
+    cancel(): void;
+}
 export declare function assignShortcuts(interactions: Interaction[]): void;
-export declare function handleKeypress(input: string, key: Key, state: TuiState, render: RenderFn, exit: ExitFn): void;
+export declare function handleKeypress(input: string, key: Key, state: TuiState, render: RenderFn, exit: ExitFn, followUp?: FollowUpActions): void;

package/dist/tui/input.js

@@ -1,7 +1,7 @@
 // 'w' is reserved for the host-level "open in browser" handoff (see
 // tui/app.ts resolveInteractionDir) — never auto-assignable as an option
 // shortcut, or pressing it would race the handoff against picking that option.
-const RESERVED = new Set(['c', 'r', 'n', 'p', 'q', 'j', 'k', 'u', 'd', 'w', ' ']);
+const RESERVED = new Set(['c', 'r', 'n', 'p', 'q', 'j', 'k', 'u', 'd', 'w', ' ', '?']);
 export function assignShortcuts(interactions) {
     for (const it of interactions) {
         const used = new Set(it.options.map((o) => o.shortcut).filter((s) => s !== undefined));
@@ -32,7 +32,14 @@ export function assignShortcuts(interactions) {
         }
     }
 }
-export function handleKeypress(input, key, state, render, exit) {
+export function handleKeypress(input, key, state, render, exit, followUp) {
+    if (key.backTab) {
+        state.bodyScrollOffsets[state.bodyMode] = state.scrollOffset;
+        state.bodyMode = state.bodyMode === 'question' ? 'visual' : 'question';
+        state.scrollOffset = state.bodyScrollOffsets[state.bodyMode];
+        render();
+        return;
+    }
     if (key.ctrl && input === 'c') {
         exit();
         return;
@@ -42,7 +49,7 @@ export function handleKeypress(input, key, state, render, exit) {
     // render cycle.
     state.hint = undefined;
     if (state.inputMode) {
-        handleInputMode(input, key, state, render);
+        handleInputMode(input, key, state, render, followUp);
         checkAutoExit(state, exit);
         return;
     }
@@ -51,7 +58,7 @@ export function handleKeypress(input, key, state, render, exit) {
             handleOverview(input, key, state, render, exit);
             break;
         case 'item-review':
-            handleItemReview(input, key, state, render);
+            handleItemReview(input, key, state, render, followUp);
             checkAutoExit(state, exit);
             break;
         case 'final':
@@ -91,7 +98,8 @@ function handleOverview(input, key, state, render, exit) {
     if (key.return || input === ' ') {
         state.phase = 'item-review';
         state.selectedAction = 0;
-        state.detailExpanded = false;
+        state.bodyMode = 'question';
+        state.scrollOffset = state.bodyScrollOffsets.question;
         render();
         return;
     }
@@ -124,7 +132,15 @@ function handleOverview(input, key, state, render, exit) {
     }
 }
 // ── Item Review ──────────────────────────────────────────────────────────────
-function handleItemReview(input, key, state, render) {
+function handleItemReview(input, key, state, render, followUp) {
+    if (input === '?' && state.followUpAvailable) {
+        if (state.followUp?.status === 'running')
+            followUp?.cancel();
+        else
+            state.inputMode = { kind: 'follow-up', buffer: '', cursor: 0 };
+        render();
+        return;
+    }
     const interaction = state.interactions[state.currentIndex];
     if (input === 'n') {
         advanceItem(state, 1);
@@ -138,22 +154,18 @@ function handleItemReview(input, key, state, render) {
     }
     // q / Esc step back to the deck overview (one level up from a card).
     if (input === 'q' || key.escape) {
+        state.bodyScrollOffsets[state.bodyMode] = state.scrollOffset;
         state.phase = 'overview';
         render();
         return;
     }
-    // Space toggles the focused option for multi-select; otherwise expand context.
+    // Space toggles the focused option for multi-select.
     if (input === ' ' && interaction.multiSelect
         && state.selectedAction < interaction.options.length) {
         toggleMulti(state, interaction, interaction.options[state.selectedAction].id);
         render();
         return;
     }
-    if (input === ' ') {
-        state.detailExpanded = !state.detailExpanded;
-        render();
-        return;
-    }
     // Body scroll: u/d, PageUp/PageDown, or Ctrl+D / Ctrl+U (half-page), Ctrl+E / Ctrl+Y (line).
     // Plain u/d exists because tmux configs commonly bind C-d/C-u for pane scroll
     // and intercept them before they reach the app. Render clamps state.scrollOffset,
@@ -273,8 +285,20 @@ function handleInteractionAction(input, key, state, interaction, render) {
     }
 }
 // ── Input Mode ───────────────────────────────────────────────────────────────
-function handleInputMode(input, key, state, render) {
+function handleInputMode(input, key, state, render, followUp) {
     const mode = state.inputMode;
+    if (mode.kind === 'follow-up' && key.return) {
+        const question = mode.buffer.trim();
+        if (question.length === 0) {
+            state.hint = 'Enter a question, or esc to cancel';
+            render();
+            return;
+        }
+        followUp?.request(question);
+        state.inputMode = null;
+        render();
+        return;
+    }
     if (key.escape) {
         state.inputMode = null;
         render();
@@ -549,8 +573,9 @@ function advanceItem(state, direction) {
     }
     state.currentIndex = next;
     state.selectedAction = 0;
-    state.detailExpanded = false;
+    state.bodyMode = 'question';
     state.scrollOffset = 0;
+    state.bodyScrollOffsets = { question: 0, visual: 0 };
 }
 /**
  * Move to the next interaction WITHOUT a response, falling through to the
@@ -570,8 +595,9 @@ function advanceToNextUnanswered(state) {
     }
     state.currentIndex = next;
     state.selectedAction = 0;
-    state.detailExpanded = false;
+    state.bodyMode = 'question';
     state.scrollOffset = 0;
+    state.bodyScrollOffsets = { question: 0, visual: 0 };
 }
 function actionCount(interaction) {
     return interaction.options.length + (interaction.allowFreetext && interaction.options.length > 0 ? 1 : 0);

package/dist/tui/log.d.ts

@@ -0,0 +1,2 @@
+export declare function popupLogPath(): string;
+export declare function logPopupEvent(event: string, fields?: Record<string, unknown>): void;

package/dist/tui/log.js

@@ -0,0 +1,53 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const MAX_BYTES = 5 * 1024 * 1024;
+const ROTATIONS = 2;
+function stateHome() {
+    return process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
+}
+export function popupLogPath() {
+    return join(stateHome(), 'humanloop', 'inbox-popup.log');
+}
+function rotateIfNeeded(path, nextLineBytes) {
+    if (!existsSync(path))
+        return;
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size + nextLineBytes < MAX_BYTES)
+        return;
+    try {
+        rmSync(`${path}.${ROTATIONS}`, { force: true });
+    }
+    catch { /* best-effort */ }
+    for (let index = ROTATIONS - 1; index >= 1; index -= 1) {
+        const source = `${path}.${index}`;
+        const target = `${path}.${index + 1}`;
+        try {
+            if (existsSync(source))
+                renameSync(source, target);
+        }
+        catch { /* best-effort */ }
+    }
+    try {
+        renameSync(path, `${path}.1`);
+    }
+    catch { /* best-effort */ }
+}
+export function logPopupEvent(event, fields = {}) {
+    const path = popupLogPath();
+    const line = JSON.stringify({ ts: new Date().toISOString(), component: 'inbox-popup', event, ...fields });
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        rotateIfNeeded(path, Buffer.byteLength(`${line}\n`, 'utf8'));
+        appendFileSync(path, `${line}\n`, 'utf8');
+    }
+    catch {
+        /* Logging is best-effort so the inbox shortcut remains available. */
+    }
+}