@north-light/crouter 0.3.311 → 0.3.313

package/dist/daemon/api/handlers/human-requests.js

@@ -1,27 +1,20 @@
-// Durable programmatic human requests — crtrd `/v1/human/requests`. A request
-// is an ordinary page ticket with an optional frozen completion action, so it
-// is the same record the inbox lists, answers, and dismisses. Creation is the
-// only surface that writes the action binding; every settlement path funnels
-// through the shared first-writer-wins store.
-import { randomBytes } from 'node:crypto';
 import { statSync } from 'node:fs';
-import { basename, isAbsolute } from 'node:path';
+import { isAbsolute } from 'node:path';
 import { ApiError } from '../../../api/index.js';
-import { readActionDelivery } from '../../../core/canvas/human-deliveries.js';
+import { readExternalActionDelivery } from '../../../core/canvas/deliveries.js';
+import { isSafeNodeId } from '../../../core/canvas/paths.js';
 import { resolvePageComponents } from '../../../core/config.js';
 import { resolveHumanAction } from '../../../core/human-actions.js';
-import { HUMAN_ACTION_NAME_PATTERN, publishTicketActionBinding, readTicketActionBinding, } from '../../../core/human/action-binding.js';
-import { completionEventFor } from '../../../core/human/completion.js';
-import { parsePage } from '../../../core/human/page.js';
-import { opaqueInboxTicketId, ticketDir } from '../../../core/human/root.js';
-import { preparePageSource, publishPage, readPageTicket, readTicketResult, validatePageTicketResponses, } from '../../../core/human/tickets.js';
+import { HUMAN_ACTION_NAME_PATTERN } from '../../../core/human/action-binding.js';
+import { createPageRequest, getRequest } from '../../../core/human/requests.js';
+import { preparePageSource } from '../../../core/human/page-authoring.js';
+import { publishPage, validatePageTicketResponses } from '../../../core/human/tickets.js';
 import { cancelHumanTicket, resolvePageTicket } from '../../human/finish.js';
-import { resolveTicket, requireTicketId } from './inbox.js';
+import { inboxPageProjection } from './inbox-page.js';
 const REASON_MAX = 1000;
 const ACTOR_MAX = 200;
 const DEFAULT_DELIVERY = { placement: 'inline', inbox: true, reply: false };
 const SOURCE_FIELDS = ['sessionName', 'askedBy', 'emittedAt', 'profileName', 'nodeId'];
-// Body validation
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -31,39 +24,39 @@ function requireNoExtraKeys(obj, allowed, where) {
             throw new ApiError(400, 'invalid_request', `unexpected field in ${where}: ${key}`);
     }
 }
-function invalid(message) {
-    return new ApiError(400, 'invalid_request', message);
-}
+function invalid(message) { return new ApiError(400, 'invalid_request', message); }
 function validatePage(raw) {
     if (!isPlainObject(raw))
         throw invalid('`page` must be an object');
     requireNoExtraKeys(raw, ['dialect', 'source'], '`page`');
-    const dialect = raw['dialect'];
-    if (dialect !== 'jsx' && dialect !== 'html')
+    if (raw['dialect'] !== 'jsx' && raw['dialect'] !== 'html')
         throw invalid('`page.dialect` must be "jsx" or "html"');
-    const source = raw['source'];
-    if (typeof source !== 'string' || source.trim() === '')
+    if (typeof raw['source'] !== 'string' || raw['source'].trim() === '')
         throw invalid('`page.source` must be the authored page text');
-    return { dialect, source };
+    return { dialect: raw['dialect'], source: raw['source'] };
+}
+function validatePlacement(raw, fallback) {
+    const placement = raw ?? fallback;
+    if (placement !== 'inline' && placement !== 'panel')
+        throw invalid('`delivery.placement` must be "inline" or "panel"');
+    return placement;
 }
