@crouton-kit/humanloop 0.3.39 → 0.4.0

package/dist/api.d.ts

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

package/dist/api.js

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

package/dist/inbox/controller.d.ts

@@ -1,7 +1,6 @@
-import type { InteractionResponse, TicketSummary } from '../types.js';
+import type { InteractionResponse, TicketSummary, VisualProvider } from '../types.js';
 import type { Key } from '../tui/terminal.js';
 import { startWebServer } from '../browser/server.js';
-import { visualGeneratorForConversationSession } from '../visuals/conversation.js';
 export interface InboxControllerOptions {
     roots?: string[];
     cols?: number;
@@ -10,8 +9,7 @@ export interface InboxControllerOptions {
     completeDeck?: (dir: string, responses: InteractionResponse[], token: string) => Promise<unknown>;
     startDeckBrowser?: typeof startWebServer;
     openBrowser?: (url: string) => void;
-    /** Test seam; production uses the standard conversation-backed visual generator. */
-    visualGeneratorForSession?: typeof visualGeneratorForConversationSession;
+    visualProvider?: VisualProvider;
 }
 type Screen = 'list' | 'detail';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
@@ -39,6 +37,8 @@ export declare class InboxController {
     private deckBrowserGeneration;
     private claim;
     private reconciling;
+    private visualReconciling;
+    private readonly visualCleanupExecutor;
     private suspended;
     private submittingDir;
     private stdinListener;
@@ -94,6 +94,11 @@ export declare class InboxController {
     /** Owner-boundary reconciliation for resolved results still lacking an ack.
      *  Guarded so overlapping fs events cannot stack concurrent scans. */
     private reconcileRoots;
+    /** Reconciliation owns stale-claim retirement and durable cleanup, never a Visual start. */
+    private reconcileVisualWork;
+    /** Automatic ticket capability is deliberately marker + current-root-handler only. */
+    private visualProviderFor;
+    private startTicketVisual;
     private leaveDetail;
     private select;
     private scrollPreview;

package/dist/inbox/controller.js

@@ -1,4 +1,5 @@
 import { readFileSync, watch } from 'node:fs';
+import { join } from 'node:path';
 import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
 import { diffFrame } from '../tui/render.js';
 import { renderMarkdown } from '../render/termrender.js';
@@ -13,13 +14,68 @@ import { inboxRootsDirectory, listInboxRoots, registeredInboxRoot } from './regi
 import { claimTicket, heartbeatClaim, releaseClaim } from './claim.js';
 import { completeDeck, readTicketResult, ticketRoot } from './tickets.js';
 import { reconcileCompletions } from './completion.js';
-import { clearProgress, deckPath, progressPath, readJson, responsePath, reviewPath } from './convention.js';
+import { clearProgress, deckPath, progressPath, readJson, responsePath, reviewPath, visualsDir } from './convention.js';
 import { DeckAdapter } from './deck-adapter.js';
 import { validateDeck } from './deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
-import { visualGeneratorForConversationSession } from '../visuals/conversation.js';
 import { editBufferInEditor } from '../editor/roundtrip.js';
 import { cancelFollowUp, readFollowUp, requestFollowUp } from './followup.js';
+import { cancelVisualRequest, dispatchVisualCleanup, listVisualCleanupObligationsForRoot, readVisualResult, reconcileStaleVisualRequestsForRoot, reconcileVisualRequestsForTicket, startVisualRequest, VISUAL_CAPABILITY, } from './visual.js';
+/** One controller-owned retry loop for durable cancellation only. */
+class VisualCleanupExecutor {
+    roots;
+    timer;
+    dispatching = new Set();
+    stopped = false;
+    constructor(roots) {
+        this.roots = roots;
+    }
+    reconcile() {
+        if (this.stopped)
+            return;
+        let tasks = [];
+        for (const root of this.roots()) {
+            try {
+                tasks.push(...listVisualCleanupObligationsForRoot(root));
+            }
+            catch { /* the next root reconciliation retries durable work */ }
+        }
+        tasks = tasks.filter((task) => !this.dispatching.has(this.key(task)));
+        const now = Date.now();
+        for (const task of tasks.filter((candidate) => Date.parse(candidate.nextAttemptAt) <= now))
+            this.dispatch(task);
+        this.arm(tasks.filter((task) => !this.dispatching.has(this.key(task))));
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    dispatch(task) {
+        const key = this.key(task);
+        if (this.dispatching.has(key))
+            return;
+        this.dispatching.add(key);
+        void dispatchVisualCleanup(task.root, task.dir, task.requestId).catch(() => undefined).finally(() => {
+            this.dispatching.delete(key);
+            this.reconcile();
+        });
+    }
+    arm(tasks) {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        const earliest = tasks.reduce((next, task) => {
+            const due = Date.parse(task.nextAttemptAt);
+            return Number.isFinite(due) && (next === undefined || due < next) ? due : next;
+        }, undefined);
+        if (earliest === undefined)
+            return;
+        this.timer = setTimeout(() => { this.timer = undefined; this.reconcile(); }, Math.max(0, earliest - Date.now()));
+    }
+    key(task) { return `${task.root}\u0000${task.dir}\u0000${task.requestId}`; }
+}
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
 export class InboxController {
     options;
@@ -45,6 +101,8 @@ export class InboxController {
     deckBrowserGeneration = 0;
     claim;
     reconciling = false;
+    visualReconciling = false;
+    visualCleanupExecutor;
     suspended = false;
     submittingDir;
     stdinListener;
@@ -64,7 +122,9 @@ export class InboxController {
         const size = getTerminalSize();
         this.cols = options.cols ?? size.cols;
         this.rows = options.rows ?? size.rows;
+        this.visualCleanupExecutor = new VisualCleanupExecutor(() => this.resolvedRoots());
         this.rescan();
+        this.reconcileVisualWork();
     }
     snapshot() {
         return { items: [...this.items], selectedDir: this.selectedDir, screen: this.screen, inputBuffer: this.adapter?.inputBuffer() };
@@ -196,13 +256,20 @@ export class InboxController {
             return;
         }
         this.claim = { dir: item.dir, token: claim.token };
-        const deck = readJson(deckPath(item.dir));
-        if (deck === null) {
+        const deck = this.readDeck(item.dir);
+        if (deck === undefined) {
             releaseClaim(item.dir, claim.token);
             this.claim = undefined;
             this.invalidate();
             return;
         }
+        const root = ticketRoot(item.dir);
+        if (root !== null) {
+            // A newly acquired claim makes every older running generation stale
+            // before the panel can mint its own work. This only dispatches cleanup.
+            const retirement = reconcileVisualRequestsForTicket(root, item.dir, claim.token);
+            void retirement.delivery.finally(() => this.visualCleanupExecutor.reconcile());
+        }
         // Notifications use the same canonical deck panel as every other deck:
         // opening is not acknowledgement; panel completion is.
         this.activeDeck = deck;
@@ -214,7 +281,7 @@ export class InboxController {
             cols: this.detailSize().cols,
             rows: this.detailSize().rows,
             onDirty: () => this.repaint(),
-            generateVisual: deck.source?.originatingConversationSessionId === undefined ? undefined : (this.options.visualGeneratorForSession ?? visualGeneratorForConversationSession)(deck.source.originatingConversationSessionId),
+            visualProvider: this.visualProviderFor(item.dir, deck, claim.token),
             onEditorRequest: () => this.editActiveDeckInput(),
             followUpAvailable: followUp.available,
             onFollowUpRequest: followUp.onRequest,
@@ -282,7 +349,8 @@ export class InboxController {
         this.activeDeck = deck;
         const followUp = this.followUpHandlers(this.claim.dir, deck);
         this.adapter.setFollowUpHandlers(followUp.available, followUp.onRequest, followUp.onCancel);
-        this.adapter.reload(deck);
+        // Reload replaces the capability before it mints the next panel generation.
+        this.adapter.reload(deck, this.visualProviderFor(this.claim.dir, deck, this.claim.token));
         if (followUp.available)
             this.adapter.setFollowUpState(this.followUpViewState(this.claim.dir));
         this.repaint();
@@ -462,6 +530,7 @@ export class InboxController {
         this.deckBrowser = undefined;
         void browser?.stop();
         this.leaveDetail();
+        this.visualCleanupExecutor.stop();
         for (const watcher of this.watchers)
             watcher.close();
         this.watchers = [];
@@ -587,6 +656,97 @@ export class InboxController {
                 this.reconciling = false;
             }
         })();
+        this.reconcileVisualWork();
+    }
+    /** Reconciliation owns stale-claim retirement and durable cleanup, never a Visual start. */
+    reconcileVisualWork() {
+        if (this.visualReconciling)
+            return;
+        this.visualReconciling = true;
+        const roots = this.resolvedRoots();
+        void (async () => {
+            try {
+                const deliveries = roots.flatMap((root) => {
+                    try {
+                        return reconcileStaleVisualRequestsForRoot(root).map((entry) => entry.delivery);
+                    }
+                    catch {
+                        return [];
+                    }
+                });
+                await Promise.all(deliveries);
+            }
+            finally {
+                this.visualReconciling = false;
+                this.visualCleanupExecutor.reconcile();
+            }
+        })();
+    }
+    /** Automatic ticket capability is deliberately marker + current-root-handler only. */
+    visualProviderFor(dir, deck, claimToken) {
+        // An inline provider is intentional host injection, independent of ticket capability.
+        if (this.options.visualProvider !== undefined)
+            return this.options.visualProvider;
+        const root = ticketRoot(dir);
+        if (root === null || deck.source?.visual !== VISUAL_CAPABILITY || registeredInboxRoot(root)?.visualHandler === undefined)
+            return undefined;
+        return (request) => this.startTicketVisual(root, dir, claimToken, request);
+    }
+    startTicketVisual(root, dir, claimToken, request) {
+        let watcher;
+        let settled = false;
+        let settle;
+        const result = new Promise((resolve) => { settle = resolve; });
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            watcher?.close();
+            watcher = undefined;
+            settle(outcome);
+        };
+        let started;
+        try {
+            started = startVisualRequest({ root, dir, claimToken, request });
+        }
+        catch (error) {
+            finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+            return { result, cancel: () => { } };
+        }
+        const reread = () => {
+            if (settled)
+                return;
+            try {
+                const outcome = readVisualResult(root, dir, request.requestId);
+                if (outcome === null)
+                    return;
+                finish(outcome.status === 'ready'
+                    ? { status: 'ready', markdown: outcome.markdown }
+                    : { status: 'error', error: outcome.error });
+            }
+            catch (error) {
+                finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+            }
+        };
+        try {
+            // Install the watch before the first durable reread so a publication in
+            // the narrow setup window is either observed or found by that reread.
+            watcher = watch(join(visualsDir(dir), request.requestId), () => reread());
+            watcher.once('error', (error) => finish({ status: 'error', error: error.message }));
+            reread();
+        }
+        catch (error) {
+            finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+        }
+        void started.delivery.then(reread, (error) => finish({ status: 'error', error: error instanceof Error ? error.message : String(error) }));
+        return {
+            result,
+            cancel: () => {
+                watcher?.close();
+                watcher = undefined;
+                void cancelVisualRequest(root, dir, request.requestId).finally(() => this.visualCleanupExecutor.reconcile());
+            },
+        };
     }
     leaveDetail(release = true) {
         this.deckBrowserGeneration++;
@@ -595,6 +755,7 @@ export class InboxController {
         this.deckBrowserStarting = false;
         this.adapter?.close();
         this.adapter = undefined;
+        this.visualCleanupExecutor.reconcile();
         this.activeDeck = undefined;
         this.selectedWatcher?.close();
         this.selectedWatcher = undefined;

package/dist/inbox/convention.d.ts

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

package/dist/inbox/convention.js

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

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

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

package/dist/inbox/deck-adapter.js

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

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

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

package/dist/inbox/deck-schema.js

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

package/dist/inbox/registry.d.ts

@@ -9,6 +9,7 @@ export interface InboxRootRegistration {
     owner: string;
     handler?: CompletionHandler;
     followUpHandler?: CompletionHandler;
+    visualHandler?: CompletionHandler;
 }
 export interface InboxRootStatus extends InboxRootRegistration {
     available: boolean;
@@ -18,6 +19,7 @@ export interface RegisterInboxRootOptions {
     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) {
@@ -30,6 +30,7 @@ function validateRegistration(raw) {
             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 {
@@ -50,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), followUpHandler: validateHandler(opts.followUpHandler) };
+        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, followupRequestPath, followupResultPath, 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), followupRequestPath(dir), followupResultPath(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'))); }
@@ -191,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);