@north-light/crouter 0.3.192 → 0.3.194

package/dist/core/human/summary.js

@@ -1,44 +1,61 @@
+import { isResponseBearingSlot } from './page-schema.js';
+function labelsOf(items, ids, labelKey) {
+    const byId = new Map((Array.isArray(items) ? items : [])
+        .filter((item) => typeof item === 'object' && item !== null)
+        .map((item) => [String(item['id']), typeof item[labelKey] === 'string' ? item[labelKey] : String(item['id'])]));
+    return (Array.isArray(ids) ? ids : []).map((id) => byId.get(String(id)) ?? String(id));
+}
+function pickedWithFreetext(picked, freetext) {
+    const text = typeof freetext === 'string' && freetext !== '' ? freetext : undefined;
+    const selection = picked.length > 0 ? picked.join(', ') : undefined;
+    if (selection !== undefined && text !== undefined)
+        return `${selection} — ${text}`;
+    return selection ?? text ?? '(no selection)';
+}
+function commentSuffix(response) {
+    const comments = response['comments'];
+    const count = Array.isArray(comments) ? comments.length : 0;
+    return count === 0 ? '' : ` (${count} comment${count === 1 ? '' : 's'})`;
+}
+function describeSlotResponse(slot, response) {
+    const value = response;
+    const config = slot.config;
+    switch (slot.kind) {
+        case 'options':
+            return `${pickedWithFreetext(labelsOf(config['options'], value['selectedOptionIds'], 'label'), value['freetext'])}${commentSuffix(value)}`;
+        case 'text': {
+            const text = typeof value['text'] === 'string' ? value['text'].replace(/\s+/g, ' ').trim() : '';
+            return `${text === '' ? '(empty)' : text}${commentSuffix(value)}`;
+        }
+        case 'table': {
+            const rows = (Array.isArray(value['selectedRowIds']) ? value['selectedRowIds'] : []).map(String);
+            const columns = labelsOf(config['columns'], value['selectedColumnIds'], 'label');
+            const parts = [...(rows.length > 0 ? [`rows ${rows.join(', ')}`] : []), ...(columns.length > 0 ? [`columns ${columns.join(', ')}`] : [])];
+            return `${parts.length === 0 ? '(no selection)' : parts.join('; ')}${commentSuffix(value)}`;
+        }
+        case 'cards': {
+            const picked = labelsOf(config['cards'], value['selectedCardIds'], 'title');
+            return `${picked.length === 0 ? '(no selection)' : picked.join(', ')}${commentSuffix(value)}`;
+        }
+        default:
+            // A product kind crtr does not render: its opaque response is the summary.
+            return JSON.stringify(value);
+    }
+}
 /**
- * Deterministic, no-LLM resolution summary — one line per answered
- * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
- * (envelope summary) and `writeResponse` (persisted into response.json at write
- * time).
+ * Deterministic, no-LLM page resolution summary — one line per answered slot in
+ * document order: `"<slot id>: <answer>"`. An acknowledgement (`responses: {}`)
+ * summarizes as the empty string.
  */
