@north-light/crouter 0.3.179 → 0.3.180

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

@@ -1,12 +1,86 @@
-// Ticket-inbox listing for the attached terminal viewer.
+// 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 { realpathSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, resolve } 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 { 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 { filterTerminalReviewTickets } from '../../../core/review/ticket-filter.js';
+const DEFAULT_CANCEL_REASON = 'Canceled from the inbox.';
+const CANCEL_REASON_MAX = 1000;
+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 {
+        canonicalRoot = realpathSync(ticketsRoot());
+    }
+    catch {
+        return null;
+    }
+    let entries;
+    try {
+        entries = readdirSync(canonicalRoot);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (ticketHash(canonicalRoot, entry) !== ticketId)
+            continue;
+        const candidate = resolve(canonicalRoot, entry);
+        let canonicalDir;
+        try {
+            if (!statSync(candidate).isDirectory())
+                continue;
+            canonicalDir = realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (resolve(canonicalDir, '..') !== canonicalRoot || basename(canonicalDir) !== entry)
+            continue;
+        if (existsSync(deckPath(canonicalDir)))
+            return { nodeId: entry, dir: canonicalDir, kind: 'deck' };
+        if (existsSync(reviewPath(canonicalDir)))
+            return { nodeId: entry, dir: canonicalDir, kind: 'review' };
+    }
+    return null;
+}
+function requireTicketId(params) {
+    const ticketId = params['ticket_id'];
+    if (ticketId === undefined || !TICKET_ID_PATTERN.test(ticketId)) {
+        throw new ApiError(400, 'invalid_request', 'invalid ticket id');
+    }
+    return ticketId;
+}
+// ===========================================================================
+// Projections — humanloop canonical shapes → wire DTOs
+// ===========================================================================
 function toDeckSourceDTO(source) {
     const dto = {};
     if (source.sessionName !== undefined)
@@ -17,6 +91,39 @@ function toDeckSourceDTO(source) {
         dto.blockedSince = source.blockedSince;
     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) {
+    const dto = {
+        id: interaction.id,
+        title: interaction.title,
+        subtitle: interaction.subtitle,
+        options: interaction.options.map(toOptionDTO),
+    };
+    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;
+    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);
@@ -43,14 +150,246 @@ function toTicketSummaryDTO(item) {
         dto.interaction_kind = item.interactionKind;
     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);
+}
+function requireNoExtraKeys(obj, allowed) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key))
+            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) };
+}
+function validateCancelRequest(raw) {
+    if (raw === undefined)
+        return {};
+    if (!isPlainObject(raw))
+        throw new ApiError(400, 'invalid_request', 'cancel body must be an object');
+    requireNoExtraKeys(raw, ['reason']);
+    if (raw['reason'] === undefined)
+        return {};
+    const reason = raw['reason'];
+    if (typeof reason !== 'string')
+        throw new ApiError(400, 'invalid_request', '`reason` must be a string');
+    if (reason.trim() === '' || reason.length > CANCEL_REASON_MAX) {
+        throw new ApiError(400, 'invalid_request', '`reason` must be nonempty after trim and at most 1000 characters');
+    }
+    return { reason };
+}
+// ===========================================================================
+// 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 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
+// ===========================================================================
+function handleGetDeck(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');
+    }
+    // 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;
+    try {
+        deck = parseDeck(deckPath(resolved.dir));
+    }
+    catch {
+        throw new ApiError(500, 'internal', 'the ticket could not be read');
+    }
+    return { status: 200, body: { ticket_id: ticketId, kind: 'deck', deck: toDeckDTO(deck) } };
+}
+// ===========================================================================
+// 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);
+    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 submit through POST /v1/human/reviews/:id/submit');
+    }
+    if (readTicketResult(resolved.dir) !== null) {
+        throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+    }
+    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 };
+    }
+    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)) {
+            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/cancel — cancel
+// ===========================================================================
+async function handleCancel(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const request = validateCancelRequest(ctx.body);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    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',
+        });
+        if (result.kind !== 'canceled')
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        return { status: 200, body: result };
+    }
+    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');
+    }
+}
 export const inboxRoutes = [
     { method: 'GET', pattern: '/v1/human/inbox', handler: handleList },
+    { method: 'GET', pattern: '/v1/human/inbox/:ticket_id', handler: handleGetDeck },
+    { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/respond', handler: handleRespond },
+    { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/cancel', handler: handleCancel },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.179",
+  "version": "0.3.180",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.179",
+  "version": "0.3.180",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.179",
+      "version": "0.3.180",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {