@crouton-kit/humanloop 0.3.38 → 0.4.0

package/dist/inbox/convention.d.ts

@@ -6,15 +6,22 @@ export declare function progressPath(dir: string): string;
 export declare function claimPath(dir: string): string;
 export declare function deliveryPath(dir: string): string;
 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
+ *  and follow-up dispatch — both invoke a registered handler the same way. */
+export declare function runHandler(command: string, args: string[], event: unknown): Promise<void>;
 export type InteractionState = 'pending' | 'claimed' | 'resolved' | 'missing';
 export declare function interactionState(dir: string): InteractionState;
 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,5 @@
-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';
 import { buildSummary } from '../summary.js';
@@ -9,9 +10,38 @@ 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';
@@ -33,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, 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,6 +9,11 @@ export interface DeckAdapterOptions {
     onComplete: (responses: InteractionResponse[]) => void;
     onBack: () => void;
     onDirty: () => void;
+    visualProvider?: VisualProvider;
+    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, visualProvider: VisualProvider | undefined): 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,
+            visualProvider: opts.visualProvider,
+            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, visualProvider) {
+        this.panel.loadDeck(deck, { progressPath: progressPath(this.opts.dir), visualProvider });
+        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>;
+        visual: z.ZodOptional<z.ZodLiteral<"humanloop.visual/v1">>;
     }, 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>;
+        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, 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() });
+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']);
-    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', '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/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,8 @@ export interface InboxRootRegistration {
     root: string;
     owner: string;
     handler?: CompletionHandler;
+    followUpHandler?: CompletionHandler;
+    visualHandler?: CompletionHandler;
 }
 export interface InboxRootStatus extends InboxRootRegistration {
     available: boolean;
@@ -16,6 +18,8 @@ export interface RegisterInboxRootOptions {
     root: string;
     owner: string;
     handler?: CompletionHandler;
+    followUpHandler?: CompletionHandler;
+    visualHandler?: CompletionHandler;
 }
 export declare function inboxRootsDirectory(): string;
 /** Create/canonicalize a root and claim its user-scoped registration. */

package/dist/inbox/registry.js

@@ -15,8 +15,8 @@ catch {
 function validateHandler(handler) {
     if (handler === undefined)
         return undefined;
-    if (!handler.command || !Array.isArray(handler.args) || !handler.args.every((arg) => typeof arg === 'string'))
-        throw new Error('completion handler requires a command and string args');
+    if (typeof handler.command !== 'string' || handler.command.trim() === '' || !Array.isArray(handler.args) || !handler.args.every((arg) => typeof arg === 'string'))
+        throw new Error('handler requires a non-empty command and string args');
     return { command: handler.command, args: [...handler.args] };
 }
 function validateRegistration(raw) {
@@ -26,7 +26,12 @@ 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),
+            visualHandler: value.visualHandler === undefined ? undefined : validateHandler(value.visualHandler),
+        };
     }
     catch {
         return null;
@@ -46,7 +51,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), visualHandler: validateHandler(opts.visualHandler) };
         atomicWriteJson(path, registration);
         chmodSync(path, 0o600);
         return registration;

package/dist/inbox/tickets.d.ts

@@ -1,6 +1,11 @@
 import type { Deck, DeckTicketResult, FeedbackResult, ReviewDescriptor, TicketResult } from '../types.js';
 /** Strict decoder for the only canonical final marker. */
 export declare function readTicketResult(dirOrResponsePath: string): TicketResult | null;
+/** Canonical registered-root/direct-child containment shared by host protocols. */
+export declare function requireCanonicalTicket(root: string, dir: string): {
+    root: string;
+    dir: string;
+};
 export interface SubmitDeckOptions {
     root: string;
     id: string;

package/dist/inbox/tickets.js

@@ -1,12 +1,13 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 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, publishJsonExclusive, responsePath, reviewPath, visualsDir } from './convention.js';
 import { validateDeck, validateReviewDescriptor, validateReviewProjection, resolveDeckBodyPaths } from './deck-schema.js';
 import { registeredInboxRoot } from './registry.js';
 import { readTicketClaim, releaseClaimLocked, withTicketLock } from './claim.js';
 import { dispatchCompletion } from './completion.js';
+import { cancelVisualRequestsForTicket } from './visual.js';
 const ticketId = z.string().regex(/^[A-Za-z0-9_-]+$/).min(1).max(128);
 const responseSchema = z.object({ id: z.string().min(1), selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), optionComments: z.record(z.string(), z.string()).optional() }).strict();
 const feedbackCommentSchema = z.object({ id: z.string().min(1), line: z.number().int().positive(), endLine: z.number().int().positive(), quote: z.string().optional(), colStart: z.number().int().nonnegative().optional(), colEnd: z.number().int().nonnegative().optional(), lineText: z.string(), comment: z.string().min(1), createdAt: z.string().min(1) }).strict();
@@ -70,7 +71,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), visualsDir(dir)].some(existsSync);
 }
 function requireRegisteredTicket(dir) {
     const canonical = realpathSync(dir);
@@ -82,21 +83,17 @@ function requireRegisteredTicket(dir) {
         throw new Error('ticket has no request descriptor');
     return { root, dir: canonical };
 }
+/** Canonical registered-root/direct-child containment shared by host protocols. */
+export function requireCanonicalTicket(root, dir) {
+    const registration = registeredInboxRoot(root);
+    const ticket = requireRegisteredTicket(dir);
+    if (registration === null || ticket.root !== registration.root)
+        throw new Error('ticket is not a canonical direct child of the registered root');
+    return ticket;
+}
 function publishRequest(path, value) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-    try {
-        linkSync(temp, path);
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            throw new Error(`ticket request already exists: ${path}`);
-        throw error;
-    }
-    finally {
-        unlinkSync(temp);
-    }
+    if (!publishJsonExclusive(path, value))
+        throw new Error(`ticket request already exists: ${path}`);
 }
 export function submitDeck(opts) {
     // Validate shape before mutating caller-owned interaction directories.
@@ -135,21 +132,7 @@ export function submitReview(opts) {
     }
 }
 function exclusiveResult(dir, result) {
-    const path = responsePath(dir);
-    const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
-    try {
-        linkSync(temp, path);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            return false;
-        throw error;
-    }
-    finally {
-        unlinkSync(temp);
-    }
+    return publishJsonExclusive(responsePath(dir), result);
 }
 function requireDeck(dir) { return validateDeck(JSON.parse(readFileSync(deckPath(dir), 'utf8'))); }
 function requireReview(dir) { return validateReviewDescriptor(JSON.parse(readFileSync(reviewPath(dir), 'utf8'))); }
@@ -172,6 +155,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) {
@@ -185,6 +174,10 @@ export function finalizeDeck(dir, responses, claimToken, completedAt = new Date(
         requireClaimOwnership(ticket.dir, claimToken);
         const deck = requireDeck(ticket.dir);
         const parsedResponses = validateDeckResponses(deck, responses);
+        // A valid primary result ends its panel generation before the canonical
+        // response can cross the owner boundary. The protocol persists cancellation
+        // first; its independent cleanup executor owns eventual handler delivery.
+        void cancelVisualRequestsForTicket(ticket.root, ticket.dir);
         const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: parsedResponses, summary: buildSummary(deck, parsedResponses), completedAt };
         const won = exclusiveResult(ticket.dir, result);
         clearOwnedWork(ticket.dir, claimToken);

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[];