-export function buildSummary(deck, responses) {
-    const byId = new Map(responses.map((r) => [r.id, r]));
+export function buildPageSummary(manifest, responses) {
     const lines = [];
-    for (const it of deck.interactions) {
-        const r = byId.get(it.id);
-        if (r === undefined)
+    for (const slot of manifest.slots) {
+        if (!isResponseBearingSlot(slot) || slot.id === undefined)
             continue;
-        const ft = r.freetext !== undefined && r.freetext !== '' ? r.freetext : undefined;
-        let picked;
-        if (r.selectedOptionIds !== undefined) {
-            const oc = r.optionComments;
-            const parts = r.selectedOptionIds
-                .map((id) => it.options.find((o) => o.id === id))
-                .filter((o) => o !== undefined)
-                .map((o) => {
-                const note = oc !== undefined ? oc[o.id] : undefined;
-                return typeof note === 'string' && note.length > 0
-                    ? `${o.label} ("${note}")`
-                    : o.label;
-            });
-            picked = parts.length > 0 ? parts.join(', ') : undefined;
-        }
-        else if (r.selectedOptionId !== undefined) {
-            picked = it.options.find((o) => o.id === r.selectedOptionId)?.label;
-        }
-        let val;
-        if (picked !== undefined && ft !== undefined)
-            val = `${picked} — ${ft}`;
-        else if (picked !== undefined)
-            val = picked;
-        else if (ft !== undefined)
-            val = ft;
-        else
-            val = '(skipped)';
-        lines.push(`${it.title}: ${val}`);
+        const response = responses[slot.id];
+        if (response === undefined)
+            continue;
+        lines.push(`${slot.id}: ${describeSlotResponse(slot, response)}`);
     }
     return lines.join('\n');
 }

package/dist/core/human/tickets.d.ts

@@ -1,14 +1,43 @@
-import type { Deck, DeckTicketResult, ReviewDescriptor, TicketResult } from './types.js';
+import type { ReviewDescriptor, TicketResult } from './types.js';
+import { type PageDialect } from './page.js';
+import { type PageManifest, type PageResponses, type PageSource } from './page-schema.js';
 /** Strict decoder for the only canonical final marker. */
 export declare function readTicketResult(dir: string): TicketResult | null;
-export interface SubmitDeckOptions {
+export interface SubmitPageOptions {
     dir: string;
-    deck: Deck;
+    /** The authored page source; copied into the ticket directory as its `document`. */
+    sourceFile: string;
+    dialect: PageDialect;
+    source?: PageSource;
+    productKinds?: string[];
 }
-export declare function submitDeck(opts: SubmitDeckOptions): {
+/** One validated page, ready to publish into a ticket directory. */
+export interface PreparedPage {
+    dialect: PageDialect;
+    /** The authored source, verbatim, as the ticket's `document`. */
+    document: string;
+    manifest: PageManifest;
+}
+/** Validate one authored page source into publishable form. Reads only: a page
+ *  that fails authoring leaves nothing behind, so a caller that must create a
+ *  bridge node prepares first and creates it only once the page is known good.
+ *  The source is read exactly once, so the published document is the same bytes
+ *  the manifest was derived from even if the file changes underneath. */
+export declare function preparePage(opts: Omit<SubmitPageOptions, 'dir'>): PreparedPage;
+/** Publish one prepared page ticket: the authored source plus its manifest, exclusively. */
+export declare function publishPage(dir: string, prepared: PreparedPage): {
     id: string;
     dir: string;
-    kind: 'deck';
+    kind: 'page';
+    manifest: PageManifest;
+};
+/** Validate and publish one page ticket in a single step, for callers that own
+ *  the ticket directory before they have a page. */
+export declare function submitPage(opts: SubmitPageOptions): {
+    id: string;
+    dir: string;
+    kind: 'page';
+    manifest: PageManifest;
 };
 export interface SubmitReviewOptions {
     dir: string;
@@ -23,17 +52,38 @@ export declare function submitReview(opts: SubmitReviewOptions): {
     dir: string;
     kind: 'review';
 };
-/** Validate a deck resolution against its canonical ticket before claim takeover. */
-export declare function validateDeckTicketResponses(dir: string, responses: unknown): DeckTicketResult['responses'];
-export declare function completeDeck(dir: string, responses: DeckTicketResult['responses'], claimToken: string, completedAt?: string): {
+/** Validate a page resolution against its canonical ticket before claim takeover. */
+export declare function validatePageTicketResponses(dir: string, responses: unknown, productKinds?: string[]): PageResponses;
+/** The three terminal states of a page ticket, derived from its published result. */
+export declare function pageTicketState(dir: string): 'pending' | 'resolved' | 'canceled';
+/** Autosave partial page work. Every supplied response is validated; omitted slots are permitted. */
+export declare function writePageProgress(dir: string, responses: unknown, productKinds?: string[]): PageResponses;
+/** Saved partial work, or null when none exists. Malformed progress is an error, never silently discarded. */
+export declare function readPageProgress(dir: string, productKinds?: string[]): PageResponses | null;
+export interface PageTicket {
+    dir: string;
+    id: string;
+    manifest: PageManifest;
+    /** The authored source document, verbatim. */
+    document: string;
+    state: 'pending' | 'resolved' | 'canceled';
+    progress: PageResponses | null;
+}
+/** Read one addressable page ticket — pending, resolved or canceled alike. */
+export declare function readPageTicket(dir: string, productKinds?: string[]): PageTicket;
+export interface CompletePageOptions {
+    productKinds?: string[];
+    completedAt?: string;
+}
+export declare function completePage(dir: string, responses: unknown, claimToken: string, opts?: CompletePageOptions): {
     won: boolean;
     result: TicketResult;
 };
-/** Atomically take a ticket's claim over, complete it, and release the takeover claim. */
-export declare function takeoverAndCompleteDeck(dir: string, responses: DeckTicketResult['responses'], owner: {
+/** Atomically take a page ticket's claim over, complete it, and release the takeover claim. */
+export declare function takeoverAndCompletePage(dir: string, responses: unknown, owner: {
     host: string;
     pid: number;
-}): {
+}, opts?: CompletePageOptions): {
     won: boolean;
     result: TicketResult;
 };

package/dist/core/human/tickets.js

@@ -2,13 +2,14 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFil
 import { basename, isAbsolute, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { buildSummary } from './summary.js';
-import { atomicWriteJson, clearProgress, claimPath, deckPath, progressPath, publishJsonExclusive, requireTicket, responsePath, reviewPath } from './convention.js';
-import { validateDeck, validateReviewDescriptor, validateReviewProjection, resolveDeckBodyPaths } from './deck-schema.js';
+import { buildPageSummary } from './summary.js';
+import { atomicWriteJson, clearProgress, claimPath, pageManifestPath, pagePath, progressPath, publishJsonExclusive, requireTicket, responsePath, reviewPath } from './convention.js';
+import { validateReviewDescriptor, validateReviewProjection } from './review-schema.js';
+import { derivePageManifestFromDocument, parsePage, PageAuthoringError } from './page.js';
+import { validatePageResponses, validatePartialPageResponses } from './page-schema.js';
 import { signalInboxActivity } from './root.js';
 import { readTicketClaim, releaseClaimLocked, withTicketLock } from './claim.js';
 import { checkReviewableFile } from './visible-paths.js';
-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, reviewId: z.string().optional(), changed: z.boolean().optional(), baselineSha256: z.string().optional(), approvedSha256: z.string().optional(), companionNodeId: z.string().optional(), commentsTotal: z.number().int().nonnegative().optional(), commentsUnresolved: z.number().int().nonnegative().optional() }).strict().superRefine((result, ctx) => {
@@ -21,7 +22,9 @@ const feedbackSchema = z.object({ file: z.string().min(1).refine(isAbsolute, 'fi
             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 slotResponseSchema = z.record(z.string(), z.unknown());
+const pageResultSchema = z.object({ schema: z.literal('crtr.page-response/v1'), kind: z.literal('page'), responses: z.record(z.string(), slotResponseSchema), summary: z.string(), completedAt: iso }).strict();
+const pageProgressSchema = z.object({ kind: z.literal('page'), responses: z.record(z.string(), slotResponseSchema), savedAt: 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. */
@@ -33,9 +36,9 @@ export function readTicketResult(dir) {
     catch {
         return null;
     }
-    const parsed = deckResultSchema.safeParse(raw);
-    if (parsed.success)
-        return parsed.data;
+    const page = pageResultSchema.safeParse(raw);
+    if (page.success)
+        return page.data;
     const review = reviewResultSchema.safeParse(raw);
     if (review.success)
         return review.data;
@@ -43,24 +46,39 @@ export function readTicketResult(dir) {
     return canceled.success ? canceled.data : null;
 }
 function hasTicketProtocolState(dir) {
-    return [deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir)].some(existsSync);
+    return [pageManifestPath(dir), pagePath(dir, 'md'), pagePath(dir, 'html'), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir)].some(existsSync);
 }
 function publishRequest(path, value) {
     if (!publishJsonExclusive(path, value))
         throw new Error(`ticket request already exists: ${path}`);
 }
-export function submitDeck(opts) {
-    // Validate shape before mutating the bridge node's canvas directory.
-    validateDeck(opts.deck);
-    mkdirSync(opts.dir, { recursive: true, mode: 0o700 });
-    const dir = realpathSync(opts.dir);
-    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);
+/** Validate one authored page source into publishable form. Reads only: a page
+ *  that fails authoring leaves nothing behind, so a caller that must create a
+ *  bridge node prepares first and creates it only once the page is known good.
+ *  The source is read exactly once, so the published document is the same bytes
+ *  the manifest was derived from even if the file changes underneath. */
+export function preparePage(opts) {
+    if (!existsSync(opts.sourceFile))
+        throw new PageAuthoringError(`page source file does not exist: ${opts.sourceFile}`);
+    const document = readFileSync(opts.sourceFile, 'utf8');
+    const stamped = { ...(opts.source ?? {}), blockedSince: opts.source?.blockedSince ?? new Date().toISOString() };
+    return { dialect: opts.dialect, document, manifest: derivePageManifestFromDocument(document, opts.dialect, opts.productKinds ?? [], stamped) };
+}
+/** Publish one prepared page ticket: the authored source plus its manifest, exclusively. */
+export function publishPage(dir, prepared) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const ticket = realpathSync(dir);
+    if (hasTicketProtocolState(ticket))
+        throw new Error(`ticket protocol state already exists: ${ticket}`);
+    writeFileSync(pagePath(ticket, prepared.dialect), prepared.document, { flag: 'wx', mode: 0o600 });
+    publishRequest(pageManifestPath(ticket), prepared.manifest);
     signalInboxActivity();
-    return { id: basename(dir), dir, kind: 'deck' };
+    return { id: basename(ticket), dir: ticket, kind: 'page', manifest: prepared.manifest };
+}
+/** Validate and publish one page ticket in a single step, for callers that own
+ *  the ticket directory before they have a page. */
+export function submitPage(opts) {
+    return publishPage(opts.dir, preparePage(opts));
 }
 export function submitReview(opts) {
     // A review takes any reviewable text file: a .md artifact renders as a document,
@@ -83,39 +101,64 @@ export function submitReview(opts) {
 function exclusiveResult(dir, result) {
     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'))); }
-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}`);
+function requirePage(dir, productKinds) {
+    if (!existsSync(pageManifestPath(dir)))
+        throw new Error(`not a page ticket: ${dir}`);
+    return parsePage(dir, productKinds);
+}
+/** Validate a page resolution against its canonical ticket before claim takeover. */
+export function validatePageTicketResponses(dir, responses, productKinds = []) {
+    return validatePageResponses(requirePage(requireTicket(dir), productKinds), responses);
+}
+/** The three terminal states of a page ticket, derived from its published result. */
+export function pageTicketState(dir) {
+    const result = readTicketResult(dir);
+    if (result === null)
+        return 'pending';
+    return result.kind === 'canceled' ? 'canceled' : 'resolved';
+}
+function readPageProgressFor(dir, manifest) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(progressPath(dir), 'utf8'));
     }
-    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}`);
-        }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new Error(`page progress is not valid JSON: ${progressPath(dir)}`);
     }
-    return responses;
+    const parsed = pageProgressSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`page progress is malformed: ${progressPath(dir)}`);
+    // Saved work is validated on read as well as on write: a page whose manifest
+    // changed under it must fail loudly rather than hydrate an answer it no longer has.
+    return validatePartialPageResponses(manifest, parsed.data.responses);
+}
+/** Autosave partial page work. Every supplied response is validated; omitted slots are permitted. */
+export function writePageProgress(dir, responses, productKinds = []) {
+    const ticket = requireTicket(dir);
+    const validated = validatePartialPageResponses(requirePage(ticket, productKinds), responses);
+    atomicWriteJson(progressPath(ticket), { kind: 'page', responses: validated, savedAt: new Date().toISOString() });
+    return validated;
+}
+/** Saved partial work, or null when none exists. Malformed progress is an error, never silently discarded. */
+export function readPageProgress(dir, productKinds = []) {
+    const ticket = requireTicket(dir);
+    return readPageProgressFor(ticket, requirePage(ticket, productKinds));
 }
-/** Validate a deck resolution against its canonical ticket before claim takeover. */
-export function validateDeckTicketResponses(dir, responses) {
+/** Read one addressable page ticket — pending, resolved or canceled alike. */
+export function readPageTicket(dir, productKinds = []) {
     const ticket = requireTicket(dir);
-    return validateDeckResponses(requireDeck(ticket), responses);
+    const manifest = requirePage(ticket, productKinds);
+    return {
+        dir: ticket,
+        id: basename(ticket),
+        manifest,
+        document: readFileSync(pagePath(ticket, manifest.dialect), 'utf8'),
+        state: pageTicketState(ticket),
+        progress: readPageProgressFor(ticket, manifest),
+    };
 }
 function requireClaimOwnership(dir, token) {
     if (readTicketClaim(dir)?.token !== token)
@@ -123,18 +166,18 @@ function requireClaimOwnership(dir, token) {
 }
 function clearOwnedWork(dir, claimToken) { clearProgress(dir); releaseClaimLocked(dir, claimToken); }
 /** Caller holds `.ticket-lock`. */
-function completeDeckLocked(dir, responses, claimToken, completedAt = new Date().toISOString()) {
+function completePageLocked(dir, responses, claimToken, opts) {
     requireClaimOwnership(dir, claimToken);
-    const deck = requireDeck(dir);
-    const parsedResponses = validateDeckResponses(deck, responses);
-    const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: parsedResponses, summary: buildSummary(deck, parsedResponses), completedAt };
+    const manifest = requirePage(dir, opts.productKinds ?? []);
+    const parsedResponses = validatePageResponses(manifest, responses);
+    const result = { schema: 'crtr.page-response/v1', kind: 'page', responses: parsedResponses, summary: buildPageSummary(manifest, parsedResponses), completedAt: opts.completedAt ?? new Date().toISOString() };
     const won = exclusiveResult(dir, result);
     clearOwnedWork(dir, claimToken);
     return { won, result: won ? result : readTicketResult(dir) ?? result };
 }
-export function completeDeck(dir, responses, claimToken, completedAt) {
+export function completePage(dir, responses, claimToken, opts = {}) {
     const ticket = requireTicket(dir);
-    const completed = withTicketLock(ticket, () => completeDeckLocked(ticket, responses, claimToken, completedAt));
+    const completed = withTicketLock(ticket, () => completePageLocked(ticket, responses, claimToken, opts));
     if (completed.won)
         signalInboxActivity();
     return completed;
@@ -148,13 +191,13 @@ function takeoverClaim(dir, owner) {
     writeFileSync(claimPath(dir), `${JSON.stringify({ token, host: owner.host, pid: owner.pid, claimedAt: now, heartbeatAt: now })}\n`, { flag: 'wx', mode: 0o600 });
     return token;
 }
-/** Atomically take a ticket's claim over, complete it, and release the takeover claim. */
-export function takeoverAndCompleteDeck(dir, responses, owner) {
+/** Atomically take a page ticket's claim over, complete it, and release the takeover claim. */
+export function takeoverAndCompletePage(dir, responses, owner, opts = {}) {
     const ticket = requireTicket(dir);
     const completed = withTicketLock(ticket, () => {
         const token = takeoverClaim(ticket, owner);
         try {
-            return completeDeckLocked(ticket, responses, token);
+            return completePageLocked(ticket, responses, token, opts);
         }
         finally {
             releaseClaimLocked(ticket, token);

package/dist/core/human/types.d.ts

@@ -1,51 +1,12 @@
-export declare const INTERACTION_KINDS: readonly ["notify", "decision", "context", "error", "review"];
-export type InteractionKind = (typeof INTERACTION_KINDS)[number];
-export interface InteractionOption {
-    id: string;
-    label: string;
-    description?: string;
-    /** Auto-assigned by the TUI (assignShortcuts), never author-settable. */
-    shortcut?: string;
-}
-export interface InteractionPreAnswer {
-    selectedOptionId?: string;
-    selectedOptionIds?: string[];
-    freetext?: string;
-    /** One-line marker shown in the answered chrome. */
-    label?: string;
-}
-export interface Interaction {
-    id: string;
-    title: string;
-    subtitle: string;
-    body?: string;
-    bodyPath?: string;
-    options: InteractionOption[];
-    multiSelect?: boolean;
-    allowFreetext?: boolean;
-    freetextLabel?: string;
-    kind?: InteractionKind;
-    preAnswered?: InteractionPreAnswer;
-}
-export interface InteractionResponse {
-    id: string;
-    selectedOptionId?: string;
-    selectedOptionIds?: string[];
-    freetext?: string;
-    optionComments?: Record<string, string>;
-}
-export interface DeckSource {
+import type { PageResponses } from './page-schema.js';
+/** Provenance stamped onto every ticket request — page and review alike. */
+export interface TicketSource {
     sessionName?: string;
     askedBy?: string;
     blockedSince?: string;
     /** Originating canvas node id (CRTR_NODE_ID) when the ask was raised inside a crouter canvas node. */
     nodeId?: string;
 }
-export interface Deck {
-    title: string;
-    source?: DeckSource;
-    interactions: Interaction[];
-}
 export interface FeedbackComment {
     id: string;
     line: number;
@@ -65,17 +26,6 @@ export interface FeedbackResult {
     submittedAt?: string;
     savedAt: string;
 }
-/**
- * Resolution contract returned by `ask`/`inbox`. On-disk `response.json` stays
- * `{ responses, completedAt }`; `responsePath` points at it.
- */
-export interface ResolutionEnvelope {
-    summary: string;
-    responsePath: string;
-    schema: 'humanloop.response/v2';
-    responses: InteractionResponse[];
-    completedAt: string;
-}
 export interface ClaimSummary {
     owner: string;
     claimedAt: string;
@@ -87,34 +37,39 @@ interface TicketSummaryBase {
     title: string;
     subtitle: string;
     blockedSince: string;
-    source: DeckSource;
+    source: TicketSource;
     claim?: ClaimSummary;
 }
-export interface DeckTicketSummary extends TicketSummaryBase {
-    kind: 'deck';
-    interactionKind?: InteractionKind;
-    interactionCount: number;
-}
 export interface ReviewTicketSummary extends TicketSummaryBase {
     kind: 'review';
     file: string;
     output: string;
 }
+/** Page triage fields: a client picks a transcript rendering without a second fetch. */
+export interface PageTicketSummary extends TicketSummaryBase {
+    kind: 'page';
+    dialect: 'md' | 'html';
+    placement: 'inline' | 'panel';
+    steps: number;
+    slotKinds: string[];
+    awaitsResponse: boolean;
+}
 /** The only pending-ticket shape scanners expose. */
-export type TicketSummary = DeckTicketSummary | ReviewTicketSummary;
+export type TicketSummary = ReviewTicketSummary | PageTicketSummary;
 export interface ReviewDescriptor {
     schema: 'humanloop.review/v1';
     file: string;
     output: string;
     title: string;
     subtitle: string;
-    source: DeckSource;
+    source: TicketSource;
     blockedSince: string;
 }
-export interface DeckTicketResult {
-    schema: 'humanloop.response/v2';
-    kind: 'deck';
-    responses: InteractionResponse[];
+export interface PageTicketResult {
+    schema: 'crtr.page-response/v1';
+    kind: 'page';
+    /** An acknowledgement is the empty map; there is no second shape. */
+    responses: PageResponses;
     summary: string;
     completedAt: string;
 }
@@ -132,5 +87,5 @@ export interface CanceledTicketResult {
     actor?: string;
 }
 /** The sole canonical response.json union. */
-export type TicketResult = DeckTicketResult | ReviewTicketResult | CanceledTicketResult;
+export type TicketResult = PageTicketResult | ReviewTicketResult | CanceledTicketResult;
 export {};

package/dist/core/human/types.js

@@ -1,5 +1 @@
-// ── v2 shapes (v1 schema dropped per cycle-16 user pivot — humanloop is v2-only) ──
-// Single source of truth for the interaction-kind enum: the Zod deck schema
-// (`deck-schema.ts`) and the CLI's JSON schema both derive their enum values
-// from this array so a new kind cannot drift between validation surfaces.
-export const INTERACTION_KINDS = ['notify', 'decision', 'context', 'error', 'review'];
+export {};

package/dist/core/inspector/model.d.ts

@@ -4,6 +4,8 @@ export type InspectorSection = 'overview' | 'schedule' | 'jobs' | 'raw';
 export interface BashJobRow {
     job_id: string;
     command: string;
+    /** Human-readable label supplied with the bash call, or null when absent. */
+    purpose: string | null;
     started_at: string;
     elapsed_ms: number;
     log_path: string;
@@ -67,6 +69,9 @@ export declare function jobElapsedMs(job: BashJobRow, now?: number): number;
 export declare function jobElapsed(job: BashJobRow, now?: number): string;
 /** First line of a command, whitespace-collapsed and capped for a one-row cell. */
 export declare function commandCell(command: string, cap?: number): string;
+/** A person-readable purpose leads when present; legacy jobs retain their
+ * command label. */
+export declare function jobLabel(job: BashJobRow, cap?: number): string;
 export declare function relativeTime(iso: string | null, now?: number): string;
 /** How long ago an ISO timestamp was, e.g. `3d ago`. `—` when absent. */
 export declare function ago(iso: unknown, now?: number): string;

package/dist/core/inspector/model.js

@@ -81,6 +81,11 @@ export function commandCell(command, cap = 60) {
     const oneLine = (command.split('\n')[0] ?? '').replace(/\s+/g, ' ').trim();
     return oneLine.length > cap ? `${oneLine.slice(0, cap - 1)}…` : oneLine;
 }
+/** A person-readable purpose leads when present; legacy jobs retain their
+ * command label. */
+export function jobLabel(job, cap = 60) {
+    return commandCell(job.purpose ?? job.command, cap);
+}
 export function relativeTime(iso, now = Date.now()) {
     if (iso === null)
         return '—';

package/dist/core/inspector/text.js

@@ -1,4 +1,4 @@
-import { jobElapsed, overviewGroups, relativeTime, scheduledItems, value } from './model.js';
+import { jobElapsed, jobLabel, overviewGroups, relativeTime, scheduledItems, value } from './model.js';
 /** The piped path: same information and grouping as the TUI, minus the glyphs
  *  and hue a pipe cannot carry. */
 export const inspectorText = {
@@ -36,7 +36,7 @@ export const inspectorText = {
         if (jobs.length === 0)
             lines.push('  nothing running');
         for (const job of jobs) {
-            lines.push('', `  ${job.command.split('\n')[0]} · ${jobElapsed(job)}`, `    id        ${job.job_id}`, `    started   ${job.started_at}`, `    log       ${job.log_path}`);
+            lines.push('', `  ${jobLabel(job)} · ${jobElapsed(job)}`, `    id        ${job.job_id}`, ...(job.purpose === null ? [] : [`    command   ${job.command.split('\n')[0]}`]), `    started   ${job.started_at}`, `    log       ${job.log_path}`);
             for (const line of job.log_tail.slice(-5))
                 lines.push(`    | ${line}`);
         }

package/dist/core/inspector/tui.js

@@ -1,4 +1,4 @@
-import { ICON, commandCell, jobElapsed, jobElapsedMs, jobTone, overviewGroups, relativeTime, scheduledItems, shortPath, value, } from './model.js';
+import { ICON, commandCell, jobElapsed, jobElapsedMs, jobLabel, jobTone, overviewGroups, relativeTime, scheduledItems, shortPath, value, } from './model.js';
 // ── Visual grammar ───────────────────────────────────────────────────────────
 //
 // Three primitives carry the whole screen: a TAB STRIP (where am I / where can
@@ -162,7 +162,14 @@ function jobItem(job, expanded, width) {
         lines.push([{ text: `${INDENT}${INDENT}${last === undefined ? 'no output yet' : logCell(last, width - 6)}`, style: { dim: true } }]);
     }
     else {
-        for (const [label, text] of [['job', job.job_id], ['started', job.started_at], ['log', shortPath(job.log_path)], ['watch', `tail -f ${shortPath(job.log_path)}`]]) {
+        const details = [
+            ['job', job.job_id],
+            ...(job.purpose === null ? [] : [['command', commandCell(job.command, Math.max(20, width - 26))]]),
+            ['started', job.started_at],
+            ['log', shortPath(job.log_path)],
+            ['watch', `tail -f ${shortPath(job.log_path)}`],
+        ];
+        for (const [label, text] of details) {
             lines.push([{ text: `${INDENT}${INDENT}${label.padEnd(LABEL_COL)}`, style: LABEL_STYLE }, { text, style: label === 'watch' ? { fg: '36' } : undefined }]);
         }
         lines.push([]);
@@ -176,7 +183,7 @@ function jobItem(job, expanded, width) {
     return {
         spans: [
             { text: ` ${ICON.job} `, style: tone },
-            { text: commandCell(job.command, Math.max(20, width - 26)), style: { bold: true } },
+            { text: jobLabel(job, Math.max(20, width - 26)), style: { bold: true } },
         ],
         right: [{ text: `${jobElapsed(job)} `, style: tone }],
         lines,