@crouton-kit/humanloop 0.3.37 → 0.3.39

package/dist/inbox/convention.js

@@ -1,4 +1,5 @@
 import { existsSync, 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';
 import { buildSummary } from '../summary.js';
@@ -9,9 +10,40 @@ export function progressPath(dir) { return `${dir}/progress.json`; }
 export function claimPath(dir) { return `${dir}/claim.json`; }
 export function deliveryPath(dir) { return `${dir}/delivery.json`; }
 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
+ *  and follow-up dispatch — both invoke a registered handler the same way. */
+export async function runHandler(command, args, event) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        // stdout stays ignored (a handler acknowledges by exit code, never stdout),
+        // but stderr is captured so a nonzero exit surfaces the handler's own
+        // diagnostics in the delivery-error record instead of a bare exit code.
+        const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { stderr += chunk; if (stderr.length > 8192)
+            stderr = stderr.slice(-8192); });
+        let timedOut = false;
+        const timeout = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 30_000);
+        child.once('error', (error) => { clearTimeout(timeout); rejectPromise(error); });
+        child.once('exit', (code, signal) => {
+            clearTimeout(timeout);
+            const detail = stderr.trim() === '' ? '' : `: ${stderr.trim()}`;
+            if (timedOut)
+                rejectPromise(new Error(`handler timed out after 30 seconds${detail}`));
+            else if (code === 0)
+                resolvePromise();
+            else
+                rejectPromise(new Error(`handler failed (${signal ?? code ?? 'unknown'})${detail}`));
+        });
+        child.stdin.end(`${JSON.stringify(event)}\n`);
+    });
+}
 export function interactionState(dir) {
     if (!existsSync(deckPath(dir)) && !existsSync(reviewPath(dir)))
         return 'missing';

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

@@ -1,4 +1,4 @@
-import type { Deck, InteractionResponse } from '../types.js';
+import type { Deck, FollowUpState, GenerateVisual, InteractionResponse } from '../types.js';
 import type { Key } from '../tui/terminal.js';
 export interface DeckAdapterOptions {
     dir: string;
@@ -9,6 +9,11 @@ export interface DeckAdapterOptions {
     onComplete: (responses: InteractionResponse[]) => void;
     onBack: () => void;
     onDirty: () => void;
+    generateVisual?: GenerateVisual;
+    onEditorRequest?: () => void;
+    followUpAvailable?: boolean;
+    onFollowUpRequest?: (question: string) => void;
+    onFollowUpCancel?: () => void;
 }
 /** Embeds the single deck renderer in a controller-owned rectangle. */
 export declare class DeckAdapter {
@@ -19,9 +24,12 @@ export declare class DeckAdapter {
     render(): string[];
     resize(cols: number, rows: number): string[];
     inputBuffer(): string | undefined;
+    setInputBuffer(text: string): void;
+    setFollowUpHandlers(available: boolean, onRequest?: (question: string) => void, onCancel?: () => void): void;
+    setFollowUpState(state: FollowUpState): void;
     canAcceptHostKeys(): boolean;
     handleKey(input: string, key: Key): void;
     /** Fresh descriptor reads preserve mounted answers for interaction ids still present. */
-    reload(): void;
+    reload(deck: Deck): void;
     close(): void;
 }

package/dist/inbox/deck-adapter.js

@@ -1,6 +1,4 @@
-import { readFileSync } from 'node:fs';
-import { deckPath, progressPath, readJson } from './convention.js';
-import { validateDeck } from './deck-schema.js';
+import { progressPath, readJson } from './convention.js';
 import { mountPanel } from '../tui/app.js';
 /** Embeds the single deck renderer in a controller-owned rectangle. */
 export class DeckAdapter {
@@ -17,13 +15,24 @@ export class DeckAdapter {
             rows: opts.rows,
             onProgress: (responses) => { this.responses = responses; opts.onProgress?.(responses); },
             onComplete: opts.onComplete,
-            onExit: () => opts.onComplete(this.responses),
+            // A partial-deck exit is a valid completion for ordinary asks, but a
+            // notification is resolved only by its explicit acknowledgement.
+            onExit: () => { if (notificationsAcknowledged(opts.deck, this.responses))
+                opts.onComplete(this.responses); },
             onDirty: opts.onDirty,
+            generateVisual: opts.generateVisual,
+            onEditorRequest: opts.onEditorRequest,
+            followUpAvailable: opts.followUpAvailable,
+            onFollowUpRequest: opts.onFollowUpRequest,
+            onFollowUpCancel: opts.onFollowUpCancel,
         });
     }
     render() { return this.panel.render(); }
     resize(cols, rows) { return this.panel.handleResize(cols, rows); }
     inputBuffer() { return this.panel.getInputBuffer(); }
+    setInputBuffer(text) { this.panel.setInputBuffer(text); }
+    setFollowUpHandlers(available, onRequest, onCancel) { this.panel.setFollowUpHandlers(available, onRequest, onCancel); }
+    setFollowUpState(state) { this.panel.setFollowUpState(state); }
     canAcceptHostKeys() { return this.panel.canAcceptHostKeys(); }
     handleKey(input, key) {
         if (key.escape && this.panel.atDeckTop()) {
@@ -33,17 +42,19 @@ export class DeckAdapter {
         this.panel.handleKey(input, key);
     }
     /** Fresh descriptor reads preserve mounted answers for interaction ids still present. */
-    reload() {
-        try {
-            this.panel.loadDeck(validateDeck(JSON.parse(readFileSync(deckPath(this.opts.dir), 'utf8'))), { progressPath: progressPath(this.opts.dir) });
-            this.opts.onDirty();
-        }
-        catch {
-            // An incomplete external rewrite is not a new deck; retain the current editor.
-        }
+    reload(deck) {
+        this.panel.loadDeck(deck, { progressPath: progressPath(this.opts.dir) });
+        this.opts.onDirty();
     }
     close() { this.panel.unmount(); }
 }
+function notificationsAcknowledged(deck, responses) {
+    const byId = new Map(responses.map((response) => [response.id, response]));
+    return deck.interactions.filter((interaction) => interaction.kind === 'notify').every((interaction) => {
+        const response = byId.get(interaction.id);
+        return response !== undefined && (response.selectedOptionId !== undefined || (response.selectedOptionIds?.length ?? 0) > 0 || (response.freetext?.trim() ?? '') !== '');
+    });
+}
 function initialResponses(deck, dir) {
     const saved = readJson(progressPath(dir))?.responses;
     if (Array.isArray(saved))

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

@@ -18,6 +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>;
     }, z.core.$strip>>;
     interactions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -58,6 +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>;
     }, 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, progressPath, responsePath, reviewPath } from './convention.js';
+import { claimPath, deckPath, deliveryErrorPath, deliveryPath, followupRequestPath, followupResultPath, progressPath, responsePath, reviewPath } 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() });
+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() });
 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']);
