@north-light/crouter 0.3.192 → 0.3.193

package/dist/daemon/api/handlers/inbox.js

@@ -1,26 +1,18 @@
 // Ticket inbox handlers — crtrd `/v1/human/inbox` (Northlight crouter-inbox
 // v1, inbox-contract.md §A). This public ticket-serving resource enumerates,
 // reads, responds to, and cancels tickets while preserving its product DTOs.
-//
-// Every ticket is addressed on the wire by an opaque, stable id: lowercase
-// SHA-256 hex of `canonicalRoot + "\0" + ticketBasename`. The wire never exposes
-// a ticket directory, review file/output, claim owner/heartbeat, or other host
-// path or process metadata. The daemon's shared ticket finish path owns claims,
-// terminal publication, and bridge delivery.
 import { createHash } from 'node:crypto';
-import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, resolve, join } from 'node:path';
 import { ApiError } from '../../../api/index.js';
-import { readJsonOrNull } from '../../../core/fs-utils.js';
-import { deckPath, reviewPath } from '../../../core/human/convention.js';
-import { parseDeck } from '../../../core/human/deck-schema.js';
+import { assetRoot } from '../../../core/asset-root.js';
+import { pageManifestPath, reviewPath } from '../../../core/human/convention.js';
+import { renderPageHtml } from '../../../core/human/page-render.js';
 import { ticketsRoot } from '../../../core/human/root.js';
-import { scanInbox } from '../../../core/human/scan.js';
-import { readTicketResult } from '../../../core/human/tickets.js';
-import { getReviewByBridge } from '../../../core/review/store.js';
-import { ReviewOperationError } from '../../../core/review/types.js';
-import { cancelHumanTicket, resolveDeckTicket } from '../../human/finish.js';
-import { cancelReview } from '../../review/finish.js';
+import { scanInbox, scanPageHistory } from '../../../core/human/scan.js';
+import { readPageTicket, readTicketResult, validatePageTicketResponses, writePageProgress, } from '../../../core/human/tickets.js';
+import { readConfig } from '../../../core/config.js';
+import { cancelHumanTicket, resolvePageTicket } from '../../human/finish.js';
 import { filterTerminalReviewTickets } from '../../../core/review/ticket-filter.js';
 const DEFAULT_CANCEL_REASON = 'Canceled from the inbox.';
 const CANCEL_REASON_MAX = 1000;
@@ -28,12 +20,9 @@ const TICKET_ID_PATTERN = /^[a-f0-9]{64}$/;
 // ===========================================================================
 // Opaque ticket id resolution
 // ===========================================================================
-/** Opaque ids hash the canonical derived tickets root and ticket basename. */
 function ticketHash(canonicalRoot, ticketBasename) {
     return createHash('sha256').update(`${canonicalRoot}\0${ticketBasename}`, 'utf8').digest('hex');
 }
