@crouton-kit/humanloop 0.3.33 → 0.3.35

package/dist/inbox/registry.js

@@ -0,0 +1,97 @@
+import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { atomicWriteJson, readJson, withExclusiveDirectoryLock } from './convention.js';
+function stateHome() { return process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state'); }
+export function inboxRootsDirectory() { return join(stateHome(), 'humanloop', 'inbox-roots'); }
+function recordPath(root) { return join(inboxRootsDirectory(), createHash('sha256').update(root).digest('hex')); }
+function canonicalRoot(root) { try {
+    return realpathSync(root);
+}
+catch {
+    return resolve(root);
+} }
+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');
+    return { command: handler.command, args: [...handler.args] };
+}
+function validateRegistration(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const value = 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) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Create/canonicalize a root and claim its user-scoped registration. */
+export function registerInboxRoot(opts) {
+    if (!opts.owner.trim())
+        throw new Error('inbox root owner must be non-empty');
+    mkdirSync(resolve(opts.root), { recursive: true, mode: 0o700 });
+    const root = realpathSync(opts.root);
+    const path = recordPath(root);
+    mkdirSync(inboxRootsDirectory(), { recursive: true, mode: 0o700 });
+    return withExclusiveDirectoryLock(`${path}.lock`, () => {
+        const existing = validateRegistration(readJson(path));
+        if (existing !== null && existing.root === root && existing.owner !== opts.owner)
+            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) };
+        atomicWriteJson(path, registration);
+        chmodSync(path, 0o600);
+        return registration;
+    });
+}
+/** Removes a matching available root through its real path, or an unavailable record by its stored canonical path. */
+export function unregisterInboxRoot(root, owner) {
+    const canonical = canonicalRoot(root);
+    const path = recordPath(canonical);
+    return withExclusiveDirectoryLock(`${path}.lock`, () => {
+        const existing = validateRegistration(readJson(path));
+        if (existing === null || existing.root !== canonical || existing.owner !== owner)
+            return false;
+        unlinkSync(path);
+        return true;
+    });
+}
+export function listInboxRoots() {
+    let files;
+    try {
+        files = readdirSync(inboxRootsDirectory());
+    }
+    catch {
+        return [];
+    }
+    const roots = [];
+    for (const file of files) {
+        const record = validateRegistration(readJson(join(inboxRootsDirectory(), file)));
+        if (record !== null)
+            roots.push({ ...record, available: existsSync(record.root) });
+    }
+    return roots.sort((a, b) => a.root.localeCompare(b.root));
+}
+export function registeredInboxRoot(root) {
+    let canonical;
+    try {
+        canonical = realpathSync(root);
+    }
+    catch {
+        return null;
+    }
+    const record = validateRegistration(readJson(recordPath(canonical)));
+    return record?.root === canonical ? record : null;
+}
+/** The managed SDK root is durable, user-scoped, and owned by humanloop. */
+export function managedInboxRoot() {
+    return registerInboxRoot({ root: join(stateHome(), 'humanloop', 'inbox'), owner: 'humanloop' });
+}

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

@@ -0,0 +1,24 @@
+import { type TicketClaim } from './claim.js';
+import { type ReviewOptions } from '../editor/review.js';
+import type { ReviewDescriptor, TicketResult } from '../types.js';
+export interface ReviewAdapterOptions {
+    dir: string;
+    descriptor: ReviewDescriptor;
+    claim: TicketClaim;
+    editor?: ReviewOptions['editor'];
+    onSubmitted?: (result: TicketResult) => Promise<void> | void;
+    /** Human pressed Option/Alt+I inside the editor: close the whole inbox. */
+    onClose?: () => Promise<void> | void;
+}
+/** Controller-owned native review child. It persists drafts but delegates the sole final write to tickets.ts. */
+export declare class ReviewAdapter {
+    private readonly opts;
+    private readonly abortController;
+    private readonly heartbeat;
+    private running;
+    private stopped;
+    constructor(opts: ReviewAdapterOptions);
+    start(): Promise<TicketResult | null>;
+    /** Toggle, cancellation, and controller teardown all take this same path. */
+    stop(): Promise<void>;
+}

