@crouton-kit/humanloop 0.3.39 → 0.4.1

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';
@@ -15,6 +14,8 @@ 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';
@@ -23,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, FollowUpState, 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, FocusEvent, } 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).
@@ -12,6 +11,7 @@ export { registerInboxRoot, unregisterInboxRoot, listInboxRoots, managedInboxRoo
 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/surfaces/inbox-popup.d.ts

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

package/dist/surfaces/inbox-popup.js

@@ -2,8 +2,8 @@ import { createServer } from 'node:net';
 import { rmSync } from 'node:fs';
 import { InboxController } from '../inbox/controller.js';
 /** Run the inbox controller in a popup-owned TTY and accept graceful close requests. */
-export async function openInboxPopup(controlSocket, roots) {
-    const controller = new InboxController({ roots });
+export async function openInboxPopup(controlSocket, roots, targetPane) {
+    const controller = new InboxController({ roots, targetPane });
     const server = controlSocket === undefined ? undefined : createServer((connection) => {
         connection.once('data', (data) => {
             if (data.toString('utf8').trim() === 'close')

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 {
-    /** Originating provider 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,13 +1,13 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
+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 { visualGeneratorForConversationSession } from '../visuals/conversation.js';
-import { visualRenderWidth } 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';
@@ -107,10 +107,13 @@ 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 context locally; resizing must never invoke the model. */
+/** 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)
@@ -118,27 +121,58 @@ function rerenderVisuals(internals) {
         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 generation = internals.visualGeneration;
+    const generationId = randomUUID();
     for (const interaction of interactions) {
-        const generationCols = internals.cols;
+        const requestId = randomUUID();
         internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'loading' });
-        gen(interaction, generationCols).then((r) => {
+        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: internals.cols === generationCols ? r.ansi : renderVisualMarkdown(r.markdown, internals.cols), markdown: r.markdown, 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.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, { questionId: interaction.id, content: '', status: 'error' });
             internals.callbacks.onDirty?.();
@@ -154,8 +188,9 @@ export function mountPanel(opts) {
         cols: opts.cols,
         rows: opts.rows,
         mounted: true,
-        generateVisual: opts.generateVisual,
+        visualProvider: opts.visualProvider,
         visualGeneration: 0,
+        visualHandles: new Map(),
         progressPath: opts.progressPath,
         followUpAvailable,
         callbacks: {
@@ -230,14 +265,21 @@ export function mountPanel(opts) {
             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);
+            // 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;
@@ -321,7 +363,6 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
     const term = getTerminalSize();
     const cols = opts.cols ?? term.cols;
     const rows = opts.rows ?? term.rows;
-    const generateVisual = opts.generateVisual ?? (opts.sessionId === undefined ? undefined : visualGeneratorForConversationSession(opts.sessionId));
     return new Promise((resolve) => {
         let panel = null;
         let prevFrameLocal = [];
@@ -408,7 +449,7 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             progressPath: progressPathFor(dir),
             cols,
             rows,
-            generateVisual,
+            visualProvider: opts.visualProvider,
             onEditorRequest: () => {
                 const buffer = panel?.getInputBuffer();
                 if (buffer !== undefined)
@@ -599,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}`);
     }
@@ -608,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/render.js

@@ -219,7 +219,7 @@ function buildItemReviewLayout(state, cols, rows) {
         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.
@@ -305,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.
@@ -318,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
@@ -346,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/tmux.js

@@ -87,7 +87,8 @@ export async function toggleInboxPopup(target) {
         }
         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)}`;
+        const targetPaneArg = resolved.targetPane === undefined ? '' : ` --target-pane ${quote(resolved.targetPane)}`;
+        const command = `${quote(process.execPath)} ${quote(fileURLToPath(new URL('../cli.js', import.meta.url)))} inbox open --control-socket ${quote(paths.controlSocket)}${targetPaneArg}`;
         const result = await launchPopup(socket, resolved, paths.controlSocket, command);
         logPopupEvent('toggle.completed', { ...resolved, controlSocket: paths.controlSocket, result });
         return result;

package/dist/types.d.ts

@@ -68,9 +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;
-    /** Durable identifier of the conversation session that originated this ask.
-     *  It is explicit metadata, never inferred from node identity or labels. */
-    originatingConversationSessionId?: string;
+    /** Host-owned durable Visual capability marker. A registered handler is also required. */
+    visual?: 'humanloop.visual/v1';
 }
 export interface Deck {
     title?: string;
@@ -248,6 +247,16 @@ export interface CompletionEvent {
     outcome: 'resolved' | 'canceled';
     responsePath: string;
 }
+/** A popup request to reveal the host surface that created a ticket. The root's
+ * trusted focus handler decides what that means; humanloop only supplies the
+ * selected ticket and the tmux pane underneath the popup. */
+export interface FocusEvent {
+    schema: 'humanloop.focus/v1';
+    root: string;
+    dir: string;
+    ticketId: string;
+    targetPane: string;
+}
 /** Options for `display()` — the live-watch tmux pane surface. The pane always
  *  watches the file and live-updates on edits; there is no non-watched mode. */
 export interface DisplayOpts {
@@ -256,20 +265,47 @@ export interface DisplayOpts {
     /** Pane budget per window before `'auto'` opens a new window. Default 3. */
     maxPanes?: number;
 }
-export type GenerateVisual = (interaction: Interaction, 
-/** Render width owned by the mounting surface. */
-cols: number) => 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;
@@ -293,6 +329,7 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.39",
+  "version": "0.4.1",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "engines": {
     "node": ">=22.19.0"
@@ -36,8 +36,6 @@
     "test": "node scripts/run-tests.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.6",
-    "@r-cli/sdk": "^1.3.0",
     "commander": "^13.0.0",
     "string-width": "^7.0.0",
     "ws": "^8.21.0",
@@ -46,6 +44,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.27.7",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0"
   }

package/dist/conversation/reader.d.ts

@@ -1,20 +0,0 @@
-export interface ConversationMessage {
-    role: 'user' | 'assistant';
-    content: string;
-}
-export type ConversationReadErrorCode = 'session_not_found' | 'session_ambiguous' | 'session_unreadable' | 'session_id_mismatch' | 'conversation_empty';
-export declare class ConversationReadError extends Error {
-    readonly code: ConversationReadErrorCode;
-    constructor(code: ConversationReadErrorCode);
-}
-export interface ConversationReaderOptions {
-    /** Claude SQLite path override for a real-store fixture; production uses Claude's standard store. */
-    claudeDbPath?: string;
-}
-/** Read messages from Claude's local conversation store. */
-export declare function readConversation(sessionId: string, options?: ConversationReaderOptions): ConversationMessage[];
-/** Resolve a pi session by exact header id and return its active useful context. */
-export declare function readPiConversationText(sessionId: string): Promise<string>;
-/** Resolve by exact membership across provider stores, never by session-id shape. */
-export declare function readConversationText(sessionId: string, options?: ConversationReaderOptions): Promise<string>;
-export declare function findRecentSessionId(cwd?: string): string | null;