@crouton-kit/humanloop 0.3.39 → 0.4.1

package/dist/api.d.ts

@@ -1,8 +1,8 @@
-import type { Deck, ResolutionEnvelope } from './types.js';
+import type { Deck, ResolutionEnvelope, VisualProvider } from './types.js';
 export interface AskOpts {
     /** Interaction directory. Defaults to a managed temp dir under os.tmpdir(). */
     dir?: string;
-    sessionId?: string;
+    visualProvider?: VisualProvider;
     cols?: number;
     rows?: number;
 }
@@ -18,6 +18,7 @@ export interface InboxOpts {
     cols?: number;
     rows?: number;
     roots?: string[];
+    visualProvider?: VisualProvider;
 }
 /** Open the centralized inbox controller in the current human terminal. */
 export declare function openInbox(opts?: InboxOpts): Promise<void>;

package/dist/api.js

@@ -27,7 +27,7 @@ export async function ask(deck, opts = {}) {
     stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {
-        sessionId: opts.sessionId,
+        visualProvider: opts.visualProvider,
         cols: opts.cols,
         rows: opts.rows,
     });
@@ -48,6 +48,6 @@ export async function notify(title, body) {
 }
 /** Open the centralized inbox controller in the current human terminal. */
 export async function openInbox(opts = {}) {
-    const controller = new InboxController({ roots: opts.roots, cols: opts.cols, rows: opts.rows });
+    const controller = new InboxController({ roots: opts.roots, cols: opts.cols, rows: opts.rows, visualProvider: opts.visualProvider });
     await controller.run();
 }

package/dist/cli.js

@@ -7,6 +7,7 @@ import { validateDeck } from './inbox/deck-schema.js';
 import { managedInboxRoot, registerInboxRoot, registeredInboxRoot, unregisterInboxRoot, listInboxRoots } from './inbox/registry.js';
 import { submitDeck, submitReview } from './inbox/tickets.js';
 import { scanInbox } from './inbox/scan.js';
+import { runInboxMaintenance } from './inbox/maintenance.js';
 import { openInboxPopup } from './surfaces/inbox-popup.js';
 import { toggleInboxPopup } from './tui/tmux.js';
 import { ask } from './api.js';