-/** Resolve an opaque id against the single tickets root. Includes terminal
- * tickets so a stale client receives the stable already-resolved response. */
 function resolveTicket(ticketId) {
     let canonicalRoot;
     try {
@@ -64,8 +53,8 @@ function resolveTicket(ticketId) {
         }
         if (resolve(canonicalDir, '..') !== canonicalRoot || basename(canonicalDir) !== entry)
             continue;
-        if (existsSync(deckPath(canonicalDir)))
-            return { nodeId: entry, dir: canonicalDir, kind: 'deck' };
+        if (existsSync(pageManifestPath(canonicalDir)))
+            return { nodeId: entry, dir: canonicalDir, kind: 'page' };
         if (existsSync(reviewPath(canonicalDir)))
             return { nodeId: entry, dir: canonicalDir, kind: 'review' };
     }
@@ -81,87 +70,45 @@ function requireTicketId(params) {
 // ===========================================================================
 // Projections — humanloop canonical shapes → wire DTOs
 // ===========================================================================
-function toDeckSourceDTO(source) {
-    const dto = {};
-    if (source.sessionName !== undefined)
-        dto.sessionName = source.sessionName;
-    if (source.askedBy !== undefined)
-        dto.askedBy = source.askedBy;
-    if (source.blockedSince !== undefined)
-        dto.blockedSince = source.blockedSince;
-    // The originating canvas node id — machine attribution a consumer uses to
-    // relate a ticket to the node that raised it. A node id is opaque canvas
-    // identity, not a host path, so it is safe on this wire.
-    if (source.nodeId !== undefined)
-        dto.nodeId = source.nodeId;
-    return dto;
-}
-function toOptionDTO(option) {
-    const dto = { id: option.id, label: option.label };
-    if (option.description !== undefined)
-        dto.description = option.description;
-    return dto;
-}
-function toInteractionDTO(interaction) {
+function pageSlotToDTO(slot) {
     const dto = {
-        id: interaction.id,
-        title: interaction.title,
-        subtitle: interaction.subtitle,
-        options: interaction.options.map(toOptionDTO),
+        kind: slot.kind,
+        step: slot.step,
+        config: slot.config,
     };
-    if (interaction.body !== undefined)
-        dto.body = interaction.body;
-    if (interaction.multiSelect !== undefined)
-        dto.multiSelect = interaction.multiSelect;
-    if (interaction.allowFreetext !== undefined)
-        dto.allowFreetext = interaction.allowFreetext;
-    if (interaction.freetextLabel !== undefined)
-        dto.freetextLabel = interaction.freetextLabel;
-    if (interaction.kind !== undefined)
-        dto.kind = interaction.kind;
-    if (interaction.preAnswered !== undefined)
-        dto.preAnswered = interaction.preAnswered;
+    if (slot.id !== undefined)
+        dto.id = slot.id;
+    if (slot.unvalidated === true)
+        dto.unvalidated = true;
     return dto;
 }
-function toDeckDTO(deck) {
-    const dto = { title: deck.title, interactions: deck.interactions.map(toInteractionDTO) };
-    if (deck.source !== undefined)
-        dto.source = toDeckSourceDTO(deck.source);
-    return dto;
-}
-function toTicketSummaryDTO(item) {
-    const ticket_id = ticketHash(realpathSync(ticketsRoot()), item.id);
-    const source = toDeckSourceDTO(item.source);
-    if (item.kind === 'review') {
-        const dto = {
-            ticket_id,
-            kind: 'review',
-            title: item.title,
-            subtitle: item.subtitle,
-            blocked_since: item.blockedSince,
-            source,
-        };
-        return dto;
-    }
+function pageManifestToDTO(manifest) {
     const dto = {
-        ticket_id,
-        kind: 'deck',
-        title: item.title,
-        subtitle: item.subtitle,
-        blocked_since: item.blockedSince,
-        source,
+        schema: 'crtr.page/v1',
+        dialect: manifest.dialect,
+        title: manifest.title,
+        placement: manifest.placement,
+        document: manifest.document,
+        steps: manifest.steps,
+        slots: manifest.slots.map(pageSlotToDTO),
     };
-    if (item.interactionKind !== undefined)
-        dto.interaction_kind = item.interactionKind;
+    if (manifest.subtitle !== undefined)
+        dto.subtitle = manifest.subtitle;
+    if (manifest.source !== undefined) {
+        const source = {};
+        if (manifest.source.sessionName !== undefined)
+            source.sessionName = manifest.source.sessionName;
+        if (manifest.source.askedBy !== undefined)
+            source.askedBy = manifest.source.askedBy;
+        if (manifest.source.blockedSince !== undefined)
+            source.blockedSince = manifest.source.blockedSince;
+        if (manifest.source.nodeId !== undefined)
+            source.nodeId = manifest.source.nodeId;
+        if (Object.keys(source).length > 0)
+            dto.source = source;
+    }
     return dto;
 }
-// ===========================================================================
-// Request-body validation — structural only. Semantic response↔deck
-// validation (option ids, single/multi-select shape, freetext permission,
-// option comments, required notify acknowledgement) belongs to the ticket
-// store via the daemon finish path; a structural violation here is
-// `invalid_request`, a semantic rejection there is `invalid_ticket_response`.
-// ===========================================================================
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -171,48 +118,21 @@ function requireNoExtraKeys(obj, allowed) {
             throw new ApiError(400, 'invalid_request', `unexpected field: ${key}`);
     }
 }
-const RESPONSE_FIELDS = ['id', 'selectedOptionId', 'selectedOptionIds', 'freetext', 'optionComments'];
-function validateInteractionResponse(raw) {
-    if (!isPlainObject(raw))
-        throw new ApiError(400, 'invalid_request', 'each response must be an object');
-    requireNoExtraKeys(raw, RESPONSE_FIELDS);
-    const { id, selectedOptionId, selectedOptionIds, freetext, optionComments } = raw;
-    if (typeof id !== 'string' || id === '') {
-        throw new ApiError(400, 'invalid_request', 'response.id must be a nonempty string');
-    }
-    const response = { id };
-    if (selectedOptionId !== undefined) {
-        if (typeof selectedOptionId !== 'string') {
-            throw new ApiError(400, 'invalid_request', 'response.selectedOptionId must be a string');
-        }
-        response.selectedOptionId = selectedOptionId;
-    }
-    if (selectedOptionIds !== undefined) {
-        if (!Array.isArray(selectedOptionIds) || !selectedOptionIds.every((v) => typeof v === 'string')) {
-            throw new ApiError(400, 'invalid_request', 'response.selectedOptionIds must be a string array');
-        }
-        response.selectedOptionIds = selectedOptionIds;
-    }
-    if (freetext !== undefined) {
-        if (typeof freetext !== 'string')
-            throw new ApiError(400, 'invalid_request', 'response.freetext must be a string');
-        response.freetext = freetext;
-    }
-    if (optionComments !== undefined) {
-        if (!isPlainObject(optionComments) || !Object.values(optionComments).every((v) => typeof v === 'string')) {
-            throw new ApiError(400, 'invalid_request', 'response.optionComments must be a string map');
-        }
-        response.optionComments = optionComments;
-    }
-    return response;
-}
 function validateRespondRequest(raw) {
     if (!isPlainObject(raw))
         throw new ApiError(400, 'invalid_request', 'respond body is required');
     requireNoExtraKeys(raw, ['responses']);
-    if (!Array.isArray(raw['responses']))
-        throw new ApiError(400, 'invalid_request', '`responses` must be an array');
-    return { responses: raw['responses'].map(validateInteractionResponse) };
+    if (!isPlainObject(raw['responses']))
+        throw new ApiError(400, 'invalid_request', '`responses` must be an object');
+    return { responses: raw['responses'] };
+}
+function validateProgressRequest(raw) {
+    if (!isPlainObject(raw))
+        throw new ApiError(400, 'invalid_request', 'progress body is required');
+    requireNoExtraKeys(raw, ['responses']);
+    if (!isPlainObject(raw['responses']))
+        throw new ApiError(400, 'invalid_request', '`responses` must be an object');
+    return { responses: raw['responses'] };
 }
 function validateCancelRequest(raw) {
     if (raw === undefined)
@@ -230,88 +150,127 @@ function validateCancelRequest(raw) {
     }
     return { reason };
 }
+// Error patterns matching slot-addressed validation messages from page-schema.ts
+const SLOT_VALIDATION_PATTERNS = [
+    /^slot ".*?" /,
+    /^response names unknown or non-response-bearing slot id/,
+    /^final page response is missing response-bearing slot id/,
+];
+function isSlotValidationError(err) {
+    return err instanceof Error && SLOT_VALIDATION_PATTERNS.some((pattern) => pattern.test(err.message));
+}
 // ===========================================================================
 // GET /v1/human/inbox — enumerate
 // ===========================================================================
 function handleList() {
-    const items = filterTerminalReviewTickets(scanInbox());
-    // `blocked_since` is an RFC 3339 timestamp that may carry a non-`Z` offset;
-    // two offsets are not lexically comparable (`+14:00` can sort after `Z`
-    // while naming an earlier instant), so sort by parsed instant and use the
-    // ticket id only to break an exact tie.
-    const tickets = items.map(toTicketSummaryDTO).sort((a, b) => {
+    const productKinds = readConfig('user').page_components ?? [];
+    const allItems = scanInbox(productKinds);
+    const filtered = filterTerminalReviewTickets(allItems);
+    const tickets = filtered.map((item) => {
+        if (item.kind === 'page') {
+            const ticketId = createHash('sha256').update(`${realpathSync(ticketsRoot())}\0${item.id}`, 'utf8').digest('hex');
+            const dto = {
+                ticket_id: ticketId,
+                kind: 'page',
+                title: item.title,
+                placement: item.placement,
+                dialect: item.dialect,
+                steps: item.steps,
+                blocked_since: item.blockedSince,
+                source: item.source,
+                slot_kinds: item.slotKinds,
+                awaits_response: item.awaitsResponse,
+            };
+            if (item.subtitle !== '')
+                dto.subtitle = item.subtitle;
+            return dto;
+        }
+        else if (item.kind === 'review') {
+            return {
+                ticket_id: createHash('sha256').update(`${realpathSync(ticketsRoot())}\0${item.id}`, 'utf8').digest('hex'),
+                kind: 'review',
+                title: item.title,
+                subtitle: item.subtitle,
+                blocked_since: item.blockedSince,
+                source: item.source,
+            };
+        }
+        throw new Error(`unknown ticket kind: ${item.kind}`);
+    }).sort((a, b) => {
         const byTime = Date.parse(b.blocked_since) - Date.parse(a.blocked_since);
         return byTime !== 0 ? byTime : a.ticket_id.localeCompare(b.ticket_id);
     });
     return { status: 200, body: { tickets } };
 }
 // ===========================================================================
-// GET /v1/human/inbox/:ticket_id — read a pending deck
+// GET /v1/human/inbox/history?node_id=<id> — page ticket history
 // ===========================================================================
-function handleGetDeck(ctx) {
+function handleHistory(ctx) {
+    const nodeId = ctx.query.get('node_id');
+    if (!nodeId || typeof nodeId !== 'string') {
+        throw new ApiError(400, 'invalid_request', 'history requires a node_id query param');
+    }
+    const productKinds = readConfig('user').page_components ?? [];
+    const history = scanPageHistory(nodeId, productKinds);
+    const canonicalRoot = realpathSync(ticketsRoot());
+    const tickets = history.map((item) => {
+        const ticketId = createHash('sha256').update(`${canonicalRoot}\0${item.id}`, 'utf8').digest('hex');
+        const dto = {
+            ticket_id: ticketId,
+            kind: 'page',
+            title: item.title,
+            placement: item.placement,
+            dialect: item.dialect,
+            steps: item.steps,
+            blocked_since: item.blockedSince,
+            source: item.source,
+            slot_kinds: item.slotKinds,
+            awaits_response: item.awaitsResponse,
+            state: item.state,
+        };
+        if (item.subtitle !== '')
+            dto.subtitle = item.subtitle;
+        return dto;
+    });
+    return { status: 200, body: { tickets } };
+}
+// ===========================================================================
+// GET /v1/human/inbox/:ticket_id — read a page ticket
+// ===========================================================================
+function handleGetPage(ctx) {
     const ticketId = requireTicketId(ctx.params);
     const resolved = resolveTicket(ticketId);
     if (resolved === null)
         throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
     if (resolved.kind === 'review') {
-        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no v1 read operation');
-    }
-    if (readTicketResult(resolved.dir) !== null) {
-        throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no page read operation');
     }
-    // A malformed stored ticket is omitted from enumeration by `scanInbox`; if
-    // independently reached during a race (or a ticket is mutated on disk after
-    // enumeration), `parseDeck` throws a plain Error whose message can carry a
-    // `bodyPath` value or another host filesystem path (e.g. "bodyPath '/etc/
-    // passwd' escapes the deck directory"). That message must never reach the
-    // wire, so it is never allowed to fall through to the router's generic
-    // mapper unsanitized — humanloop validation itself is never weakened to
-    // serve unvalidated content, only its failure message is sanitized.
-    let deck;
+    const productKinds = readConfig('user').page_components ?? [];
+    let ticket;
     try {
-        deck = parseDeck(deckPath(resolved.dir));
+        ticket = readPageTicket(resolved.dir, productKinds);
     }
-    catch {
+    catch (err) {
         throw new ApiError(500, 'internal', 'the ticket could not be read');
     }
-    return { status: 200, body: { ticket_id: ticketId, kind: 'deck', deck: toDeckDTO(deck) } };
+    const progress = ticket.progress;
+    const progressDTO = progress === null ? null : { responses: progress };
+    return {
+        status: 200,
+        body: {
+            ticket_id: ticketId,
+            kind: 'page',
+            state: ticket.state,
+            page: pageManifestToDTO(ticket.manifest),
+            document: ticket.document,
+            document_media_type: ticket.manifest.dialect === 'md' ? 'text/markdown' : 'text/html',
+            progress: progressDTO,
+        },
+    };
 }
 // ===========================================================================
 // POST /v1/human/inbox/:ticket_id/respond — submit
 // ===========================================================================
-// The exhaustive set of messages the ticket store's response validator throws
-// for a genuine response-shape
-// rejection — duplicate/unknown interaction id, invalid single/multi-select
-// shape, disallowed freetext, invalid option comments, or a missing required
-// notify acknowledgement. None of these ever carry a filesystem path (only
-// client-supplied interaction ids), so their message is safe to forward
-// verbatim as `invalid_ticket_response`. Any other failure — a malformed
-// stored deck, a lock/dispatch/filesystem error — is not a response-shape
-// problem and must not be mislabeled or leak its cause; it is sanitized to
-// `500 internal`.
-const RESPONSE_VALIDATION_MESSAGE_PATTERNS = [
-    /^response does not match a unique deck interaction: /,
-    /^invalid single-select response for /,
-    /^invalid multi-select response for /,
-    /^freetext is not allowed for /,
-    /^invalid option comments for /,
-    /^notification requires an explicit acknowledgement: /,
-];
-function isResponseValidationError(err) {
-    return err instanceof Error && RESPONSE_VALIDATION_MESSAGE_PATTERNS.some((pattern) => pattern.test(err.message));
-}
-function coerceSingleSelect(responses, dir) {
-    const deck = readJsonOrNull(deckPath(dir));
-    if (deck === null)
-        return responses;
-    const multiSelect = new Map(deck.interactions.map((interaction) => [interaction.id, interaction.multiSelect === true]));
-    return responses.map((response) => {
-        if (multiSelect.get(response.id) === true || response.selectedOptionId !== undefined || response.selectedOptionIds?.length !== 1)
-            return response;
-        const { selectedOptionIds: _selectedOptionIds, ...rest } = response;
-        return { ...rest, selectedOptionId: response.selectedOptionIds[0] };
-    });
-}
 async function handleRespond(ctx) {
     const ticketId = requireTicketId(ctx.params);
     const request = validateRespondRequest(ctx.body);
@@ -319,30 +278,71 @@ async function handleRespond(ctx) {
     if (resolved === null)
         throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
     if (resolved.kind === 'review') {
-        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets submit through POST /v1/human/reviews/:id/submit');
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets submit through their own path');
     }
-    if (readTicketResult(resolved.dir) !== null) {
+    const result = readTicketResult(resolved.dir);
+    if (result !== null && result.kind !== 'canceled') {
         throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
     }
+    if (result?.kind === 'canceled') {
+        throw new ApiError(409, 'ticket_canceled', 'canceled tickets cannot be answered');
+    }
+    const productKinds = readConfig('user').page_components ?? [];
     try {
-        const result = await resolveDeckTicket(resolved.nodeId, coerceSingleSelect(request.responses, resolved.dir));
-        if (result.kind !== 'deck')
-            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
-        return { status: 200, body: result };
+        validatePageTicketResponses(resolved.dir, request.responses, productKinds);
+    }
+    catch (error) {
+        if (isSlotValidationError(error)) {
+            throw new ApiError(400, 'invalid_ticket_response', error.message);
+        }
+        throw new ApiError(500, 'internal', 'validation failed');
+    }
+    try {
+        // The shared completion path: it publishes the result and wakes the asking node.
+        const completed = await resolvePageTicket(resolved.nodeId, request.responses, productKinds);
+        if (completed.kind !== 'page') {
+            throw new ApiError(409, 'ticket_kind_mismatch', 'unexpected result kind');
+        }
+        return { status: 200, body: completed };
     }
     catch (error) {
-        // The daemon's terminal errors are public protocol outcomes: preserve both
-        // their code and message so Northlight can distinguish conflict from a
-        // recorded-but-undelivered answer.
         if (error instanceof ApiError)
             throw error;
-        if (isResponseValidationError(error)) {
+        if (isSlotValidationError(error)) {
             throw new ApiError(400, 'invalid_ticket_response', error.message);
         }
         throw new ApiError(500, 'internal', 'the ticket could not be finalized');
     }
 }
 // ===========================================================================
+// POST /v1/human/inbox/:ticket_id/progress — autosave
+// ===========================================================================
+function handleProgress(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const request = validateProgressRequest(ctx.body);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    if (resolved.kind === 'review') {
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets do not support progress autosave');
+    }
+    const result = readTicketResult(resolved.dir);
+    if (result !== null && result.kind !== 'canceled') {
+        throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+    }
+    const productKinds = readConfig('user').page_components ?? [];
+    try {
+        writePageProgress(resolved.dir, request.responses, productKinds);
+        return { status: 200, body: {} };
+    }
+    catch (error) {
+        if (isSlotValidationError(error)) {
+            throw new ApiError(400, 'invalid_ticket_response', error.message);
+        }
+        throw new ApiError(500, 'internal', 'progress could not be saved');
+    }
+}
+// ===========================================================================
 // POST /v1/human/inbox/:ticket_id/cancel — cancel
 // ===========================================================================
 async function handleCancel(ctx) {
@@ -351,26 +351,10 @@ async function handleCancel(ctx) {
     const resolved = resolveTicket(ticketId);
     if (resolved === null)
         throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    if (resolved.kind === 'review') {
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have their own cancel path');
+    }
     try {
-        if (resolved.kind === 'review') {
-            const review = getReviewByBridge(resolved.nodeId);
-            if (review !== null) {
-                if (review.state === 'approved') {
-                    throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
-                }
-                const finished = await cancelReview(review.review_id, {
-                    reason: request.reason ?? DEFAULT_CANCEL_REASON,
-                    actor: 'human',
-                });
-                if (finished.outcome === 'already_settled') {
-                    throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
-                }
-                if (finished.ticket_result?.kind !== 'canceled') {
-                    throw new Error('canonical review cancellation did not produce a ticket result');
-                }
-                return { status: 200, body: finished.ticket_result };
-            }
-        }
         const result = await cancelHumanTicket(resolved.nodeId, {
             reason: request.reason ?? DEFAULT_CANCEL_REASON,
             actor: 'human',
@@ -382,19 +366,119 @@ async function handleCancel(ctx) {
     catch (error) {
         if (error instanceof ApiError)
             throw error;
-        // Review errors are canonical lifecycle vocabulary, not ticket protocol.
-        // A concurrent terminal winner is the same public ticket conflict.
-        if (error instanceof ReviewOperationError) {
-            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
-        }
-        // A lock/filesystem/delivery failure is not a request-shape problem; do
-        // not leak its cause through the generic router mapper.
         throw new ApiError(500, 'internal', 'the ticket could not be canceled');
     }
 }
+// ===========================================================================
+// GET /v1/human/inbox/:ticket_id/response — published response
+// ===========================================================================
+function handleGetResponse(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    if (resolved.kind === 'review') {
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets fetch responses through their own path');
+    }
+    const result = readTicketResult(resolved.dir);
+    if (result === null) {
+        throw new ApiError(404, 'ticket_pending', 'ticket has no response yet');
+    }
+    if (result.kind === 'canceled') {
+        throw new ApiError(404, 'ticket_canceled', 'canceled tickets have no response');
+    }
+    if (result.kind !== 'page') {
+        throw new ApiError(409, 'ticket_kind_mismatch', 'unexpected result kind');
+    }
+    return { status: 200, body: result };
+}
+// ===========================================================================
+// GET /v1/human/inbox/:ticket_id/render — the page's HTML payload
+// ===========================================================================
+function handleRenderPage(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    if (resolved.kind === 'review') {
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no page render operation');
+    }
+    const productKinds = readConfig('user').page_components ?? [];
+    // Addressable for pending, resolved, and canceled tickets alike — the same
+    // read rule as the detail route: a page stays readable after it resolves.
+    let ticket;
+    try {
+        ticket = readPageTicket(resolved.dir, productKinds);
+    }
+    catch {
+        throw new ApiError(500, 'internal', 'the ticket could not be read');
+    }
+    try {
+        return { status: 200, body: { html: renderPageHtml(ticket.manifest, ticket.document, productKinds) } };
+    }
+    catch {
+        throw new ApiError(500, 'internal', 'the page could not be rendered');
+    }
+}
+// ===========================================================================
+// GET /v1/human/pages/bundle.js|.css — the page runtime assets
+// ===========================================================================
+const BUNDLE_MEDIA_TYPES = {
+    'bundle.js': 'text/javascript; charset=utf-8',
+    'bundle.css': 'text/css; charset=utf-8',
+};
+const bundleCache = new Map();
+/** Read one built bundle asset, reusing the cached bytes while the file on disk
+ *  is unchanged. A runtime generation swap changes mtime, so the next request
+ *  re-reads and re-hashes. */
+function readBundleAsset(name) {
+    let path;
+    let stat;
+    try {
+        path = join(assetRoot(), 'pages', name);
+        stat = statSync(path);
+    }
+    catch {
+        throw new ApiError(500, 'page_bundle_unavailable', `${name} is not present in this runtime generation; the page runtime is built by \`npm run build\``);
+    }
+    const cached = bundleCache.get(name);
+    if (cached !== undefined && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size)
+        return cached;
+    const bytes = readFileSync(path);
+    const asset = {
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        bytes,
+        etag: `"${createHash('sha256').update(bytes).digest('hex').slice(0, 32)}"`,
+    };
+    bundleCache.set(name, asset);
+    return asset;
+}
+function etagMatches(header, etag) {
+    if (header === undefined)
+        return false;
+    return header.split(',').map((candidate) => candidate.trim()).some((candidate) => candidate === '*' || candidate === etag || candidate === `W/${etag}`);
+}
+function handleBundleAsset(name) {
+    return (ctx) => {
+        const asset = readBundleAsset(name);
+        const headers = { etag: asset.etag, 'cache-control': 'no-cache' };
+        const ifNoneMatch = ctx.req.headers['if-none-match'];
+        if (etagMatches(Array.isArray(ifNoneMatch) ? ifNoneMatch.join(',') : ifNoneMatch, asset.etag)) {
+            return { status: 304, headers };
+        }
+        return { status: 200, rawBody: asset.bytes, headers: { ...headers, 'content-type': BUNDLE_MEDIA_TYPES[name] } };
+    };
+}
 export const inboxRoutes = [
+    { method: 'GET', pattern: '/v1/human/pages/bundle.js', handler: handleBundleAsset('bundle.js') },
+    { method: 'GET', pattern: '/v1/human/pages/bundle.css', handler: handleBundleAsset('bundle.css') },
     { method: 'GET', pattern: '/v1/human/inbox', handler: handleList },
-    { method: 'GET', pattern: '/v1/human/inbox/:ticket_id', handler: handleGetDeck },
+    { method: 'GET', pattern: '/v1/human/inbox/history', handler: handleHistory },
+    { method: 'GET', pattern: '/v1/human/inbox/:ticket_id', handler: handleGetPage },
+    { method: 'GET', pattern: '/v1/human/inbox/:ticket_id/render', handler: handleRenderPage },
+    { method: 'GET', pattern: '/v1/human/inbox/:ticket_id/response', handler: handleGetResponse },
     { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/respond', handler: handleRespond },
+    { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/progress', handler: handleProgress },
     { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/cancel', handler: handleCancel },
 ];