package/dist/inbox/review-adapter.js

@@ -0,0 +1,57 @@
+import { completeReview } from './tickets.js';
+import { heartbeatClaim, releaseClaim } from './claim.js';
+import { progressPath } from './convention.js';
+import { launchReview } from '../editor/review.js';
+/** Controller-owned native review child. It persists drafts but delegates the sole final write to tickets.ts. */
+export class ReviewAdapter {
+    opts;
+    abortController = new AbortController();
+    heartbeat;
+    running = null;
+    stopped = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.heartbeat = setInterval(() => {
+            if (!this.stopped)
+                heartbeatClaim(this.opts.dir, this.opts.claim.token);
+        }, 10_000);
+    }
+    start() {
+        if (this.running !== null)
+            return this.running;
+        let canonical = null;
+        this.running = launchReview(this.opts.descriptor.file, {
+            output: progressPath(this.opts.dir),
+            jobDir: this.opts.dir,
+            editor: this.opts.editor,
+            signal: this.abortController.signal,
+            onClose: this.opts.onClose,
+            onPropose: async (proposal) => {
+                if (this.stopped || this.abortController.signal.aborted)
+                    return;
+                const completed = await completeReview(this.opts.dir, proposal, this.opts.claim.token);
+                canonical = completed.result;
+                await this.opts.onSubmitted?.(canonical);
+            },
+        }).then(() => canonical).finally(() => {
+            clearInterval(this.heartbeat);
+            releaseClaim(this.opts.dir, this.opts.claim.token);
+            this.stopped = true;
+        });
+        return this.running;
+    }
+    /** Toggle, cancellation, and controller teardown all take this same path. */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.abortController.abort();
+        try {
+            await this.running;
+        }
+        finally {
+            clearInterval(this.heartbeat);
+            releaseClaim(this.opts.dir, this.opts.claim.token);
+        }
+    }
+}

package/dist/inbox/scan.d.ts

@@ -1,2 +1,3 @@
-import type { InboxItem } from '../types.js';
-export declare function scanInbox(roots: string[]): InboxItem[];
+import type { TicketSummary } from '../types.js';
+/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
+export declare function scanInbox(roots?: string[]): TicketSummary[];

package/dist/inbox/scan.js