@@ -47,11 +48,11 @@ function requireRegisteredRoot(root) {
 const program = new Command();
 program.name('hl').description('Humanloop durable inbox and review surface.').helpOption('-h, --help');
 const inbox = program.command('inbox').description('Open, inspect, and configure the centralized human inbox.');
-inbox.command('open').description('Open the inbox controller in this human TTY.').option('--root <path>', 'filter to a registered root', (value, prior) => [...prior, value], []).option('--control-socket <path>', 'popup control socket').action(async (options) => {
+inbox.command('open').description('Open the inbox controller in this human TTY.').option('--root <path>', 'filter to a registered root', (value, prior) => [...prior, value], []).option('--control-socket <path>', 'popup control socket').option('--target-pane <pane>', 'tmux pane underneath the popup').action(async (options) => {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         fail('hl inbox open requires an interactive TTY; use hl inbox list for read-only output');
     try {
-        await openInboxPopup(options.controlSocket, roots(options.root));
+        await openInboxPopup(options.controlSocket, roots(options.root), options.targetPane);
     }
     catch (error) {
         fail(error);
@@ -73,6 +74,9 @@ inbox.command('toggle').description('Toggle the inbox popup for one tmux client.
     process.exit(result === 'failed' || result === 'ambiguous_client' ? 1 : 0);
 });
 inbox.command('list').description('Print pending tickets newest first as JSON.').option('--root <path>', 'filter to a root', (value, prior) => [...prior, value], []).action((options) => emit(scanInbox(roots(options.root))));
+inbox.command('_maintain', { hidden: true }).requiredOption('--lease <path>').action(async (options) => {
+    await runInboxMaintenance(resolve(options.lease));
+});
 const root = inbox.command('roots').description('Manage durable interaction roots.');
 root.command('register').description('Register a root owned by a host.').requiredOption('--root <path>').requiredOption('--owner <owner>').option('--handler-command <path>').option('--handler-arg <arg>', 'repeatable direct-exec handler argument', (value, prior) => [...prior, value], []).action((options) => {
     if ((options.handlerCommand === undefined) !== (options.handlerArg.length === 0))

package/dist/inbox/controller.d.ts

@@ -1,7 +1,6 @@
-import type { InteractionResponse, TicketSummary } from '../types.js';
+import type { InteractionResponse, TicketSummary, VisualProvider } from '../types.js';
 import type { Key } from '../tui/terminal.js';
 import { startWebServer } from '../browser/server.js';
-import { visualGeneratorForConversationSession } from '../visuals/conversation.js';
 export interface InboxControllerOptions {
     roots?: string[];
     cols?: number;
@@ -10,8 +9,10 @@ export interface InboxControllerOptions {
     completeDeck?: (dir: string, responses: InteractionResponse[], token: string) => Promise<unknown>;
     startDeckBrowser?: typeof startWebServer;
     openBrowser?: (url: string) => void;
-    /** Test seam; production uses the standard conversation-backed visual generator. */
-    visualGeneratorForSession?: typeof visualGeneratorForConversationSession;
+    visualProvider?: VisualProvider;
+    /** Pane underneath a tmux popup. Enables a registered focus handler to
+     * reveal the host surface that created the selected ticket. */
+    targetPane?: string;
 }
 type Screen = 'list' | 'detail';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
@@ -35,10 +36,10 @@ export declare class InboxController {
     private deckBrowserFinalizing;
     private deckBrowserStarting;
     private deckBrowserStartingGeneration;
+    private focusingSource;
     /** Invalidates an in-flight asynchronous browser start when ownership ends. */
     private deckBrowserGeneration;
     private claim;
-    private reconciling;
     private suspended;
     private submittingDir;
     private stdinListener;
@@ -91,14 +92,19 @@ export declare class InboxController {
     /** Retake the TTY after the child exits and force a full repaint. */
     private resumeAfterChild;
     private resolvedRoots;
-    /** Owner-boundary reconciliation for resolved results still lacking an ack.
-     *  Guarded so overlapping fs events cannot stack concurrent scans. */
-    private reconcileRoots;
+    /** Automatic ticket capability is deliberately marker + current-root-handler only. */
+    private visualProviderFor;
+    private startTicketVisual;
     private leaveDetail;
     private select;
     private scrollPreview;
     private detailSize;
     private detailLines;
+    private focusAvailable;
+    /** Ask the registered host to reveal this ticket's source beside the pane
+     * underneath the popup. The popup closes only after the host acknowledges
+     * that focus succeeded, so a failure remains visible as status. */
+    private focusSelectedSource;
     private passiveDetailLines;
     private previewViewport;
     private withStatus;

package/dist/inbox/controller.js

@@ -1,4 +1,5 @@
 import { readFileSync, watch } from 'node:fs';
+import { basename, join } from 'node:path';
 import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
 import { diffFrame } from '../tui/render.js';
 import { renderMarkdown } from '../render/termrender.js';
@@ -9,17 +10,17 @@ import { BOLD, CYAN, DIM, GRAY, RESET, YELLOW, clipLine } from '../tui/ansi.js';
 import { buildInboxLines } from './tui.js';
 import { inboxLayout } from './layout.js';
 import { scanInbox } from './scan.js';
-import { inboxRootsDirectory, listInboxRoots, registeredInboxRoot } from './registry.js';
+import { inboxActivityPath, inboxRootsDirectory, inboxStateDirectory, listInboxRoots, registeredInboxRoot } from './registry.js';
 import { claimTicket, heartbeatClaim, releaseClaim } from './claim.js';
 import { completeDeck, readTicketResult, ticketRoot } from './tickets.js';
-import { reconcileCompletions } from './completion.js';
-import { clearProgress, deckPath, progressPath, readJson, responsePath, reviewPath } from './convention.js';
+import { clearProgress, deckPath, progressPath, readJson, responsePath, reviewPath, runHandler, visualsDir } from './convention.js';
 import { DeckAdapter } from './deck-adapter.js';
 import { validateDeck } from './deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
-import { visualGeneratorForConversationSession } from '../visuals/conversation.js';
 import { editBufferInEditor } from '../editor/roundtrip.js';
 import { cancelFollowUp, readFollowUp, requestFollowUp } from './followup.js';
+import { cancelVisualRequest, readVisualResult, reconcileVisualRequestsForTicket, startVisualRequest, VISUAL_CAPABILITY, } from './visual.js';
+import { kickInboxMaintenance } from './maintenance.js';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
 export class InboxController {
     options;
@@ -41,10 +42,10 @@ export class InboxController {
     deckBrowserFinalizing;
     deckBrowserStarting = false;
     deckBrowserStartingGeneration;
+    focusingSource = false;
     /** Invalidates an in-flight asynchronous browser start when ownership ends. */
     deckBrowserGeneration = 0;
     claim;
-    reconciling = false;
     suspended = false;
     submittingDir;
     stdinListener;
@@ -153,6 +154,10 @@ export class InboxController {
             return;
         }
         if (this.screen === 'detail' && this.adapter !== undefined) {
+            if ((input === 'g' || input === 'G') && this.adapter.canAcceptHostKeys()) {
+                void this.focusSelectedSource();
+                return;
+            }
             if ((input === 'w' || input === 'W') && this.adapter.canAcceptHostKeys()) {
                 void this.openDeckBrowser();
                 return;
@@ -176,6 +181,8 @@ export class InboxController {
             this.select(this.selectedIndex + 1);
         else if (input === 'k' || key.upArrow)
             this.select(this.selectedIndex - 1);
+        else if (input === 'g' || input === 'G')
+            void this.focusSelectedSource();
         else if (key.return || input === 'a')
             this.activate();
         this.repaint();
@@ -196,13 +203,20 @@ export class InboxController {
             return;
         }
         this.claim = { dir: item.dir, token: claim.token };
-        const deck = readJson(deckPath(item.dir));
-        if (deck === null) {
+        const deck = this.readDeck(item.dir);
+        if (deck === undefined) {
             releaseClaim(item.dir, claim.token);
             this.claim = undefined;
             this.invalidate();
             return;
         }
+        const root = ticketRoot(item.dir);
+        if (root !== null) {
+            // A newly acquired claim makes every older running generation stale
+            // before the panel can mint its own work. This only dispatches cleanup.
+            const retirement = reconcileVisualRequestsForTicket(root, item.dir, claim.token);
+            void retirement.delivery.finally(kickInboxMaintenance);
+        }
         // Notifications use the same canonical deck panel as every other deck:
         // opening is not acknowledgement; panel completion is.
         this.activeDeck = deck;
@@ -214,7 +228,7 @@ export class InboxController {
             cols: this.detailSize().cols,
             rows: this.detailSize().rows,
             onDirty: () => this.repaint(),
-            generateVisual: deck.source?.originatingConversationSessionId === undefined ? undefined : (this.options.visualGeneratorForSession ?? visualGeneratorForConversationSession)(deck.source.originatingConversationSessionId),
+            visualProvider: this.visualProviderFor(item.dir, deck, claim.token),
             onEditorRequest: () => this.editActiveDeckInput(),
             followUpAvailable: followUp.available,
             onFollowUpRequest: followUp.onRequest,
@@ -264,7 +278,6 @@ export class InboxController {
             else {
                 this.resumeAfterChild();
                 this.rescan();
-                this.reconcileRoots();
                 this.repaint(true);
             }
         }
@@ -282,7 +295,8 @@ export class InboxController {
         this.activeDeck = deck;
         const followUp = this.followUpHandlers(this.claim.dir, deck);
         this.adapter.setFollowUpHandlers(followUp.available, followUp.onRequest, followUp.onCancel);
-        this.adapter.reload(deck);
+        // Reload replaces the capability before it mints the next panel generation.
+        this.adapter.reload(deck, this.visualProviderFor(this.claim.dir, deck, this.claim.token));
         if (followUp.available)
             this.adapter.setFollowUpState(this.followUpViewState(this.claim.dir));
         this.repaint();
@@ -418,7 +432,6 @@ export class InboxController {
         if (this.claim?.dir === dir)
             this.leaveDetail();
         this.rescan();
-        this.reconcileRoots();
         this.repaint();
     }
     /** Return browser authority to the terminal deck without changing its draft. */
@@ -473,10 +486,9 @@ export class InboxController {
         setupTerminal();
         this.running = true;
         this.watchRoots();
-        // Close the crash window between an earlier result publication and its
-        // handler launch: dispatch every resolved-but-undelivered ticket now.
-        this.reconcileRoots();
         this.repaint(true);
+        // Crash repair is durable but never part of a human keystroke.
+        kickInboxMaintenance();
         const heartbeat = setInterval(() => {
             if (this.claim !== undefined)
                 heartbeatClaim(this.claim.dir, this.claim.token);
@@ -525,7 +537,6 @@ export class InboxController {
         this.submittingDir = undefined;
         this.leaveDetail(false);
         this.rescan();
-        this.reconcileRoots();
         this.repaint();
     }
     /** The controller owns the terminal handoff and repaint around $EDITOR. */
@@ -567,26 +578,71 @@ export class InboxController {
     resolvedRoots() {
         return this.options.roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
     }
-    /** Owner-boundary reconciliation for resolved results still lacking an ack.
-     *  Guarded so overlapping fs events cannot stack concurrent scans. */
-    reconcileRoots() {
-        if (this.reconciling)
-            return;
-        this.reconciling = true;
-        const roots = this.resolvedRoots();
-        void (async () => {
+    /** Automatic ticket capability is deliberately marker + current-root-handler only. */
+    visualProviderFor(dir, deck, claimToken) {
+        // An inline provider is intentional host injection, independent of ticket capability.
+        if (this.options.visualProvider !== undefined)
+            return this.options.visualProvider;
+        const root = ticketRoot(dir);
+        if (root === null || deck.source?.visual !== VISUAL_CAPABILITY || registeredInboxRoot(root)?.visualHandler === undefined)
+            return undefined;
+        return (request) => this.startTicketVisual(root, dir, claimToken, request);
+    }
+    startTicketVisual(root, dir, claimToken, request) {
+        let watcher;
+        let settled = false;
+        let settle;
+        const result = new Promise((resolve) => { settle = resolve; });
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            watcher?.close();
+            watcher = undefined;
+            settle(outcome);
+        };
+        let started;
+        try {
+            started = startVisualRequest({ root, dir, claimToken, request });
+        }
+        catch (error) {
+            finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+            return { result, cancel: () => { } };
+        }
+        const reread = () => {
+            if (settled)
+                return;
             try {
-                for (const root of roots) {
-                    try {
-                        await reconcileCompletions(root);
-                    }
-                    catch { /* undelivered stays for the next pass */ }
-                }
+                const outcome = readVisualResult(root, dir, request.requestId);
+                if (outcome === null)
+                    return;
+                finish(outcome.status === 'ready'
+                    ? { status: 'ready', markdown: outcome.markdown }
+                    : { status: 'error', error: outcome.error });
             }
-            finally {
-                this.reconciling = false;
+            catch (error) {
+                finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
             }
-        })();
+        };
+        try {
+            // Install the watch before the first durable reread so a publication in
+            // the narrow setup window is either observed or found by that reread.
+            watcher = watch(join(visualsDir(dir), request.requestId), () => reread());
+            watcher.once('error', (error) => finish({ status: 'error', error: error.message }));
+            reread();
+        }
+        catch (error) {
+            finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+        }
+        void started.delivery.then(reread, (error) => finish({ status: 'error', error: error instanceof Error ? error.message : String(error) }));
+        return {
+            result,
+            cancel: () => {
+                watcher?.close();
+                watcher = undefined;
+                void cancelVisualRequest(root, dir, request.requestId).finally(kickInboxMaintenance);
+            },
+        };
     }
     leaveDetail(release = true) {
         this.deckBrowserGeneration++;
@@ -629,11 +685,42 @@ export class InboxController {
         const selected = this.items[this.selectedIndex];
         if (selected === undefined)
             return this.previewViewport(this.passiveDetailLines(width), width, rows);
+        const focusHint = this.focusAvailable(selected.dir) ? `  ${DIM}g${RESET} chat` : '';
         const footer = selected.kind === 'deck'
-            ? [`  ${DIM}Enter${RESET} opens the full ticket  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}Active ask:${RESET} c comment  u/d scroll  w browser  ${DIM}q${RESET} close`]
-            : [`  ${DIM}Enter${RESET} opens the full review  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}q${RESET} close`];
+            ? [`  ${DIM}Enter${RESET} opens the full ticket  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}Active ask:${RESET} c comment  u/d scroll  w browser${focusHint}  ${DIM}q${RESET} close`]
+            : [`  ${DIM}Enter${RESET} opens the full review  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, ` ${focusHint}  ${DIM}q${RESET} close`];
         return [...this.previewViewport(this.passiveDetailLines(width), width, Math.max(0, rows - footer.length)), ...footer.map((line) => clipLine(line, width))];
     }
+    focusAvailable(dir) {
+        const root = ticketRoot(dir);
+        return this.options.targetPane !== undefined && root !== null && registeredInboxRoot(root)?.focusHandler !== undefined;
+    }
+    /** Ask the registered host to reveal this ticket's source beside the pane
+     * underneath the popup. The popup closes only after the host acknowledges
+     * that focus succeeded, so a failure remains visible as status. */
+    async focusSelectedSource() {
+        const item = this.items[this.selectedIndex];
+        const targetPane = this.options.targetPane;
+        if (item === undefined || targetPane === undefined || this.focusingSource)
+            return;
+        const root = ticketRoot(item.dir);
+        const registration = root === null ? null : registeredInboxRoot(root);
+        if (root === null || registration?.focusHandler === undefined)
+            return;
+        const event = { schema: 'humanloop.focus/v1', root, dir: item.dir, ticketId: item.id, targetPane };
+        this.focusingSource = true;
+        try {
+            await runHandler(registration.focusHandler.command, registration.focusHandler.args, event);
+            this.close();
+        }
+        catch (error) {
+            this.status = error instanceof Error ? error.message : String(error);
+            this.repaint();
+        }
+        finally {
+            this.focusingSource = false;
+        }
+    }
     passiveDetailLines(width) {
         const selected = this.items[this.selectedIndex];
         if (selected === undefined)
@@ -727,15 +814,21 @@ export class InboxController {
         this.frame = diff.nextPrevFrame;
     }
     watchRoots() {
-        for (const root of this.resolvedRoots()) {
-            try {
-                this.watchers.push(watch(root, () => { this.invalidate(); this.reconcileRoots(); }));
-            }
-            catch { /* unavailable roots remain discoverable through later rescans */ }
+        // A single state-level activity marker replaces one watcher per historical
+        // root. Closing hundreds of fs watchers was itself a multi-second UI path.
+        const activity = basename(inboxActivityPath());
+        try {
+            this.watchers.push(watch(inboxStateDirectory(), (_event, file) => {
+                if (String(file) === activity) {
+                    this.invalidate();
+                    kickInboxMaintenance();
+                }
+            }));
         }
+        catch { /* the state directory appears when the next ticket is submitted */ }
         if (this.options.roots === undefined) {
             try {
-                this.watchers.push(watch(inboxRootsDirectory(), () => this.invalidate()));
+                this.watchers.push(watch(inboxRootsDirectory(), () => { this.invalidate(); kickInboxMaintenance(); }));
             }
             catch { /* registry appears after the next explicit open */ }
         }

package/dist/inbox/convention.d.ts

@@ -9,8 +9,6 @@ export declare function deliveryErrorPath(dir: string): string;
 export declare function followupRequestPath(dir: string): string;
 export declare function followupResultPath(dir: string): string;
 export declare function visualsDir(dir: string): string;
-export declare function visualMdPath(dir: string, id: string): string;
-export declare function visualAnsiPath(dir: string, id: string): string;
 /** Spawns a handler `{command,args}` with `event` as JSON on stdin. Exit 0
  *  acknowledges; a nonzero exit, spawn error, or 30s timeout rejects with an
  *  Error carrying the handler's captured stderr. Shared by completion delivery
@@ -22,6 +20,8 @@ export declare function isResolved(dir: string): boolean;
 export declare function isClaimed(dir: string): boolean;
 export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
+/** Publish one immutable JSON record without replacing an existing winner. */
+export declare function publishJsonExclusive(path: string, value: unknown): boolean;
 export declare function readJson<T>(path: string): T | null;
 /** Runs a short filesystem transition under a token-checked, crash-reclaimable directory lock. */
 export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: {

package/dist/inbox/convention.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -13,8 +13,6 @@ export function deliveryErrorPath(dir) { return `${dir}/delivery-error.json`; }
 export function followupRequestPath(dir) { return `${dir}/followup-request.json`; }
 export function followupResultPath(dir) { return `${dir}/followup-result.json`; }
 export function visualsDir(dir) { return `${dir}/visuals`; }
-export function visualMdPath(dir, id) { return `${dir}/visuals/${id}.md`; }
-export function visualAnsiPath(dir, id) { return `${dir}/visuals/${id}.ansi`; }
 /** Spawns a handler `{command,args}` with `event` as JSON on stdin. Exit 0
  *  acknowledges; a nonzero exit, spawn error, or 30s timeout rejects with an
  *  Error carrying the handler's captured stderr. Shared by completion delivery
@@ -65,6 +63,24 @@ export function atomicWriteJson(path, value) {
     writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
     renameSync(tmp, path);
 }
+/** Publish one immutable JSON record without replacing an existing winner. */
+export function publishJsonExclusive(path, value) {
+    const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    try {
+        linkSync(tmp, path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        unlinkSync(tmp);
+    }
+}
 export function readJson(path) {
     try {
         return JSON.parse(readFileSync(path, 'utf8'));

package/dist/inbox/deck-adapter.d.ts

@@ -1,4 +1,4 @@
-import type { Deck, FollowUpState, GenerateVisual, InteractionResponse } from '../types.js';
+import type { Deck, FollowUpState, InteractionResponse, VisualProvider } from '../types.js';
 import type { Key } from '../tui/terminal.js';
 export interface DeckAdapterOptions {
     dir: string;
@@ -9,7 +9,7 @@ export interface DeckAdapterOptions {
     onComplete: (responses: InteractionResponse[]) => void;
     onBack: () => void;
     onDirty: () => void;
-    generateVisual?: GenerateVisual;
+    visualProvider?: VisualProvider;
     onEditorRequest?: () => void;
     followUpAvailable?: boolean;
     onFollowUpRequest?: (question: string) => void;
@@ -30,6 +30,6 @@ export declare class DeckAdapter {
     canAcceptHostKeys(): boolean;
     handleKey(input: string, key: Key): void;
     /** Fresh descriptor reads preserve mounted answers for interaction ids still present. */
-    reload(deck: Deck): void;
+    reload(deck: Deck, visualProvider: VisualProvider | undefined): void;
     close(): void;
 }

package/dist/inbox/deck-adapter.js

@@ -20,7 +20,7 @@ export class DeckAdapter {
             onExit: () => { if (notificationsAcknowledged(opts.deck, this.responses))
                 opts.onComplete(this.responses); },
             onDirty: opts.onDirty,
-            generateVisual: opts.generateVisual,
+            visualProvider: opts.visualProvider,
             onEditorRequest: opts.onEditorRequest,
             followUpAvailable: opts.followUpAvailable,
             onFollowUpRequest: opts.onFollowUpRequest,
@@ -42,8 +42,8 @@ export class DeckAdapter {
         this.panel.handleKey(input, key);
     }
     /** Fresh descriptor reads preserve mounted answers for interaction ids still present. */
-    reload(deck) {
-        this.panel.loadDeck(deck, { progressPath: progressPath(this.opts.dir) });
+    reload(deck, visualProvider) {
+        this.panel.loadDeck(deck, { progressPath: progressPath(this.opts.dir), visualProvider });
         this.opts.onDirty();
     }
     close() { this.panel.unmount(); }

package/dist/inbox/deck-schema.d.ts

@@ -18,7 +18,7 @@ export declare const deckSchema: z.ZodObject<{
         askedBy: z.ZodOptional<z.ZodString>;
         blockedSince: z.ZodOptional<z.ZodString>;
         nodeId: z.ZodOptional<z.ZodString>;
-        originatingConversationSessionId: z.ZodOptional<z.ZodString>;
+        visual: z.ZodOptional<z.ZodLiteral<"humanloop.visual/v1">>;
     }, z.core.$strip>>;
     interactions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -59,7 +59,7 @@ export declare const reviewDescriptorSchema: z.ZodObject<{
         askedBy: z.ZodOptional<z.ZodString>;
         blockedSince: z.ZodOptional<z.ZodString>;
         nodeId: z.ZodOptional<z.ZodString>;
-        originatingConversationSessionId: z.ZodOptional<z.ZodString>;
+        visual: z.ZodOptional<z.ZodLiteral<"humanloop.visual/v1">>;
     }, z.core.$strip>;
     blockedSince: z.ZodString;
 }, z.core.$strict>;

package/dist/inbox/deck-schema.js

@@ -1,6 +1,6 @@
 import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, resolve, sep } from 'node:path';
-import { claimPath, deckPath, deliveryErrorPath, deliveryPath, followupRequestPath, followupResultPath, progressPath, responsePath, reviewPath } from './convention.js';
+import { claimPath, deckPath, deliveryErrorPath, deliveryPath, followupRequestPath, followupResultPath, progressPath, responsePath, reviewPath, visualsDir } from './convention.js';
 import { z } from 'zod';
 import { INTERACTION_KINDS } from '../types.js';
 import { checkMarkdown } from '../render/termrender.js';
@@ -11,7 +11,7 @@ const interactionSchema = z.object({
     title: z.string().min(1), subtitle: z.string().min(1).optional(), body: z.string().optional(), bodyPath: z.string().optional(),
     options: z.array(interactionOptionSchema), multiSelect: z.boolean().optional(), allowFreetext: z.boolean().optional(), freetextLabel: z.string().optional(), kind: z.enum(INTERACTION_KINDS).optional(), preAnswered: preAnswerSchema.optional(),
 });
-const deckSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional(), originatingConversationSessionId: z.string().min(1).optional() });
+const deckSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional(), visual: z.literal('humanloop.visual/v1').optional() });
 export const deckSchema = z.object({ title: z.string().optional(), source: deckSourceSchema.optional(), interactions: z.array(interactionSchema).min(1) }).superRefine((input, ctx) => {
     const seen = new Set();
     input.interactions.forEach((interaction, index) => {
@@ -77,8 +77,8 @@ export function validateReviewProjection(dir, parsed) {
         throw new Error('review file must be an existing absolute markdown file');
     const file = realpathSync(descriptor.file);
     const output = resolve(realpathSync(dirname(descriptor.output)), basename(descriptor.output));
-    const reserved = new Set(['deck.json', 'review.json', 'response.json', 'progress.json', 'claim.json', 'delivery.json', 'delivery-error.json', 'followup-request.json', 'followup-result.json']);
-    const ownProtocolPaths = new Set([deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir), followupRequestPath(dir), followupResultPath(dir)]);
+    const reserved = new Set(['deck.json', 'review.json', 'response.json', 'progress.json', 'claim.json', 'delivery.json', 'delivery-error.json', 'followup-request.json', 'followup-result.json', 'visuals']);
+    const ownProtocolPaths = new Set([deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir), followupRequestPath(dir), followupResultPath(dir), visualsDir(dir)]);
     if (output === file || reserved.has(basename(output)) || ownProtocolPaths.has(output))
         throw new Error('review output must not alias the source or ticket protocol files');
     return { ...descriptor, file, output };

package/dist/inbox/maintenance.d.ts

@@ -0,0 +1,4 @@
+/** Start one detached repair pass. The lease makes repeated UI gestures free. */
+export declare function kickInboxMaintenance(): void;
+/** Run repair and stay alive only until the durable cleanup retry queue is empty. */
+export declare function runInboxMaintenance(lease: string): Promise<void>;