-/** Creation pins a programmatic request to the inbox with no bridge to reply to. */
-function validateCreateDelivery(raw) {
+function validateCreateDelivery(raw, requesterNodeId) {
     if (raw === undefined)
         return DEFAULT_DELIVERY;
     if (!isPlainObject(raw))
         throw invalid('`delivery` must be an object');
     requireNoExtraKeys(raw, ['placement', 'inbox', 'reply'], '`delivery`');
-    const placement = validatePlacement(raw['placement'], DEFAULT_DELIVERY.placement);
-    const inbox = raw['inbox'] ?? true;
-    const reply = raw['reply'] ?? false;
-    if (inbox !== true)
-        throw invalid('`delivery.inbox` must be true: a programmatic request must stay answerable');
-    if (reply !== false)
-        throw invalid('`delivery.reply` must be false: a programmatic request has no agent bridge to reply to');
-    return { placement, inbox: true, reply: false };
+    const inbox = raw['inbox'] ?? DEFAULT_DELIVERY.inbox;
+    const reply = raw['reply'] ?? DEFAULT_DELIVERY.reply;
+    if (typeof inbox !== 'boolean')
+        throw invalid('`delivery.inbox` must be boolean');
+    if (typeof reply !== 'boolean')
+        throw invalid('`delivery.reply` must be boolean');
+    if (reply && requesterNodeId === null)
+        throw invalid('`delivery.reply` requires `requester_node_id`');
+    return { placement: validatePlacement(raw['placement'], DEFAULT_DELIVERY.placement), inbox, reply };
 }
-/** Replace re-presents a pending page; where the ticket is routed is fixed at
- * creation, so only placement is replaceable. */
 function validateReplaceDelivery(raw, prior) {
     if (raw === undefined)
         return prior;
@@ -72,12 +65,6 @@ function validateReplaceDelivery(raw, prior) {
     requireNoExtraKeys(raw, ['placement'], '`delivery`');
     return { ...prior, placement: validatePlacement(raw['placement'], prior.placement) };
 }
-function validatePlacement(raw, fallback) {
-    const placement = raw ?? fallback;
-    if (placement !== 'inline' && placement !== 'panel')
-        throw invalid('`delivery.placement` must be "inline" or "panel"');
-    return placement;
-}
 function validateSource(raw) {
     if (raw === undefined)
         return undefined;
@@ -117,40 +104,43 @@ function validateActionSelection(raw) {
     if (!isPlainObject(raw))
         throw invalid('`action` must be an object');
     requireNoExtraKeys(raw, ['name', 'payload'], '`action`');
-    const name = raw['name'];
-    if (typeof name !== 'string' || !HUMAN_ACTION_NAME_PATTERN.test(name)) {
+    if (typeof raw['name'] !== 'string' || !HUMAN_ACTION_NAME_PATTERN.test(raw['name']))
         throw invalid('`action.name` must be a declared action name');
-    }
-    // The completion document always carries `action.payload`, so an omitted one
-    // is normalized here rather than serialized away downstream.
-    return { name, payload: raw['payload'] ?? null };
+    return { name: raw['name'], payload: raw['payload'] ?? null };
+}
+function validateRequesterNodeId(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'string' || !isSafeNodeId(raw))
+        throw invalid('`requester_node_id` must be a safe node id or null');
+    return raw;
 }
 function validateCreateRequest(raw) {
     if (!isPlainObject(raw))
         throw invalid('request body is required');
-    requireNoExtraKeys(raw, ['page', 'delivery', 'source', 'creator_cwd', 'action'], 'the request body');
+    requireNoExtraKeys(raw, ['page', 'delivery', 'source', 'requester_node_id', 'creator_cwd', 'action'], 'the request body');
     const source = validateSource(raw['source']);
+    const requesterNodeId = validateRequesterNodeId(raw['requester_node_id']);
     const action = validateActionSelection(raw['action']);
     return {
         page: validatePage(raw['page']),
-        delivery: validateCreateDelivery(raw['delivery']),
+        delivery: validateCreateDelivery(raw['delivery'], requesterNodeId),
         ...(source === undefined ? {} : { source }),
+        requesterNodeId,
         creatorCwd: validateCreatorCwd(raw['creator_cwd']),
         ...(action === undefined ? {} : { action }),
     };
 }
-function validateReplaceRequest(raw, priorDelivery) {
+function validateReplaceRequest(raw, prior) {
     if (!isPlainObject(raw))
         throw invalid('request body is required');
     requireNoExtraKeys(raw, ['page', 'delivery'], 'the request body');
-    return { page: validatePage(raw['page']), delivery: validateReplaceDelivery(raw['delivery'], priorDelivery) };
+    return { page: validatePage(raw['page']), delivery: validateReplaceDelivery(raw['delivery'], prior) };
 }
 function optionalBoundedString(raw, field, max) {
     if (raw === undefined)
         return undefined;
-    if (typeof raw !== 'string')
-        throw invalid(`\`${field}\` must be a string`);
-    if (raw.trim() === '' || raw.length > max)
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > max)
         throw invalid(`\`${field}\` must be nonempty after trim and at most ${max} characters`);
     return raw;
 }
@@ -173,92 +163,111 @@ function validateSettleRequest(raw) {
     const actor = optionalBoundedString(raw['actor'], 'actor', ACTOR_MAX);
     return { ...(reason === undefined ? {} : { reason }), ...(actor === undefined ? {} : { actor }) };
 }
-function resolveRequest(ctx) {
-    const requestId = requireTicketId({ ticket_id: ctx.params['request_id'] ?? '' });
-    const resolved = resolveTicket(requestId);
-    if (resolved === null || resolved.kind !== 'page')
+function requestId(ctx) {
+    const id = ctx.params['request_id'];
+    if (typeof id !== 'string' || id === '')
+        throw invalid('request id is required');
+    return id;
+}
+function requirePageRequest(id) {
+    const request = getRequest(id);
+    if (request === null || request.kind !== 'page')
         throw new ApiError(404, 'not_found', 'no request with that id');
-    let manifest;
+    return request;
+}
+function manifest(request) {
     try {
-        manifest = parsePage(resolved.dir);
+        const value = JSON.parse(request.specification_json);
+        if (!isPlainObject(value))
+            throw new Error('not an object');
+        return value;
     }
     catch {
-        throw new ApiError(500, 'internal', 'the request could not be read');
+        throw new ApiError(500, 'internal', 'the request specification could not be read');
     }
-    return {
-        requestId,
-        ticketId: resolved.ticketId,
-        dir: resolved.dir,
-        manifest,
-        result: readTicketResult(resolved.dir),
-        binding: readTicketActionBinding(resolved.dir),
-    };
 }
-function requestState(result) {
-    if (result === null)
+function terminalResult(request) {
+    if (request.result_json === null)
+        return null;
+    try {
+        return JSON.parse(request.result_json);
+    }
+    catch {
+        throw new ApiError(500, 'internal', 'the request result could not be read');
+    }
+}
+function frozenAction(request) {
+    if (request.action_json === null)
+        return null;
+    try {
+        const action = JSON.parse(request.action_json);
+        if (action.schema !== 'crtr.human-action-binding/v1' || typeof action.name !== 'string')
+            throw new Error('invalid action');
+        return action;
+    }
+    catch {
+        throw new ApiError(500, 'internal', 'the request action could not be read');
+    }
+}
+function requestState(request) {
+    if (request.state !== 'settled')
         return 'pending';
-    if (result.kind === 'canceled')
-        return completionEventFor(result);
-    return 'answered';
+    return request.outcome === 'answered' ? 'answered' : request.outcome === 'dismissed' ? 'dismissed' : 'canceled';
 }
-function deliveryDetail(row) {
-    if (row === null)
+function deliveryDetail(request) {
+    if (request.action_delivery_id === null)
         return { state: 'none', attempt: 0 };
-    const detail = { state: row.state, attempt: row.attempt };
-    // A next attempt is only meaningful for a pending retry; the enqueue instant
-    // of an untried delivery says nothing a client can act on.
-    if (row.state === 'pending' && row.lastFailure !== null)
-        detail.next_attempt_at = new Date(row.nextAttemptAt).toISOString();
-    if (row.acceptedAt !== null)
-        detail.accepted_at = new Date(row.acceptedAt).toISOString();
-    if (row.permanentFailedAt !== null)
-        detail.permanent_failed_at = new Date(row.permanentFailedAt).toISOString();
-    if (row.lastFailure !== null) {
-        const failure = row.lastFailure;
-        detail.last_failure = {
-            kind: failure.kind,
-            ...(failure.exitCode === undefined ? {} : { exit_code: failure.exitCode }),
-            ...(failure.signal === undefined ? {} : { signal: failure.signal }),
-            ...(failure.message === undefined ? {} : { message: failure.message }),
-            ...(failure.stderr === undefined ? {} : { stderr: failure.stderr }),
-        };
-    }
+    const delivery = readExternalActionDelivery(`human-action:${request.inbox_ticket_id}`);
+    if (delivery === null)
+        return { state: 'none', attempt: 0 };
+    const state = delivery.state === 'acknowledged' ? 'accepted' : delivery.state === 'permanent_failed' ? 'permanent_failed' : delivery.state === 'handed_off' ? 'running' : 'pending';
+    const detail = { state, attempt: delivery.attempts };
+    if (state === 'pending' && delivery.nextAttemptAt !== null)
+        detail.next_attempt_at = new Date(delivery.nextAttemptAt).toISOString();
+    if (delivery.acknowledgedAt !== null)
+        detail.accepted_at = new Date(delivery.acknowledgedAt).toISOString();
+    if (delivery.failedAt !== null)
+        detail.permanent_failed_at = new Date(delivery.failedAt).toISOString();
+    if (delivery.lastFailure !== null)
+        detail.last_failure = delivery.lastFailure;
     return detail;
 }
 function requestToDTO(request) {
-    const { manifest, result, binding } = request;
-    const emittedAt = manifest.source?.emittedAt;
-    if (emittedAt === undefined)
-        throw new ApiError(500, 'internal', 'the request carries no emitted time');
-    const state = requestState(result);
+    const page = manifest(request);
+    const result = terminalResult(request);
+    const state = requestState(request);
     const dto = {
-        request_id: request.requestId,
+        request_id: request.request_id,
+        inbox_ticket_id: request.inbox_ticket_id,
+        request_dir: request.request_dir,
+        kind: request.kind,
         state,
-        title: manifest.title,
-        source: manifest.source ?? {},
-        emitted_at: emittedAt,
+        title: request.title,
+        source: page.source ?? {},
+        emitted_at: page.source?.emittedAt ?? request.created_at,
     };
-    if (manifest.subtitle !== undefined)
-        dto.subtitle = manifest.subtitle;
+    if (request.subtitle !== null)
+        dto.subtitle = request.subtitle;
+    if (request.kind === 'page')
+        dto.page = inboxPageProjection(request);
     if (result !== null) {
-        dto.settled_at = result.kind === 'canceled' ? result.canceledAt : result.completedAt;
-        // Never fabricated for a dismissal or a withdrawal: only an answer has responses.
-        if (state === 'answered' && result.kind === 'page')
+        dto.settled_at = request.settled_at ?? request.updated_at;
+        if (result.kind === 'page' && state === 'answered')
             dto.responses = result.responses;
         if (result.kind === 'canceled' && result.reason !== undefined)
             dto.reason = result.reason;
-        const actor = result.kind === 'review' ? undefined : result.actor;
-        if (actor !== undefined)
-            dto.actor = actor;
+        if (result.kind === 'page' && result.actor !== undefined)
+            dto.actor = result.actor;
+        if (result.kind === 'canceled' && result.actor !== undefined)
+            dto.actor = result.actor;
     }
-    if (binding !== null) {
-        dto.action = { name: binding.name, payload: binding.payload };
-        dto.delivery = deliveryDetail(readActionDelivery(request.requestId));
+    const action = frozenAction(request);
+    if (action !== null) {
+        dto.action = { name: action.name, payload: action.payload };
+        dto.delivery = deliveryDetail(request);
     }
     return dto;
 }
-// POST /v1/human/requests — create
-/** Authoring failure is the caller's malformed page, never a server fault. */
 function prepareOrReject(dialect, document, source, delivery) {
     try {
         return preparePageSource({ dialect, document, source, delivery, productKinds: resolvePageComponents() });
@@ -269,9 +278,7 @@ function prepareOrReject(dialect, document, source, delivery) {
 }
 function handleCreate(ctx) {
     const request = validateCreateRequest(ctx.body);
-    // Action resolution precedes every write: a rejected action must leave no
-    // inbox row for a human to answer.
-    let resolvedAction;
+    let actionJson;
     if (request.action !== undefined) {
         const resolution = resolveHumanAction(request.action.name, request.creatorCwd);
         if ('kind' in resolution) {
@@ -280,120 +287,93 @@ function handleCreate(ctx) {
                 : `${resolution.name} is declared in ${resolution.configOrigin} but unusable: ${resolution.reason}`;
             throw new ApiError(400, resolution.kind, detail);
         }
-        resolvedAction = resolution;
-    }
-    const prepared = prepareOrReject(request.page.dialect, request.page.source, request.source, request.delivery);
-    const dir = ticketDir(`page-${randomBytes(8).toString('hex')}`);
-    // The binding is written before the page exists, so a visible request is
-    // never momentarily unbound and `replace` can never reach the approved effect.
-    if (request.action !== undefined && resolvedAction !== undefined) {
-        publishTicketActionBinding(dir, {
-            schema: 'crtr.human-action-binding/v1',
-            name: request.action.name,
-            payload: request.action.payload,
-            creatorCwd: request.creatorCwd,
-            configOrigin: resolvedAction.configOrigin,
-            argv: resolvedAction.argv,
-            cwd: resolvedAction.cwd,
+        actionJson = JSON.stringify({
+            schema: 'crtr.human-action-binding/v1', name: request.action.name, payload: request.action.payload,
+            creatorCwd: request.creatorCwd, configOrigin: resolution.configOrigin, argv: resolution.argv, cwd: resolution.cwd,
         });
     }
-    const published = publishPage(dir, prepared);
+    const prepared = prepareOrReject(request.page.dialect, request.page.source, request.source, request.delivery);
+    const created = createPageRequest({
+        prepared,
+        requester_node_id: request.requesterNodeId,
+        ...(actionJson === undefined ? {} : { action_json: actionJson }),
+    });
     return {
         status: 201,
-        body: {
-            request_id: opaqueInboxTicketId(basename(published.dir)),
-            state: 'pending',
-            ...(request.action === undefined ? {} : { action: { name: request.action.name } }),
-            delivery_state: 'none',
-        },
+        body: { request_id: created.request_id, request_dir: created.request_dir, state: 'pending', ...(request.action === undefined ? {} : { action: { name: request.action.name } }), delivery_state: 'none' },
     };
 }
-// GET /v1/human/requests/:request_id — read
 function handleGet(ctx) {
-    return { status: 200, body: requestToDTO(resolveRequest(ctx)) };
+    return { status: 200, body: requestToDTO(requirePageRequest(requestId(ctx))) };
 }
-// POST /v1/human/requests/:request_id/replace — revise the pending page
 function handleReplace(ctx) {
-    const request = resolveRequest(ctx);
-    if (request.result !== null)
+    const request = requirePageRequest(requestId(ctx));
+    if (request.state === 'settled')
         throw new ApiError(409, 'already_settled', 'the request already has a terminal result');
-    const body = validateReplaceRequest(ctx.body, request.manifest.delivery);
-    // Identity and provenance are the creation's, verbatim — a revision changes
-    // only what is on screen, never who asked or when.
-    const prepared = prepareOrReject(body.page.dialect, body.page.source, request.manifest.source, body.delivery);
-    publishPage(request.dir, prepared);
-    return { status: 200, body: requestToDTO({ ...request, manifest: prepared.manifest }) };
+    const page = manifest(request);
+    const body = validateReplaceRequest(ctx.body, page.delivery);
+    const prepared = prepareOrReject(body.page.dialect, body.page.source, page.source, body.delivery);
+    try {
+        publishPage(request.request_dir, prepared);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === `page request is not open: ${request.request_id}`) {
+            throw new ApiError(409, 'already_settled', 'the request already has a terminal result');
+        }
+        throw error;
+    }
+    return { status: 200, body: requestToDTO(requirePageRequest(request.request_id)) };
 }
-// Settlement — respond, dismiss, cancel
-/** The settlement funnels speak the inbox's error vocabulary; requests speak
- * the wire contract's. This is the one translation. */
 function settlementError(error) {
-    if (error instanceof ApiError) {
-        if (error.code === 'ticket_already_resolved')
-            return new ApiError(409, 'already_settled', 'the request already has a terminal result');
-        if (error.code === 'page_has_no_response_lifecycle')
-            return new ApiError(409, 'not_settleable', 'this request carries no response lifecycle');
+    if (error instanceof ApiError)
         return error;
-    }
-    if (error instanceof Error && error.message === 'page_has_no_response_lifecycle') {
+    if (error instanceof Error && error.message.includes('unknown page request'))
+        return new ApiError(404, 'not_found', 'no request with that id');
+    if (error instanceof Error && error.message === 'page_has_no_response_lifecycle')
         return new ApiError(409, 'not_settleable', 'this request carries no response lifecycle');
-    }
     return new ApiError(500, 'internal', 'the request could not be settled');
 }
 function requireSettleable(request) {
-    if (request.result !== null)
+    if (request.state === 'settled')
         throw new ApiError(409, 'already_settled', 'the request already has a terminal result');
-    if (readPageTicket(request.dir).state === 'passive') {
+    if (!request.settleable)
         throw new ApiError(409, 'not_settleable', 'this request carries no response lifecycle');
-    }
 }
 async function handleRespond(ctx) {
-    const request = resolveRequest(ctx);
+    const request = requirePageRequest(requestId(ctx));
     const body = validateRespondRequest(ctx.body);
     requireSettleable(request);
     try {
-        validatePageTicketResponses(request.dir, body.responses);
+        validatePageTicketResponses(request.request_dir, body.responses);
     }
     catch (error) {
-        // `requireSettleable` already refused a page with no response lifecycle, so
-        // anything left here is the caller's response map.
         throw invalid(error instanceof Error ? error.message : 'the response map is invalid');
     }
-    let result;
     try {
-        result = await resolvePageTicket(request.ticketId, body.responses, body.actor === undefined ? {} : { actor: body.actor });
+        await resolvePageTicket(request.request_id, body.responses, body.actor === undefined ? {} : { actor: body.actor });
     }
     catch (error) {
         throw settlementError(error);
     }
-    return { status: 200, body: requestToDTO({ ...request, result, binding: request.binding }) };
+    return { status: 200, body: requestToDTO(requirePageRequest(request.request_id)) };
 }
 async function settle(ctx, disposition) {
-    const request = resolveRequest(ctx);
+    const request = requirePageRequest(requestId(ctx));
     const body = validateSettleRequest(ctx.body);
     requireSettleable(request);
-    let result;
     try {
-        result = await cancelHumanTicket(request.ticketId, { ...body, disposition });
+        await cancelHumanTicket(request.request_id, { ...body, disposition });
     }
     catch (error) {
         throw settlementError(error);
     }
-    return { status: 200, body: requestToDTO({ ...request, result }) };
-}
-/** The recipient surface deliberately closing the request without answering. */
-function handleDismiss(ctx) {
-    return settle(ctx, 'dismissed');
-}
-/** The requester withdrawing its own request. */
-function handleCancel(ctx) {
-    return settle(ctx, 'canceled');
+    return { status: 200, body: requestToDTO(requirePageRequest(request.request_id)) };
 }
 export const humanRequestRoutes = [
     { method: 'POST', pattern: '/v1/human/requests', handler: handleCreate },
     { method: 'GET', pattern: '/v1/human/requests/:request_id', handler: handleGet },
     { method: 'POST', pattern: '/v1/human/requests/:request_id/replace', handler: handleReplace },
     { method: 'POST', pattern: '/v1/human/requests/:request_id/respond', handler: handleRespond },
-    { method: 'POST', pattern: '/v1/human/requests/:request_id/dismiss', handler: handleDismiss },
-    { method: 'POST', pattern: '/v1/human/requests/:request_id/cancel', handler: handleCancel },
+    { method: 'POST', pattern: '/v1/human/requests/:request_id/dismiss', handler: (ctx) => settle(ctx, 'dismissed') },
+    { method: 'POST', pattern: '/v1/human/requests/:request_id/cancel', handler: (ctx) => settle(ctx, 'canceled') },
 ];