-    const ownProtocolPaths = new Set([deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(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']);
+    const ownProtocolPaths = new Set([deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir), followupRequestPath(dir), followupResultPath(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/followup.d.ts

@@ -0,0 +1,57 @@
+export interface FollowUpRequestEvent {
+    schema: 'humanloop.followup-request/v1';
+    action: 'start' | 'cancel';
+    capability: 'humanloop.follow-up/v1';
+    owner: string;
+    root: string;
+    dir: string;
+    ticketId: string;
+    requestId: string;
+    question: string;
+}
+/** followup-request.json — humanloop-owned. A state machine, not delete-on-cancel;
+ *  the sole writer is humanloop, always under `.followup-lock`. */
+export interface FollowUpRequest {
+    schema: 'humanloop.followup-request/v1';
+    requestId: string;
+    question: string;
+    state: 'running' | 'canceled' | 'superseded' | 'terminal';
+    askedAt: string;
+    settledAt?: string;
+}
+/** followup-result.json — the provider's writer, via `submitFollowUpResult`'s
+ *  compare-and-publish gate. */
+export interface FollowUpResult {
+    schema: 'humanloop.followup-result/v1';
+    requestId: string;
+    status: 'ready' | 'error';
+    markdown?: string;
+    error?: string;
+    completedAt: string;
+}
+/** Supersede any running request, write a fresh `running` request, and fire a
+ *  best-effort `start` kickoff to the registered handler. */
+export declare function requestFollowUp(root: string, dir: string, opts: {
+    question: string;
+}): FollowUpRequest;
+/** Mark the current running request `canceled` (never deleted) and best-effort
+ *  notify the handler. A no-op when nothing is running. */
+export declare function cancelFollowUp(root: string, dir: string): void;
+/** The provider's writer. Canonicalizes a registered direct-child ticket, then
+ *  publishes ONLY if `result.requestId` matches the current `running` request
+ *  under `.followup-lock` \u2014 the authoritative guard that a superseded/canceled
+ *  writer's late answer can never clobber a newer result. A stale writer is a
+ *  silent no-op. A `ready` whose markdown fails `checkMarkdown` is downgraded
+ *  to an `error` result, never thrown. */
+export declare function submitFollowUpResult(root: string, dir: string, result: {
+    requestId: string;
+    status: 'ready' | 'error';
+    markdown?: string;
+    error?: string;
+}): {
+    published: boolean;
+};
+export declare function readFollowUp(dir: string): {
+    request: FollowUpRequest | null;
+    result: FollowUpResult | null;
+};

package/dist/inbox/followup.js

@@ -0,0 +1,117 @@
+import { realpathSync } from 'node:fs';
+import { basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomicWriteJson, followupRequestPath, followupResultPath, readJson, runHandler, withExclusiveDirectoryLock } from './convention.js';
+import { registeredInboxRoot } from './registry.js';
+import { ticketRoot } from './tickets.js';
+import { checkMarkdown } from '../render/termrender.js';
+const CAPABILITY = 'humanloop.follow-up/v1';
+function lockPath(dir) { return `${dir}/.followup-lock`; }
+function requireCanonicalTicket(root, dir) {
+    const registration = registeredInboxRoot(root);
+    let canonicalDir;
+    try {
+        canonicalDir = realpathSync(dir);
+    }
+    catch {
+        throw new Error('ticket is not a canonical direct child of a registered root');
+    }
+    if (registration === null || ticketRoot(canonicalDir) !== registration.root)
+        throw new Error('ticket is not a canonical direct child of a registered root');
+    return { root: registration.root, dir: canonicalDir, owner: registration.owner, followUpHandler: registration.followUpHandler };
+}
+function requireFollowUpHandler(root, dir) {
+    const ticket = requireCanonicalTicket(root, dir);
+    if (ticket.followUpHandler === undefined)
+        throw new Error('root has no registered follow-up handler');
+    return { ...ticket, followUpHandler: ticket.followUpHandler };
+}
+function normalizeResult(result) {
+    const completedAt = new Date().toISOString();
+    if (result.status === 'ready') {
+        if (typeof result.markdown !== 'string' || result.markdown.trim().length === 0) {
+            return { schema: 'humanloop.followup-result/v1', requestId: result.requestId, status: 'error', error: 'ready result requires non-empty markdown', completedAt };
+        }
+        const check = checkMarkdown(result.markdown);
+        if (!check.ok)
+            return { schema: 'humanloop.followup-result/v1', requestId: result.requestId, status: 'error', error: check.error, completedAt };
+        return { schema: 'humanloop.followup-result/v1', requestId: result.requestId, status: 'ready', markdown: result.markdown, completedAt };
+    }
+    return { schema: 'humanloop.followup-result/v1', requestId: result.requestId, status: 'error', error: result.error ?? 'unknown error', completedAt };
+}
+/** Supersede any running request, write a fresh `running` request, and fire a
+ *  best-effort `start` kickoff to the registered handler. */
+export function requestFollowUp(root, dir, opts) {
+    const { root: canonicalRoot, dir: canonicalDir, owner, followUpHandler } = requireFollowUpHandler(root, dir);
+    const request = {
+        schema: 'humanloop.followup-request/v1',
+        requestId: randomUUID(),
+        question: opts.question,
+        state: 'running',
+        askedAt: new Date().toISOString(),
+    };
+    withExclusiveDirectoryLock(lockPath(canonicalDir), () => {
+        const current = readJson(followupRequestPath(canonicalDir));
+        if (current !== null && current.state === 'running') {
+            atomicWriteJson(followupRequestPath(canonicalDir), { ...current, state: 'superseded', settledAt: new Date().toISOString() });
+        }
+        atomicWriteJson(followupRequestPath(canonicalDir), request);
+    });
+    const event = {
+        schema: 'humanloop.followup-request/v1', action: 'start', capability: CAPABILITY,
+        owner, root: canonicalRoot, dir: canonicalDir, ticketId: basename(canonicalDir),
+        requestId: request.requestId, question: opts.question,
+    };
+    void runHandler(followUpHandler.command, followUpHandler.args, event).catch((error) => {
+        submitFollowUpResult(canonicalRoot, canonicalDir, { requestId: request.requestId, status: 'error', error: error instanceof Error ? error.message : String(error) });
+    });
+    return request;
+}
+/** Mark the current running request `canceled` (never deleted) and best-effort
+ *  notify the handler. A no-op when nothing is running. */
+export function cancelFollowUp(root, dir) {
+    const { owner, root: canonicalRoot, dir: canonicalDir, followUpHandler } = requireFollowUpHandler(root, dir);
+    const canceled = withExclusiveDirectoryLock(lockPath(canonicalDir), () => {
+        const current = readJson(followupRequestPath(canonicalDir));
+        if (current === null || current.state !== 'running')
+            return null;
+        atomicWriteJson(followupRequestPath(canonicalDir), { ...current, state: 'canceled', settledAt: new Date().toISOString() });
+        return current;
+    });
+    if (canceled === null)
+        return;
+    const event = {
+        schema: 'humanloop.followup-request/v1', action: 'cancel', capability: CAPABILITY,
+        owner, root: canonicalRoot, dir: canonicalDir, ticketId: basename(canonicalDir),
+        requestId: canceled.requestId, question: '',
+    };
+    void runHandler(followUpHandler.command, followUpHandler.args, event).catch(() => { });
+}
+/** The provider's writer. Canonicalizes a registered direct-child ticket, then
+ *  publishes ONLY if `result.requestId` matches the current `running` request
+ *  under `.followup-lock` \u2014 the authoritative guard that a superseded/canceled
+ *  writer's late answer can never clobber a newer result. A stale writer is a
+ *  silent no-op. A `ready` whose markdown fails `checkMarkdown` is downgraded
+ *  to an `error` result, never thrown. */
+export function submitFollowUpResult(root, dir, result) {
+    const { dir: canonicalDir } = requireCanonicalTicket(root, dir);
+    const normalized = normalizeResult(result);
+    return withExclusiveDirectoryLock(lockPath(canonicalDir), () => {
+        const current = readJson(followupRequestPath(canonicalDir));
+        if (current === null || current.requestId !== result.requestId || current.state !== 'running')
+            return { published: false };
+        atomicWriteJson(followupResultPath(canonicalDir), normalized);
+        atomicWriteJson(followupRequestPath(canonicalDir), { ...current, state: 'terminal', settledAt: normalized.completedAt });
+        return { published: true };
+    });
+}
+export function readFollowUp(dir) {
+    let canonicalDir;
+    try {
+        canonicalDir = realpathSync(dir);
+    }
+    catch {
+        return { request: null, result: null };
+    }
+    return { request: readJson(followupRequestPath(canonicalDir)), result: readJson(followupResultPath(canonicalDir)) };
+}

package/dist/inbox/registry.d.ts

@@ -8,6 +8,7 @@ export interface InboxRootRegistration {
     root: string;
     owner: string;
     handler?: CompletionHandler;
+    followUpHandler?: CompletionHandler;
 }
 export interface InboxRootStatus extends InboxRootRegistration {
     available: boolean;
@@ -16,6 +17,7 @@ export interface RegisterInboxRootOptions {
     root: string;
     owner: string;
     handler?: CompletionHandler;
+    followUpHandler?: CompletionHandler;
 }
 export declare function inboxRootsDirectory(): string;
 /** Create/canonicalize a root and claim its user-scoped registration. */

package/dist/inbox/registry.js

@@ -26,7 +26,11 @@ function validateRegistration(raw) {
     if (value.schema !== 'humanloop.inbox-root/v1' || typeof value.root !== 'string' || !value.root || typeof value.owner !== 'string' || !value.owner.trim())
         return null;
     try {
-        return { schema: 'humanloop.inbox-root/v1', root: value.root, owner: value.owner, handler: value.handler === undefined ? undefined : validateHandler(value.handler) };
+        return {
+            schema: 'humanloop.inbox-root/v1', root: value.root, owner: value.owner,
+            handler: value.handler === undefined ? undefined : validateHandler(value.handler),
+            followUpHandler: value.followUpHandler === undefined ? undefined : validateHandler(value.followUpHandler),
+        };
     }
     catch {
         return null;
@@ -46,7 +50,7 @@ export function registerInboxRoot(opts) {
             throw new Error(`inbox root is already owned by ${existing.owner}`);
         if (existing !== null && existing.root !== root)
             throw new Error('inbox root registry hash collision');
-        const registration = { schema: 'humanloop.inbox-root/v1', root, owner: opts.owner, handler: validateHandler(opts.handler) };
+        const registration = { schema: 'humanloop.inbox-root/v1', root, owner: opts.owner, handler: validateHandler(opts.handler), followUpHandler: validateHandler(opts.followUpHandler) };
         atomicWriteJson(path, registration);
         chmodSync(path, 0o600);
         return registration;

package/dist/inbox/tickets.js

@@ -2,7 +2,7 @@ import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, rmSync, un
 import { basename, dirname, isAbsolute, resolve } from 'node:path';
 import { z } from 'zod';
 import { buildSummary } from '../summary.js';
-import { clearProgress, claimPath, deckPath, deliveryErrorPath, deliveryPath, progressPath, responsePath, reviewPath } from './convention.js';
+import { clearProgress, claimPath, deckPath, deliveryErrorPath, deliveryPath, followupRequestPath, followupResultPath, progressPath, responsePath, reviewPath } from './convention.js';
 import { validateDeck, validateReviewDescriptor, validateReviewProjection, resolveDeckBodyPaths } from './deck-schema.js';
 import { registeredInboxRoot } from './registry.js';
 import { readTicketClaim, releaseClaimLocked, withTicketLock } from './claim.js';
@@ -70,7 +70,7 @@ function ticketDir(root, id) {
 function discardCreatedTicket(dir, created) { if (created)
     rmSync(dir, { recursive: true, force: true }); }
 function hasTicketProtocolState(dir) {
-    return [deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir)].some(existsSync);
+    return [deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir), followupRequestPath(dir), followupResultPath(dir)].some(existsSync);
 }
 function requireRegisteredTicket(dir) {
     const canonical = realpathSync(dir);
@@ -172,6 +172,12 @@ function validateDeckResponses(deck, raw) {
         if (response.optionComments !== undefined && (interaction.multiSelect !== true || Object.keys(response.optionComments).some((id) => !optionIds.has(id))))
             throw new Error(`invalid option comments for ${response.id}`);
     }
+    for (const interaction of deck.interactions.filter((candidate) => candidate.kind === 'notify')) {
+        const response = responses.find((candidate) => candidate.id === interaction.id);
+        if (response === undefined || (response.selectedOptionId === undefined && (response.selectedOptionIds?.length ?? 0) === 0 && (response.freetext?.trim() ?? '') === '')) {
+            throw new Error(`notification requires an explicit acknowledgement: ${interaction.id}`);
+        }
+    }
     return responses;
 }
 function requireClaimOwnership(dir, token) {

package/dist/inbox/tui.d.ts

@@ -3,4 +3,4 @@ export declare const KIND_ICON: Record<string, string>;
 export declare const KIND_COLOR: Record<string, string>;
 export declare function formatTimeAgo(iso: string): string;
 /** Pure inbox rows; selection and terminal ownership belong to InboxController. */
-export declare function buildInboxLines(items: TicketSummary[], width: number, selectedIndex: number): string[];
+export declare function buildInboxLines(items: TicketSummary[], width: number, selectedIndex: number, height?: number): string[];

package/dist/inbox/tui.js

@@ -19,33 +19,66 @@ export function formatTimeAgo(iso) {
     return 'just now';
 }
 /** Pure inbox rows; selection and terminal ownership belong to InboxController. */
-export function buildInboxLines(items, width, selectedIndex) {
+export function buildInboxLines(items, width, selectedIndex, height = Number.MAX_SAFE_INTEGER) {
     if (items.length === 0)
         return [`  ${DIM}${ITALIC}No pending interactions${RESET}`];
-    const lines = [`  ${BOLD}${items.length} pending${RESET}`, ''];
     const contentWidth = width - 4;
-    for (let index = 0; index < items.length; index++) {
-        const item = items[index];
-        const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
-        const icon = KIND_ICON[kind] ?? '·';
-        // Source and title share the row budget: an unbounded source (a long node
-        // or session name) would floor the title at its minimum and overflow the
-        // column, bending the panel divider. Shrink the source only when the row
-        // cannot hold it alongside the title's 10-col minimum.
-        const rawSource = item.source.sessionName ?? item.source.askedBy ?? item.source.nodeId ?? '';
-        const age = formatTimeAgo(item.blockedSince);
-        const source = truncateRow(rawSource, Math.max(8, contentWidth - age.length - 8 - 10));
-        const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
-        const titleWidth = Math.max(10, contentWidth - source.length - age.length - 8);
-        let row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} `;
-        if (source)
-            row += `${ansiColor(source, 'yellow')} ${DIM}·${RESET} `;
-        row += `${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
-        lines.push(row);
-        if (item.claim)
-            lines.push(`      ${DIM}${truncateRow(`claimed by ${item.claim.owner}`, contentWidth - 6)}${RESET}`);
-        else if (item.subtitle)
-            lines.push(`      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`);
-    }
+    const itemLines = items.map((item, index) => buildItemLines(item, index, selectedIndex, contentWidth));
+    const window = visibleWindow(itemLines, selectedIndex, Math.max(1, height - 2));
+    const lines = [`  ${BOLD}${items.length} pending${RESET}`, ''];
+    if (window.start > 0)
+        lines.push(`  ${DIM}↑ ${window.start} above${RESET}`);
+    for (let index = window.start; index < window.end; index++)
+        lines.push(...itemLines[index]);
+    if (window.end < items.length)
+        lines.push(`  ${DIM}↓ ${items.length - window.end} below${RESET}`);
     return lines;
 }
+function buildItemLines(item, index, selectedIndex, contentWidth) {
+    const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
+    const icon = KIND_ICON[kind] ?? '·';
+    // Source and title share the row budget: an unbounded source (a long node
+    // or session name) would floor the title at its minimum and overflow the
+    // column, bending the panel divider. Shrink the source only when the row
+    // cannot hold it alongside the title's 10-col minimum.
+    const rawSource = item.source.sessionName ?? item.source.askedBy ?? item.source.nodeId ?? '';
+    const age = formatTimeAgo(item.blockedSince);
+    const source = truncateRow(rawSource, Math.max(8, contentWidth - age.length - 8 - 10));
+    const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
+    const titleWidth = Math.max(10, contentWidth - source.length - age.length - 8);
+    let row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} `;
+    if (source)
+        row += `${ansiColor(source, 'yellow')} ${DIM}·${RESET} `;
+    row += `${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
+    if (item.claim)
+        return [row, `      ${DIM}${truncateRow(`claimed by ${item.claim.owner}`, contentWidth - 6)}${RESET}`];
+    if (item.subtitle)
+        return [row, `      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`];
+    return [row];
+}
+/** Select a contiguous row window that always contains the selected ticket. */
+function visibleWindow(rows, selectedIndex, capacity) {
+    let start = Math.max(0, Math.min(selectedIndex, rows.length - 1));
+    let end = start + 1;
+    let preferBelow = true;
+    while (true) {
+        const below = end < rows.length ? { start, end: end + 1 } : undefined;
+        const above = start > 0 ? { start: start - 1, end } : undefined;
+        const preferred = preferBelow ? [below, above] : [above, below];
+        const next = preferred.find((candidate) => candidate !== undefined && windowHeight(rows, candidate.start, candidate.end) <= capacity);
+        if (next === undefined)
+            break;
+        start = next.start;
+        end = next.end;
+        preferBelow = !preferBelow;
+    }
+    return { start, end };
+}
+function windowHeight(rows, start, end) {
+    let height = start > 0 ? 1 : 0;
+    for (let index = start; index < end; index++)
+        height += rows[index].length;
+    if (end < rows.length)
+        height++;
+    return height;
+}

package/dist/index.d.ts

@@ -13,6 +13,8 @@ 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 { 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 +23,6 @@ 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, 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 { Key } from './tui/terminal.js';
 export type { ConversationMessage } from './conversation/reader.js';

package/dist/index.js

@@ -11,6 +11,7 @@ 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 { 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.