@@ -1,62 +1,90 @@
-import { readdirSync, statSync } from 'fs';
-import { resolve, basename } from 'path';
-import { deckPath, isResolved, isClaimed, readJson } from './convention.js';
-// ── scanInbox ─────────────────────────────────────────────────────────────────
+import { readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { claimPath, deckPath, isResolved, readJson, reviewPath } from './convention.js';
+import { validateDeck, validateReviewDescriptor } from './deck-schema.js';
+import { listInboxRoots } from './registry.js';
+function claimSummary(dir) {
+    const claim = readJson(claimPath(dir));
+    if (claim === null || typeof claim.host !== 'string' || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
+        return undefined;
+    return { owner: claim.host, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt };
+}
+function deckSummary(dir, id) {
+    const raw = readJson(deckPath(dir));
+    if (raw === null)
+        return null;
+    let deck;
+    try {
+        deck = validateDeck(raw);
+    }
+    catch {
+        return null;
+    }
+    const first = deck.interactions[0];
+    if (first === undefined)
+        return null;
+    let blockedSince = deck.source?.blockedSince;
+    if (blockedSince === undefined) {
+        try {
+            blockedSince = statSync(deckPath(dir)).mtime.toISOString();
+        }
+        catch {
+            return null;
+        }
+    }
+    return { dir, id, kind: 'deck', title: deck.title ?? first.title, subtitle: first.subtitle, interactionKind: first.kind, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
+}
+function reviewSummary(dir, id) {
+    const raw = readJson(reviewPath(dir));
+    if (raw === null)
+        return null;
+    let review;
+    try {
+        review = validateReviewDescriptor(raw);
+    }
+    catch {
+        return null;
+    }
+    return { dir, id, kind: 'review', title: review.title, file: review.file, output: review.output, source: review.source, blockedSince: review.blockedSince, claim: claimSummary(dir) };
+}
+/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
 export function scanInbox(roots) {
+    const selectedRoots = roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
+    const seen = new Set();
     const items = [];
-    for (const root of roots) {
+    for (const root of selectedRoots) {
+        let canonicalRoot;
+        try {
+            canonicalRoot = realpathSync(root);
+        }
+        catch {
+            continue;
+        }
         let entries;
         try {
-            entries = readdirSync(root);
+            entries = readdirSync(canonicalRoot);
         }
         catch {
-            // root doesn't exist or isn't readable — skip silently
             continue;
         }
         for (const entry of entries) {
-            const dir = resolve(root, entry);
+            const dir = resolve(canonicalRoot, entry);
+            let canonicalDir;
             try {
-                const stat = statSync(dir);
-                if (!stat.isDirectory())
+                if (!statSync(dir).isDirectory())
                     continue;
+                canonicalDir = realpathSync(dir);
             }
             catch {
                 continue;
             }
-            // Skip resolved or actively claimed dirs
-            if (isResolved(dir) || isClaimed(dir))
-                continue;
-            const dp = deckPath(dir);
-            const deck = readJson(dp);
-            if (deck === null)
+            if (resolve(canonicalDir, '..') !== canonicalRoot || seen.has(canonicalDir) || isResolved(canonicalDir))
                 continue;
-            // Derive blockedSince: prefer deck.source.blockedSince, fall back to mtime
-            let blockedSince;
-            if (deck.source?.blockedSince !== undefined) {
-                blockedSince = deck.source.blockedSince;
-            }
-            else {
-                try {
-                    blockedSince = new Date(statSync(dp).mtime).toISOString();
-                }
-                catch {
-                    blockedSince = new Date().toISOString();
-                }
-            }
-            const firstInteraction = deck.interactions[0];
-            const item = {
-                dir,
-                id: firstInteraction?.id ?? basename(dir),
-                title: deck.title ?? firstInteraction?.title,
-                subtitle: firstInteraction?.subtitle,
-                kind: firstInteraction?.kind,
-                source: deck.source,
-                blockedSince,
-            };
-            items.push(item);
+            seen.add(canonicalDir);
+            const item = deckSummary(canonicalDir, basename(canonicalDir)) ?? reviewSummary(canonicalDir, basename(canonicalDir));
+            if (item !== null)
+                items.push(item);
         }
     }
-    // Sort ascending by blockedSince (ISO string compare is monotonic)
-    items.sort((a, b) => (a.blockedSince < b.blockedSince ? -1 : a.blockedSince > b.blockedSince ? 1 : 0));
-    return items;
+    return items.sort((a, b) => b.blockedSince.localeCompare(a.blockedSince) || a.id.localeCompare(b.id));
 }

package/dist/inbox/tickets.d.ts

@@ -0,0 +1,63 @@
+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;
+export interface SubmitDeckOptions {
+    root: string;
+    id: string;
+    deck: Deck;
+}
+export declare function submitDeck(opts: SubmitDeckOptions): {
+    id: string;
+    dir: string;
+    kind: 'deck';
+};
+export interface SubmitReviewOptions {
+    root: string;
+    id: string;
+    review: Omit<ReviewDescriptor, 'schema' | 'file' | 'output' | 'blockedSince'> & {
+        file: string;
+        output?: string;
+        blockedSince?: string;
+    };
+}
+export declare function submitReview(opts: SubmitReviewOptions): {
+    id: string;
+    dir: string;
+    kind: 'review';
+};
+export declare function finalizeDeck(dir: string, responses: DeckTicketResult['responses'], claimToken: string, completedAt?: string): {
+    won: boolean;
+    result: TicketResult;
+};
+export declare function finalizeReview(dir: string, feedback: FeedbackResult, claimToken: string, completedAt?: string): {
+    won: boolean;
+    result: TicketResult;
+    descriptor: ReviewDescriptor;
+};
+export declare function cancelTicketResult(dir: string, opts?: {
+    reason?: string;
+    actor?: string;
+}): {
+    status: 'canceled' | 'already_resolved';
+    result: TicketResult;
+};
+export declare function ticketRoot(dir: string): string | null;
+/** Finalize and immediately cross the trusted root completion boundary. */
+export declare function completeDeck(dir: string, responses: DeckTicketResult['responses'], claimToken: string): Promise<{
+    won: boolean;
+    result: TicketResult;
+}>;
+/** Finalize a review, then let completion own its projection and notification boundary. */
+export declare function completeReview(dir: string, feedback: FeedbackResult, claimToken: string): Promise<{
+    won: boolean;
+    result: TicketResult;
+    descriptor: ReviewDescriptor;
+}>;
+/** Cancellation races finalization but never requires or removes another claim. */
+export declare function cancelTicket(dir: string, opts?: {
+    reason?: string;
+    actor?: string;
+}): Promise<{
+    status: 'canceled' | 'already_resolved';
+    result: TicketResult;
+}>;

package/dist/inbox/tickets.js

@@ -0,0 +1,247 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } 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 { 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';
+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();
+const iso = z.string().datetime({ offset: true });
+const feedbackSchema = z.object({ file: z.string().min(1).refine(isAbsolute, 'file must be absolute').refine((file) => resolve(file) === file, 'file must be canonical'), submitted: z.literal(true), approved: z.boolean(), comments: z.array(feedbackCommentSchema), submittedAt: iso, savedAt: iso }).strict().superRefine((result, ctx) => {
+    if (result.approved !== (result.comments.length === 0))
+        ctx.addIssue({ code: 'custom', message: 'approved must match empty comments' });
+    result.comments.forEach((comment, index) => {
+        if (comment.endLine < comment.line)
+            ctx.addIssue({ code: 'custom', message: 'endLine must be >= line', path: ['comments', index, 'endLine'] });
+        if ((comment.colStart === undefined) !== (comment.colEnd === undefined))
+            ctx.addIssue({ code: 'custom', message: 'columns must be supplied together', path: ['comments', index] });
+        if (comment.line === comment.endLine && comment.colStart !== undefined && comment.colEnd !== undefined && comment.colEnd <= comment.colStart)
+            ctx.addIssue({ code: 'custom', message: 'colEnd must exceed colStart', path: ['comments', index, 'colEnd'] });
+    });
+});
+const deckResultSchema = z.object({ schema: z.literal('humanloop.response/v2'), kind: z.literal('deck'), responses: z.array(responseSchema), summary: z.string(), completedAt: iso }).strict();
+const reviewResultSchema = z.object({ schema: z.literal('humanloop.review-response/v1'), kind: z.literal('review'), result: feedbackSchema, completedAt: iso }).strict();
+const canceledResultSchema = z.object({ schema: z.literal('humanloop.cancel/v1'), kind: z.literal('canceled'), canceledAt: iso, reason: z.string().optional(), actor: z.string().optional() }).strict();
+/** Strict decoder for the only canonical final marker. */
+export function readTicketResult(dirOrResponsePath) {
+    const path = basename(dirOrResponsePath) === 'response.json' ? dirOrResponsePath : responsePath(dirOrResponsePath);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const parsed = deckResultSchema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    const review = reviewResultSchema.safeParse(raw);
+    if (review.success)
+        return review.data;
+    const canceled = canceledResultSchema.safeParse(raw);
+    return canceled.success ? canceled.data : null;
+}
+function rootAndDir(root, id) {
+    const registration = registeredInboxRoot(root);
+    if (registration === null)
+        throw new Error('interaction root is not registered');
+    const parsedId = ticketId.parse(id);
+    const dir = resolve(registration.root, parsedId);
+    if (dirname(dir) !== registration.root)
+        throw new Error('ticket directory must be a direct child of its registered root');
+    return { root: registration.root, dir };
+}
+function ticketDir(root, id) {
+    const candidate = rootAndDir(root, id);
+    let created = false;
+    if (!existsSync(candidate.dir)) {
+        mkdirSync(candidate.dir, { mode: 0o700 });
+        created = true;
+    }
+    const dir = realpathSync(candidate.dir);
+    if (dirname(dir) !== candidate.root)
+        throw new Error('ticket directory must canonically be a direct child of its registered root');
+    return { dir, created };
+}
+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);
+}
+function requireRegisteredTicket(dir) {
+    const canonical = realpathSync(dir);
+    const root = dirname(canonical);
+    const registration = registeredInboxRoot(root);
+    if (registration === null || registration.root !== root || basename(canonical) === '')
+        throw new Error('ticket must be a canonical direct child of a registered root');
+    if (!existsSync(deckPath(canonical)) && !existsSync(reviewPath(canonical)))
+        throw new Error('ticket has no request descriptor');
+    return { root, dir: canonical };
+}
+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);
+    }
+}
+export function submitDeck(opts) {
+    // Validate shape before mutating caller-owned interaction directories.
+    validateDeck(opts.deck);
+    const { dir, created } = ticketDir(opts.root, opts.id);
+    try {
+        if (hasTicketProtocolState(dir))
+            throw new Error(`ticket protocol state already exists: ${dir}`);
+        const deck = validateDeck(resolveDeckBodyPaths(opts.deck, dir));
+        const stamped = { ...deck, source: { ...(deck.source ?? {}), blockedSince: deck.source?.blockedSince ?? new Date().toISOString() } };
+        publishRequest(deckPath(dir), stamped);
+        return { id: opts.id, dir, kind: 'deck' };
+    }
+    catch (error) {
+        discardCreatedTicket(dir, created);
+        throw error;
+    }
+}
+export function submitReview(opts) {
+    if (!isAbsolute(opts.review.file) || !existsSync(opts.review.file))
+        throw new Error('review file must be an existing absolute markdown file');
+    if (!/\.md(?:own)?$/i.test(opts.review.file))
+        throw new Error('review file must be markdown');
+    const source = realpathSync(opts.review.file);
+    const { dir, created } = ticketDir(opts.root, opts.id);
+    try {
+        if (hasTicketProtocolState(dir))
+            throw new Error(`ticket protocol state already exists: ${dir}`);
+        const descriptor = validateReviewProjection(dir, { schema: 'humanloop.review/v1', file: source, output: resolve(opts.review.output ?? `${dir}/feedback.json`), title: opts.review.title, source: opts.review.source, blockedSince: opts.review.blockedSince ?? new Date().toISOString() });
+        publishRequest(reviewPath(dir), descriptor);
+        return { id: opts.id, dir, kind: 'review' };
+    }
+    catch (error) {
+        discardCreatedTicket(dir, created);
+        throw error;
+    }
+}
+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);
+    }
+}
+function requireDeck(dir) { return validateDeck(JSON.parse(readFileSync(deckPath(dir), 'utf8'))); }
+function requireReview(dir) { return validateReviewDescriptor(JSON.parse(readFileSync(reviewPath(dir), 'utf8'))); }
+function validateDeckResponses(deck, raw) {
+    const responses = z.array(responseSchema).parse(raw);
+    const interactions = new Map(deck.interactions.map((interaction) => [interaction.id, interaction]));
+    const seen = new Set();
+    for (const response of responses) {
+        const interaction = interactions.get(response.id);
+        if (interaction === undefined || seen.has(response.id))
+            throw new Error(`response does not match a unique deck interaction: ${response.id}`);
+        seen.add(response.id);
+        const optionIds = new Set(interaction.options.map((option) => option.id));
+        if (response.selectedOptionId !== undefined && (!optionIds.has(response.selectedOptionId) || interaction.multiSelect === true))
+            throw new Error(`invalid single-select response for ${response.id}`);
+        if (response.selectedOptionIds !== undefined && (interaction.multiSelect !== true || response.selectedOptionIds.some((id) => !optionIds.has(id)) || new Set(response.selectedOptionIds).size !== response.selectedOptionIds.length))
+            throw new Error(`invalid multi-select response for ${response.id}`);
+        if (response.freetext !== undefined && interaction.allowFreetext !== true)
+            throw new Error(`freetext is not allowed for ${response.id}`);
+        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}`);
+    }
+    return responses;
+}
+function requireClaimOwnership(dir, token) {
+    if (readTicketClaim(dir)?.token !== token)
+        throw new Error('only the current claim holder may submit a result');
+}
+function clearOwnedWork(dir, claimToken) { clearProgress(dir); releaseClaimLocked(dir, claimToken); }
+export function finalizeDeck(dir, responses, claimToken, completedAt = new Date().toISOString()) {
+    const ticket = requireRegisteredTicket(dir);
+    return withTicketLock(ticket.dir, () => {
+        requireClaimOwnership(ticket.dir, claimToken);
+        const deck = requireDeck(ticket.dir);
+        const parsedResponses = validateDeckResponses(deck, responses);
+        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);
+        return { won, result: won ? result : readTicketResult(ticket.dir) ?? result };
+    });
+}
+export function finalizeReview(dir, feedback, claimToken, completedAt = new Date().toISOString()) {
+    const ticket = requireRegisteredTicket(dir);
+    return withTicketLock(ticket.dir, () => {
+        requireClaimOwnership(ticket.dir, claimToken);
+        const descriptor = requireReview(ticket.dir);
+        const parsed = feedbackSchema.parse(feedback);
+        if (realpathSync(parsed.file) !== descriptor.file)
+            throw new Error('review result file does not match descriptor');
+        const result = { schema: 'humanloop.review-response/v1', kind: 'review', result: parsed, completedAt };
+        const won = exclusiveResult(ticket.dir, result);
+        clearOwnedWork(ticket.dir, claimToken);
+        return { won, result: won ? result : readTicketResult(ticket.dir) ?? result, descriptor };
+    });
+}
+export function cancelTicketResult(dir, opts = {}) {
+    const ticket = requireRegisteredTicket(dir);
+    return withTicketLock(ticket.dir, () => {
+        const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
+        const won = exclusiveResult(ticket.dir, result);
+        return { status: won ? 'canceled' : 'already_resolved', result: won ? result : readTicketResult(ticket.dir) ?? result };
+    });
+}
+export function ticketRoot(dir) {
+    try {
+        return requireRegisteredTicket(dir).root;
+    }
+    catch {
+        return null;
+    }
+}
+/** Finalize and immediately cross the trusted root completion boundary. */
+export async function completeDeck(dir, responses, claimToken) {
+    const completed = finalizeDeck(dir, responses, claimToken);
+    const root = ticketRoot(dir);
+    if (completed.won && root !== null)
+        await dispatchCompletion(root, dir);
+    return completed;
+}
+/** Finalize a review, then let completion own its projection and notification boundary. */
+export async function completeReview(dir, feedback, claimToken) {
+    const completed = finalizeReview(dir, feedback, claimToken);
+    const root = ticketRoot(dir);
+    if (completed.won && root !== null)
+        await dispatchCompletion(root, dir);
+    return completed;
+}
+/** Cancellation races finalization but never requires or removes another claim. */
+export async function cancelTicket(dir, opts = {}) {
+    const canceled = cancelTicketResult(dir, opts);
+    const root = ticketRoot(dir);
+    if (canceled.status === 'canceled' && root !== null)
+        await dispatchCompletion(root, dir);
+    return canceled;
+}

package/dist/inbox/tui.d.ts

@@ -1,9 +1,6 @@
-import type { InboxItem } from '../types.js';
+import type { TicketSummary } from '../types.js';
 export declare const KIND_ICON: Record<string, string>;
 export declare const KIND_COLOR: Record<string, string>;
 export declare function formatTimeAgo(iso: string): string;
-export declare function buildInboxLines(items: InboxItem[], width: number, selectedIndex: number): string[];
-export declare function pickFromInbox(items: InboxItem[], opts: {
-    cols: number;
-    rows: number;
-}): Promise<InboxItem | null>;
+/** Pure inbox rows; selection and terminal ownership belong to InboxController. */
+export declare function buildInboxLines(items: TicketSummary[], width: number, selectedIndex: number): string[];