@north-light/api 0.3.580 → 0.3.587

package/dist/core/human/requests.js

@@ -0,0 +1,619 @@
+import { prepared as cachedStatement } from '../sqlite-statements.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { z } from 'zod';
+import { crtrHome, isSafeNodeId, nodesRoot } from '../canvas/paths.js';
+import { withCanvasWrite, openDb } from '../canvas/db.js';
+import { syncDirectory, syncFile } from '../fs-utils.js';
+import { newNodeId } from '../runtime/nodes.js';
+import { pageManifestPath, pageModulePath, pagePath } from './convention.js';
+import { preparePageSource } from './page-authoring.js';
+import { pageAwaitsResponse, pageDeliverySchema, pageIsNoticeSql, validatePageManifest } from './page-schema.js';
+import { appendWaitingOnUser } from '../runs/questions.js';
+import { isCloudRole } from '../canvas/person.js';
+import { REQUEST_BLOB_PREFIX, isBlobRequestPath, writeRequestFile } from './request-files.js';
+function bool(value) { return value === 1 || value === true; }
+function recordFromRow(raw) {
+    return {
+        request_id: raw['request_id'],
+        kind: raw['kind'],
+        inbox_ticket_id: raw['inbox_ticket_id'],
+        request_dir: raw['request_dir'],
+        presentation_dir: raw['presentation_dir'],
+        requester_node_id: raw['requester_node_id'],
+        companion_node_id: raw['companion_node_id'],
+        idempotency_key: raw['idempotency_key'],
+        state: raw['state'],
+        outcome: raw['outcome'],
+        inbox_listed: bool(raw['inbox_listed']),
+        settleable: bool(raw['settleable']),
+        title: raw['title'],
+        subtitle: raw['subtitle'],
+        file: raw['file'],
+        specification_json: raw['specification_json'],
+        action_json: raw['action_json'],
+        progress_json: raw['progress_json'],
+        feedback_json: raw['feedback_json'],
+        result_json: raw['result_json'],
+        anchor_base_sha256: raw['anchor_base_sha256'],
+        anchor_base_bytes: raw['anchor_base_bytes'] === null ? null : Buffer.from(raw['anchor_base_bytes']),
+        created_at: raw['created_at'],
+        opened_at: raw['opened_at'],
+        submit_requested_at: raw['submit_requested_at'],
+        settled_at: raw['settled_at'],
+        settlement_delivery_id: raw['settlement_delivery_id'],
+        action_delivery_id: raw['action_delivery_id'],
+        submit_note_delivery_id: raw['submit_note_delivery_id'],
+        projected_at: raw['projected_at'],
+        projection_error: raw['projection_error'],
+        companion_retired_at: raw['companion_retired_at'],
+        updated_at: raw['updated_at'],
+    };
+}
+async function one(db, where, ...params) {
+    const raw = await db.prepareUncached(`SELECT * FROM human_requests WHERE ${where}`).get(...params);
+    return raw === undefined ? null : recordFromRow(raw);
+}
+async function many(db, where, params = [], order = 'created_at ASC, request_id ASC') {
+    return (await db.prepareUncached(`SELECT * FROM human_requests WHERE ${where} ORDER BY ${order}`).all(...params)).map(recordFromRow);
+}
+export function humanRequestsRoot() { return join(crtrHome(), 'requests'); }
+/** Where a new request's files live: the blob prefix `requests/<id>` on a cloud role (its API processes share no disk), else a directory under the install's home. */
+export function requestDir(requestId) {
+    if (!isSafeNodeId(requestId))
+        throw new TypeError(`request_id must be a safe path segment: ${requestId}`);
+    if (isCloudRole())
+        return `${REQUEST_BLOB_PREFIX}${requestId}`;
+    const root = humanRequestsRoot();
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    return join(realpathSync(root), requestId);
+}
+function randomTicketId() { return randomBytes(32).toString('hex'); }
+function legacyTicketId(root, name) {
+    return createHash('sha256').update(`${realpathSync(root)}\0${name}`, 'utf8').digest('hex');
+}
+const durablePageRevisionStorage = {
+    writeFile(path, content) { writeFileSync(path, content, { flag: 'wx', mode: 0o600 }); },
+    syncFile,
+    syncDirectory,
+};
+function revisionRoot(dir) { return join(dir, 'revisions'); }
+/** Publish a complete, immutable revision before a request can select it. */
+export function publishPageRevision(dir, prepared, storage = durablePageRevisionStorage) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const revisions = revisionRoot(dir);
+    mkdirSync(revisions, { recursive: true, mode: 0o700 });
+    const revision = join(revisions, randomBytes(16).toString('hex'));
+    mkdirSync(revision, { mode: 0o700 });
+    const document = pagePath(revision, prepared.manifest.dialect);
+    storage.writeFile(document, prepared.document);
+    storage.syncFile(document);
+    if (prepared.manifest.dialect === 'jsx') {
+        const module = pageModulePath(revision);
+        storage.writeFile(module, prepared.module);
+        storage.syncFile(module);
+    }
+    const manifest = pageManifestPath(revision);
+    storage.writeFile(manifest, `${JSON.stringify(prepared.manifest, null, 2)}\n`);
+    storage.syncFile(manifest);
+    storage.syncDirectory(revision);
+    storage.syncDirectory(revisions);
+    storage.syncDirectory(dir);
+    storage.syncDirectory(humanRequestsRoot());
+    return revision;
+}
+/** {@link publishPageRevision} for a request directory that is a blob prefix (a cloud role or an imported request) or a local directory. */
+export async function publishPageRevisionTo(dir, prepared) {
+    if (!isBlobRequestPath(dir))
+        return publishPageRevision(dir, prepared);
+    const revision = `${dir}/revisions/${randomBytes(16).toString('hex')}`;
+    await writeRequestFile(pageManifestPath(revision), `${JSON.stringify(prepared.manifest, null, 2)}\n`);
+    await writeRequestFile(pagePath(revision, prepared.manifest.dialect), prepared.document);
+    if (prepared.manifest.dialect === 'jsx')
+        await writeRequestFile(pageModulePath(revision), prepared.module);
+    return revision;
+}
+/** The SQL-selected page revision. There is no path-based fallback for page reads. */
+export function presentationDir(request) {
+    if (request.kind !== 'page' || request.presentation_dir === null)
+        throw new Error(`page request has no selected presentation: ${request.request_id}`);
+    return request.presentation_dir;
+}
+/** Creates one SQL-authoritative page request. `request_id` is optional for ordinary callers and frozen by cron creation. */
+export async function createPageRequest(input) {
+    const requestId = input.request_id ?? await newNodeId();
+    const dir = requestDir(requestId);
+    const selectedPresentation = await publishPageRevisionTo(dir, input.prepared);
+    const at = new Date().toISOString();
+    const manifest = input.prepared.manifest;
+    return await withCanvasWrite(async (db) => {
+        await db.prepare(`
+      INSERT INTO human_requests (
+        request_id, kind, inbox_ticket_id, request_dir, presentation_dir, requester_node_id, state, inbox_listed,
+        settleable, title, subtitle, specification_json, action_json, created_at, updated_at
+      ) VALUES (?, 'page', ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(requestId, input.inbox_ticket_id ?? randomTicketId(), dir, selectedPresentation, input.requester_node_id ?? null, manifest.delivery.inbox ? 1 : 0, manifest.delivery.inbox || manifest.delivery.reply ? 1 : 0, manifest.title, manifest.subtitle ?? null, JSON.stringify(manifest), input.action_json ?? null, at, at);
+        const request = await one(db, 'request_id = ?', requestId);
+        if (request === null)
+            throw new Error(`page request insert did not produce a row: ${requestId}`);
+        // A question from a run is carried on that run's stream in the same write.
+        await appendWaitingOnUser(db, request);
+        return request;
+    });
+}
+/** Claims a review idempotency key before companion realization. */
+export async function commitBindingRequest(input) {
+    return await withCanvasWrite(async (db) => {
+        const inserted = await db.prepare(`
+      INSERT INTO human_requests (
+        request_id, kind, inbox_ticket_id, request_dir, requester_node_id, companion_node_id,
+        idempotency_key, state, inbox_listed, settleable, title, subtitle, file,
+        specification_json, anchor_base_sha256, anchor_base_bytes, created_at, updated_at
+      ) VALUES (?, 'review', ?, ?, ?, ?, ?, 'binding', ?, 1, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(idempotency_key) DO NOTHING
+    `).run(input.request_id, randomTicketId(), input.request_dir, input.requester_node_id, input.companion_node_id, input.idempotency_key, input.inbox_listed ? 1 : 0, input.title ?? basename(input.file), input.subtitle ?? null, input.file, JSON.stringify(input.specification), input.anchor_base_sha256, input.anchor_base_bytes, input.created_at, input.created_at);
+        const winner = await one(db, 'idempotency_key = ?', input.idempotency_key);
+        if (winner === null)
+            throw new Error(`review binding insert did not produce a row: ${input.idempotency_key}`);
+        return { request_id: winner.request_id, won: inserted.changes > 0 };
+    });
+}
+export async function getRequest(requestId) { return await one(await openDb(), 'request_id = ?', requestId); }
+export async function getRequestByInboxTicket(ticketId) { return await one(await openDb(), 'inbox_ticket_id = ?', ticketId); }
+export async function getRequestByDirectory(dir) {
+    let canonical = dir;
+    if (!isBlobRequestPath(dir)) {
+        try {
+            canonical = realpathSync(dir);
+        }
+        catch { /* A caller may name a request directory before it exists. */ }
+    }
+    return await one(await openDb(), 'request_dir = ?', canonical);
+}
+export async function getRequestByCompanion(nodeId) { return await one(await openDb(), "companion_node_id = ? AND state <> 'binding'", nodeId); }
+export async function getRequestByIdempotencyKey(key) { return await one(await openDb(), 'idempotency_key = ?', key); }
+/** SQL for the node a page request belongs to: its requester, else, for a notice only (a page that takes no response
+ *  and so has no requester), the node that sent it. `alias` is the human_requests table or alias. */
+export const askingNodeSql = (alias) => `COALESCE(${alias}.requester_node_id, CASE WHEN ${alias}.kind = 'page' AND ${pageIsNoticeSql(`${alias}.specification_json`)} THEN ${alias}.specification_json #>> '{source,nodeId}' END)`;
+/** A page asked from a run of an app other than the terminal is that app's to show
+ *  (daemon-operations §question.*: the terminal shows `app:terminal` runs' questions). */
+export const NOT_OTHER_APP_QUESTION = `NOT (kind = 'page' AND EXISTS (SELECT 1 FROM node_rows n WHERE n.node_id = ${askingNodeSql('human_requests')}
+  AND n.run_id IS NOT NULL AND n.grantee IS NOT NULL AND n.grantee <> 'app:terminal'))`;
+export async function listOpenInboxRequests() {
+    return await many(await openDb(), `state = 'open' AND inbox_listed = 1 AND ${NOT_OTHER_APP_QUESTION}`, [], 'created_at DESC, request_id DESC');
+}
+/** Every open request a person is being asked to act on: the inbox's set (`listOpenInboxRequests`), plus
+ *  answerable pages kept out of the inbox. This is the set the attach viewer's inbox strip shows. */
+export async function listPendingAsks() {
+    return (await many(await openDb(), `state = 'open' AND requester_node_id IS NOT NULL AND ((inbox_listed = 1 AND ${NOT_OTHER_APP_QUESTION}) OR (kind = 'page' AND inbox_listed = 0 AND settleable = 1))`, [], 'created_at ASC, request_id ASC'))
+        .filter((request) => request.inbox_listed || pageAwaitsResponse(JSON.parse(request.specification_json)));
+}
+export async function openRequestsByRequester(nodeId) {
+    return await many(await openDb(), "state = 'open' AND requester_node_id = ?", [nodeId], 'created_at DESC, request_id DESC');
+}
+export async function hasOpenReplyBearingRequestByRequester(nodeId) {
+    return (await openRequestsByRequester(nodeId)).some((request) => {
+        if (request.kind === 'review')
+            return true;
+        const specification = JSON.parse(request.specification_json);
+        return specification.delivery?.reply === true;
+    });
+}
+/** Indexed attention projection: only open inbox-listed requests with a reply target keep a node wakeable. */
+export async function listOpenReplyBearingRequests() {
+    return await many(await openDb(), "state = 'open' AND inbox_listed = 1 AND requester_node_id IS NOT NULL", [], 'created_at DESC, request_id DESC');
+}
+export async function listBindingRequests() { return await many(await openDb(), "kind = 'review' AND state = 'binding'"); }
+export async function listSubmitRequestedRequests() { return await many(await openDb(), "kind = 'review' AND state = 'open' AND submit_requested_at IS NOT NULL"); }
+export async function listUnprojectedReviews() { return await many(await openDb(), "kind = 'review' AND state = 'settled' AND projected_at IS NULL"); }
+export async function listRequests(filter = {}) {
+    const clauses = ['true'];
+    const params = [];
+    for (const [column, value] of Object.entries(filter)) {
+        if (value !== undefined) {
+            // History has always belonged to manifest.source.nodeId, which can differ
+            // from requester_node_id on imported or independently published pages.
+            clauses.push(column === 'page_source_node_id'
+                ? "specification_json #>> '{source,nodeId}' = ?" : `${column} = ?`);
+            params.push(value);
+        }
+    }
+    return await many(await openDb(), clauses.join(' AND '), params);
+}
+/** A preflight preserves the old map-before-filter error for malformed page results. */
+export async function hasPageResultException() {
+    return await (await openDb()).prepare(`
+    SELECT 1 FROM human_requests
+    WHERE kind = 'page' AND result_json IS NOT NULL
+      AND (result_json ->> 'kind') = 'page'
+      AND jsonb_typeof(result_json -> 'summary') IS DISTINCT FROM 'string'
+    LIMIT 1
+  `).get() !== undefined;
+}
+export async function firstInvalidPageSpecification() {
+    return await (await openDb()).prepare(`
+    SELECT request_id, specification_json FROM human_requests
+    WHERE kind = 'page' AND jsonb_typeof(specification_json) <> 'object'
+    ORDER BY created_at ASC, request_id ASC LIMIT 1
+  `).get() ?? null;
+}
+export async function openRequest(requestId, openedAt) {
+    return (await (await openDb()).prepare("UPDATE human_requests SET state = 'open', opened_at = ?, updated_at = ? WHERE request_id = ? AND state = 'binding'").run(openedAt, openedAt, requestId)).changes > 0;
+}
+/** A binding whose immutable branch disappeared never recaptures a new origin. */
+export async function cancelBindingRequest(requestId, at, reason) {
+    return (await (await openDb()).prepare(`
+    UPDATE human_requests SET state = 'settled', outcome = 'canceled', result_json = ?, settled_at = ?, updated_at = ?
+    WHERE request_id = ? AND kind = 'review' AND state = 'binding'
+  `).run(JSON.stringify({ schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: at, reason }), at, at, requestId)).changes > 0;
+}
+export async function requestSubmit(requestId, at) {
+    return (await (await openDb()).prepare("UPDATE human_requests SET submit_requested_at = ?, updated_at = ? WHERE request_id = ? AND kind = 'review' AND state = 'open' AND submit_requested_at IS NULL").run(at, at, requestId)).changes > 0;
+}
+/** The first-writer-wins terminal transition. Callers add obligations in this same `withCanvasWrite` boundary. */
+export async function settleRequestLocked(db, args) {
+    const changed = (await db.prepare(`
+    UPDATE human_requests SET state = 'settled', outcome = ?, result_json = ?, settled_at = ?,
+      progress_json = NULL, updated_at = ?
+    WHERE request_id = ? AND state = 'open'
+  `).run(args.outcome, args.result_json, args.settled_at, args.settled_at, args.request_id)).changes;
+    return changed === 0 ? null : await one(db, 'request_id = ?', args.request_id);
+}
+export async function setSettlementDeliveryMarksLocked(db, requestId, marks) {
+    await db.prepare(`UPDATE human_requests SET settlement_delivery_id = ?, action_delivery_id = ?, updated_at = ? WHERE request_id = ?`).run(marks.settlement_delivery_id ?? null, marks.action_delivery_id ?? null, new Date().toISOString(), requestId);
+}
+export async function setSubmitNoteDeliveryLocked(db, requestId, deliveryId) {
+    return (await db.prepare(`UPDATE human_requests SET submit_note_delivery_id = ?, updated_at = ? WHERE request_id = ? AND state = 'open' AND submit_note_delivery_id IS NULL`).run(deliveryId, new Date().toISOString(), requestId)).changes > 0;
+}
+export async function revisePageRequest(requestId, values) {
+    return (await (await openDb()).prepare(`
+    UPDATE human_requests SET presentation_dir = ?, specification_json = ?, title = ?, subtitle = ?, inbox_listed = ?, settleable = ?, updated_at = ?
+    WHERE request_id = ? AND kind = 'page' AND state = 'open'
+  `).run(values.presentation_dir, values.specification_json, values.title, values.subtitle, values.inbox_listed ? 1 : 0, values.settleable ? 1 : 0, new Date().toISOString(), requestId)).changes > 0;
+}
+export async function writeProgress(ticketId, responses) {
+    return (await (await openDb()).prepare(`
+    UPDATE human_requests SET progress_json = ?, updated_at = ?
+    WHERE inbox_ticket_id = ? AND kind = 'page' AND state = 'open' AND settleable = 1
+  `).run(JSON.stringify({ kind: 'page', responses, savedAt: new Date().toISOString() }), new Date().toISOString(), ticketId)).changes > 0;
+}
+export async function markProjected(requestId, at) {
+    await (await openDb()).prepare(`UPDATE human_requests SET projected_at = ?, projection_error = NULL, updated_at = ? WHERE request_id = ?`).run(at, at, requestId);
+}
+export async function markProjectionError(requestId, error) {
+    await (await openDb()).prepare(`UPDATE human_requests SET projection_error = ?, updated_at = ? WHERE request_id = ? AND projected_at IS NULL`).run(error, new Date().toISOString(), requestId);
+}
+export async function markCompanionRetired(requestId, at) {
+    await (await openDb()).prepare(`UPDATE human_requests SET companion_retired_at = ?, updated_at = ? WHERE request_id = ? AND companion_retired_at IS NULL`).run(at, at, requestId);
+}
+export async function readAnchorBase(requestId) {
+    const row = await (await openDb()).prepare('SELECT anchor_base_bytes, anchor_base_sha256 FROM human_requests WHERE request_id = ?').get(requestId);
+    return row === undefined || row.anchor_base_bytes === null || row.anchor_base_sha256 === null ? null : { bytes: Buffer.from(row.anchor_base_bytes), sha256: row.anchor_base_sha256 };
+}
+export async function replaceAnchorBaseLocked(db, requestId, bytes, sha256) {
+    await db.prepare('UPDATE human_requests SET anchor_base_bytes = ?, anchor_base_sha256 = ?, updated_at = ? WHERE request_id = ?').run(bytes, sha256, new Date().toISOString(), requestId);
+}
+function legacyPageResult(result) {
+    if (typeof result !== 'object' || result === null)
+        throw new Error('result is not an object');
+    const row = result;
+    if (row['kind'] === 'canceled')
+        return { outcome: row['disposition'] === 'dismissed' ? 'dismissed' : 'canceled', settledAt: String(row['canceledAt']) };
+    return { outcome: 'answered', settledAt: String(row['completedAt']) };
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`corrupt required input: ${path}`, { cause: error });
+    }
+}
+function migrationId() { return randomBytes(16).toString('hex'); }
+function nextMessageSeq(db) {
+    return Number(cachedStatement(db, 'SELECT COALESCE(MAX(seq), 0) AS seq FROM messages').get().seq) + 1;
+}
+function importedTerminalDelivery(db, requestId, requesterNodeId, kind) {
+    const row = kind === 'page'
+        ? cachedStatement(db, `SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+        WHERE d.destination_kind = 'node_inbox' AND d.destination_id = ? AND m.sender_node_id = ?
+          AND m.disposition IN ('human-answer', 'human-canceled') LIMIT 1`).get(requesterNodeId, requestId)
+        : cachedStatement(db, `SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+        WHERE d.destination_kind = 'node_inbox' AND d.destination_id = ? AND m.body_json LIKE ? LIMIT 1`).get(requesterNodeId, `%\"review_id\":\"${requestId}\"%`);
+    return row?.delivery_id ?? null;
+}
+function companionRetirementProven(db, companionNodeId, outcome) {
+    if (companionNodeId === null || outcome === null)
+        return false;
+    const row = cachedStatement(db, 'SELECT status, final_report FROM nodes WHERE node_id = ?').get(companionNodeId);
+    return row?.status === 'canceled' || (outcome === 'approved' && row?.status === 'done' && row.final_report !== null);
+}
+function migratedCancellationReason(result) {
+    if (typeof result !== 'object' || result === null)
+        return 'no reason was given';
+    const reason = result['reason'];
+    return typeof reason === 'string' && reason !== '' ? reason : 'no reason was given';
+}
+function migratedTerminalBody(input, result) {
+    const canceled = input.outcome === 'canceled' || input.outcome === 'dismissed';
+    const summary = input.kind === 'review'
+        ? canceled
+            ? `Review ${input.requestId} was canceled — ${migratedCancellationReason(result)}.`
+            : `Review ${input.requestId} was approved by the user.`
+        : canceled
+            ? `Human request ${input.requestId} was canceled — ${migratedCancellationReason(result)}.`
+            : `Human request ${input.requestId} was answered.`;
+    return [
+        summary,
+        ...(input.kind === 'review' ? [`The review result is at ${input.requestDir}/result.json.`] : []),
+        `Result:\n${JSON.stringify(result, null, 2)}`,
+    ].join('\n\n');
+}
+function createMigratedTerminalDelivery(db, input) {
+    const messageId = migrationId();
+    const deliveryId = migrationId();
+    const now = Date.parse(input.settledAt);
+    const createdAt = Number.isFinite(now) ? now : 0;
+    const disposition = input.outcome === 'answered' || input.outcome === 'approved' ? 'human-answer' : 'human-canceled';
+    const result = JSON.parse(input.resultJson);
+    const body = migratedTerminalBody(input, result);
+    cachedStatement(db, `INSERT INTO messages
+    (message_id, seq, operation_id, created_at, sender_node_id, sender_name, kind, label, body_ref, body_json, disposition)
+    VALUES (?, ?, ?, ?, NULL, 'crtrd', 'completed', ?, NULL, ?, ?)`)
+        .run(messageId, nextMessageSeq(db), migrationId(), input.settledAt, body.split('\n', 1)[0], JSON.stringify({ body, result }), disposition);
+    cachedStatement(db, `INSERT INTO deliveries
+    (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, created_at, updated_at)
+    VALUES (?, ?, 'node_inbox', ?, 'normal', 1, 'pending', 0, ?, ?)`)
+        .run(deliveryId, messageId, input.requesterNodeId, createdAt, createdAt);
+    return deliveryId;
+}
+function terminalDeliveryMark(db, input) {
+    if (input.requesterNodeId === null || input.outcome === null || input.resultJson === null || input.settledAt === null)
+        return null;
+    const imported = importedTerminalDelivery(db, input.requestId, input.requesterNodeId, input.kind);
+    if (imported !== null)
+        return imported;
+    if (input.deliveredAt !== null && input.deliveredAt !== undefined)
+        return null;
+    return createMigratedTerminalDelivery(db, {
+        requestId: input.requestId, requesterNodeId: input.requesterNodeId, kind: input.kind,
+        outcome: input.outcome, resultJson: input.resultJson, settledAt: input.settledAt, requestDir: input.requestDir,
+    });
+}
+/** Imports every legacy page and review inside the caller's already-open migration transaction. */
+const legacyPageSourceSchema = z.object({
+    sessionName: z.string().optional(),
+    askedBy: z.string().optional(),
+    blockedSince: z.string().optional(),
+    profileName: z.string().optional(),
+    nodeId: z.string().optional(),
+}).strict();
+const legacyPageSlotSchema = z.object({
+    id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).optional(),
+    kind: z.string().min(1),
+    step: z.number().int().nonnegative(),
+    config: z.record(z.string(), z.unknown()),
+    unvalidated: z.literal(true).optional(),
+    display: z.literal(true).optional(),
+}).strict();
+const legacyPageManifestSchema = z.object({
+    schema: z.literal('crtr.page/v1'),
+    dialect: z.enum(['md', 'html', 'jsx']),
+    title: z.string().trim().min(1),
+    subtitle: z.string().optional(),
+    placement: z.enum(['inline', 'panel']),
+    document: z.enum(['page.md', 'page.html', 'page.tsx']),
+    steps: z.number().int().positive(),
+    slots: z.array(legacyPageSlotSchema),
+    source: legacyPageSourceSchema.optional(),
+}).strict().superRefine((manifest, ctx) => {
+    const document = manifest.dialect === 'md' ? 'page.md' : manifest.dialect === 'html' ? 'page.html' : 'page.tsx';
+    if (manifest.document !== document)
+        ctx.addIssue({ code: 'custom', path: ['document'], message: 'document must agree with dialect' });
+    if (manifest.dialect === 'md' && manifest.steps !== 1)
+        ctx.addIssue({ code: 'custom', path: ['steps'], message: 'md pages have exactly one step' });
+});
+function legacyPresentationSource(manifest) {
+    if (manifest.source === undefined)
+        return undefined;
+    const { blockedSince, ...source } = manifest.source;
+    const normalized = { ...source, ...(blockedSince !== undefined && z.string().datetime({ offset: true }).safeParse(blockedSince).success ? { emittedAt: blockedSince } : {}) };
+    return Object.keys(normalized).length === 0 ? undefined : normalized;
+}
+/** A discontinued v1 page is replayed as a static JSX page so current readers retain its authored bytes without reviving the retired dialect. */
+function legacyReplayDocument(title, subtitle, document) {
+    return `export default function LegacyPage() { return <Page title={${JSON.stringify(title)}}${subtitle === undefined ? '' : ` subtitle={${JSON.stringify(subtitle)}}`}><pre>{${JSON.stringify(document)}}</pre></Page>; }\n`;
+}
+function withoutLegacyTextEditable(manifest) {
+    if (!Array.isArray(manifest['slots']))
+        return manifest;
+    return {
+        ...manifest,
+        slots: manifest['slots'].map((slot) => {
+            if (typeof slot !== 'object' || slot === null || Array.isArray(slot))
+                return slot;
+            const record = slot;
+            if (record['kind'] !== 'text' || typeof record['config'] !== 'object' || record['config'] === null || Array.isArray(record['config']))
+                return slot;
+            const { editable: _editable, ...config } = record['config'];
+            return { ...record, config };
+        }),
+    };
+}
+function migrateLegacyPage(dir, raw) {
+    const manifestPath = join(dir, 'page.json');
+    const parsed = legacyPageManifestSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(parsed.error.message);
+    const manifest = parsed.data;
+    const source = legacyPresentationSource(manifest);
+    const delivery = {
+        placement: manifest.placement,
+        inbox: true,
+        reply: manifest.source?.blockedSince !== undefined,
+    };
+    validatePageManifest(withoutLegacyTextEditable({
+        schema: 'crtr.page/v2', dialect: 'jsx', title: manifest.title,
+        ...(manifest.subtitle === undefined ? {} : { subtitle: manifest.subtitle }),
+        delivery, document: 'page.tsx', steps: manifest.steps, slots: manifest.slots,
+        ...(source === undefined ? {} : { source }),
+    }));
+    const sourcePath = join(dir, manifest.document);
+    if (!existsSync(sourcePath))
+        throw new Error(`corrupt required input: ${sourcePath}`);
+    const sourceDocument = readFileSync(sourcePath, 'utf8');
+    const prepared = preparePageSource({ dialect: 'jsx', document: legacyReplayDocument(manifest.title, manifest.subtitle, sourceDocument), source, delivery });
+    if (source !== undefined)
+        return prepared;
+    const { source: _source, ...manifestWithoutSource } = prepared.manifest;
+    return { ...prepared, manifest: manifestWithoutSource };
+}
+export function migrateHumanRequestsState(db) {
+    db.exec(`
+    CREATE TABLE human_requests (
+      request_id TEXT PRIMARY KEY, kind TEXT NOT NULL CHECK (kind IN ('page','review')),
+      inbox_ticket_id TEXT NOT NULL UNIQUE, request_dir TEXT NOT NULL, presentation_dir TEXT,
+      requester_node_id TEXT,
+      companion_node_id TEXT UNIQUE, idempotency_key TEXT UNIQUE,
+      state TEXT NOT NULL CHECK (state IN ('binding','open','settled')),
+      outcome TEXT CHECK (outcome IN ('approved','answered','canceled','dismissed')),
+      inbox_listed INTEGER NOT NULL, settleable INTEGER NOT NULL, title TEXT NOT NULL, subtitle TEXT,
+      file TEXT, specification_json TEXT NOT NULL, action_json TEXT, progress_json TEXT, feedback_json TEXT,
+      result_json TEXT, anchor_base_sha256 TEXT, anchor_base_bytes BLOB, created_at TEXT NOT NULL,
+      opened_at TEXT, submit_requested_at TEXT, settled_at TEXT, settlement_delivery_id TEXT,
+      action_delivery_id TEXT, submit_note_delivery_id TEXT, projected_at TEXT, projection_error TEXT,
+      companion_retired_at TEXT, updated_at TEXT NOT NULL,
+      CHECK ((state = 'settled') = (outcome IS NOT NULL)),
+      CHECK ((state = 'settled') = (result_json IS NOT NULL)),
+      CHECK (kind <> 'page' OR presentation_dir IS NOT NULL)
+    );
+    CREATE INDEX idx_human_requests_inbox ON human_requests(state, inbox_listed);
+    CREATE INDEX idx_human_requests_kind_state ON human_requests(kind, state);
+    CREATE INDEX idx_human_requests_submit ON human_requests(state, submit_requested_at);
+    CREATE INDEX idx_human_requests_file ON human_requests(file);
+    CREATE INDEX idx_human_requests_requester ON human_requests(requester_node_id);
+  `);
+    const insert = cachedStatement(db, `INSERT INTO human_requests (
+    request_id, kind, inbox_ticket_id, request_dir, presentation_dir, requester_node_id, companion_node_id, idempotency_key,
+    state, outcome, inbox_listed, settleable, title, subtitle, file, specification_json, action_json,
+    progress_json, feedback_json, result_json, anchor_base_sha256, anchor_base_bytes, created_at, opened_at,
+    submit_requested_at, settled_at, settlement_delivery_id, action_delivery_id, projected_at, projection_error,
+    companion_retired_at, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    if (cachedStatement(db, "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'reviews'").get() !== undefined) {
+        const rows = cachedStatement(db, 'SELECT * FROM reviews').all();
+        for (const row of rows) {
+            const legacyState = row['state'];
+            const settled = legacyState === 'approved' || legacyState === 'canceled';
+            const result = legacyState === 'canceled' && row['result_json'] === null
+                ? JSON.stringify({ schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: row['canceled_at'], ...(row['cancel_reason'] === '' || row['cancel_reason'] === null ? {} : { reason: row['cancel_reason'] }), ...(row['cancel_actor'] === null ? {} : { actor: row['cancel_actor'] }) })
+                : row['result_json'];
+            if (settled && result === null)
+                throw new Error(`corrupt required input: reviews/${row['review_id']} has no terminal result`);
+            const requestDirectory = row['bridge_node_id'] === null ? join(crtrHome(), 'reviews', row['review_id']) : join(nodesRoot(), row['bridge_node_id']);
+            const spec = {
+                origin_kind: row['origin_kind'], bridge_node_id: row['bridge_node_id'],
+                origin_session_file: row['origin_session_file'], origin_session_id: row['origin_session_id'], origin_leaf_id: row['origin_leaf_id'],
+                model_spec: row['model_spec'], branch_file: row['branch_file'], baseline_sha256: row['baseline_sha256'], baseline_bytes: row['baseline_bytes'],
+                captured_at: row['captured_at'], output_path: row['output_path'],
+            };
+            const outcome = settled ? (legacyState === 'approved' ? 'approved' : 'canceled') : null;
+            const settledAt = settled ? (legacyState === 'approved' ? row['approved_at'] : row['canceled_at']) : null;
+            const settlementDeliveryId = terminalDeliveryMark(db, {
+                requestId: row['review_id'], requesterNodeId: row['origin_node_id'], kind: 'review', outcome, resultJson: result,
+                settledAt, requestDir: requestDirectory, deliveredAt: row['delivered_at'],
+            });
+            const companionRetiredAt = companionRetirementProven(db, row['companion_node_id'], outcome) ? settledAt : null;
+            insert.run(row['review_id'], 'review', row['origin_kind'] === 'ticket' ? legacyTicketId(nodesRoot(), basename(requestDirectory)) : randomTicketId(), requestDirectory, null, row['origin_node_id'], row['companion_node_id'], row['idempotency_key'], settled ? 'settled' : legacyState, outcome, row['origin_kind'] === 'ticket' ? 1 : 0, 1, basename(row['file']), row['subtitle'], row['file'], JSON.stringify(spec), null, null, null, result, row['anchor_base_sha256'], row['anchor_base_bytes'], row['created'], row['opened_at'], row['submit_requested_at'], settledAt, settlementDeliveryId, null, row['projected_at'], row['projection_error'], companionRetiredAt, row['created']);
+        }
+        db.exec('DROP TABLE reviews');
+    }
+    for (const entry of existsSync(nodesRoot()) ? readdirSync(nodesRoot(), { withFileTypes: true }) : []) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = join(nodesRoot(), entry.name);
+        const manifestPath = join(dir, 'page.json');
+        const reviewPath = join(dir, 'review.json');
+        if (!existsSync(manifestPath)) {
+            if (existsSync(reviewPath))
+                continue;
+            continue;
+        }
+        if (cachedStatement(db, 'SELECT 1 FROM human_requests WHERE request_id = ?').get(entry.name) !== undefined)
+            continue;
+        let manifest;
+        let prepared;
+        let canonicalManifest;
+        let delivery;
+        try {
+            const rawManifest = readJson(manifestPath);
+            if (typeof rawManifest !== 'object' || rawManifest === null || Array.isArray(rawManifest))
+                throw new Error('page manifest must be an object');
+            manifest = rawManifest;
+            if (manifest['schema'] === 'crtr.page/v1') {
+                prepared = migrateLegacyPage(dir, rawManifest);
+                manifest = prepared.manifest;
+            }
+            else if (manifest['schema'] === 'crtr.page/v2') {
+                manifest = withoutLegacyTextEditable(manifest);
+            }
+            const parsedDelivery = pageDeliverySchema.safeParse(manifest['delivery']);
+            if (typeof manifest['title'] !== 'string' || !parsedDelivery.success)
+                throw new Error(parsedDelivery.success ? 'page title must be a string' : parsedDelivery.error.message);
+            delivery = parsedDelivery.data;
+            canonicalManifest = validatePageManifest(manifest);
+        }
+        catch (error) {
+            const message = error instanceof Error && error.cause instanceof Error ? error.cause.message : error instanceof Error ? error.message : String(error);
+            console.warn(`skipping legacy page ${manifestPath}: ${message}`);
+            continue;
+        }
+        let retainedPresentationDirectory = realpathSync(dir);
+        if (prepared !== undefined)
+            retainedPresentationDirectory = publishPageRevision(requestDir(entry.name), prepared);
+        const source = canonicalManifest.source;
+        const resultPath = join(dir, 'response.json');
+        const result = existsSync(resultPath) ? readJson(resultPath) : null;
+        const terminal = result === null ? null : legacyPageResult(result);
+        const actionDelivery = cachedStatement(db, "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'deliveries'").get() === undefined
+            ? null
+            : cachedStatement(db, "SELECT delivery_id FROM deliveries WHERE idempotency_key = ?").get(`human-action:${legacyTicketId(nodesRoot(), entry.name)}`);
+        const actionPath = join(dir, 'action.json');
+        const progressPath = join(dir, 'progress.json');
+        const feedbackPath = join(dir, 'feedback-comments.json');
+        const replyRoutePath = join(dir, 'reply-route.json');
+        const feedback = existsSync(feedbackPath) ? readJson(feedbackPath) : null;
+        if (feedback !== null && (typeof feedback !== 'object' || typeof feedback['companionNodeId'] !== 'undefined' && typeof feedback['companionNodeId'] !== 'string')) {
+            throw new Error(`corrupt required input: ${feedbackPath}`);
+        }
+        const replyRoute = existsSync(replyRoutePath) ? readJson(replyRoutePath) : null;
+        if (replyRoute !== null && (typeof replyRoute !== 'object' || typeof replyRoute['bridge_node_id'] !== 'string')) {
+            throw new Error(`corrupt required input: ${replyRoutePath}`);
+        }
+        const bridgeNodeId = replyRoute?.['bridge_node_id'];
+        const bridgeRequester = typeof bridgeNodeId !== 'string' || cachedStatement(db, "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'nodes'").get() === undefined
+            ? null
+            : cachedStatement(db, 'SELECT parent FROM nodes WHERE node_id = ?').get(bridgeNodeId);
+        const requesterNodeId = bridgeRequester?.parent ?? (typeof source?.['nodeId'] === 'string' ? source['nodeId'] : null);
+        const companionNodeId = feedback?.['companionNodeId'];
+        const createdAt = typeof source?.['emittedAt'] === 'string' ? source['emittedAt'] : statSync(manifestPath).mtime.toISOString();
+        const resultJson = result === null ? null : JSON.stringify(result);
+        const settlementDeliveryId = terminalDeliveryMark(db, {
+            requestId: entry.name, requesterNodeId, kind: 'page', outcome: terminal?.outcome ?? null, resultJson,
+            settledAt: terminal?.settledAt ?? null, requestDir: dir,
+        });
+        const companionRetiredAt = companionRetirementProven(db, companionNodeId ?? null, terminal?.outcome ?? null) ? terminal?.settledAt ?? null : null;
+        const stableRequestDirectory = requestDir(entry.name);
+        mkdirSync(stableRequestDirectory, { recursive: true, mode: 0o700 });
+        insert.run(entry.name, 'page', legacyTicketId(nodesRoot(), entry.name), stableRequestDirectory, retainedPresentationDirectory, requesterNodeId, companionNodeId ?? null, null, terminal === null ? 'open' : 'settled', terminal?.outcome ?? null, delivery.inbox ? 1 : 0, delivery.inbox || delivery.reply ? 1 : 0, canonicalManifest.title, canonicalManifest.subtitle ?? null, null, JSON.stringify(canonicalManifest), existsSync(actionPath) ? JSON.stringify(readJson(actionPath)) : null, existsSync(progressPath) && terminal === null ? JSON.stringify(readJson(progressPath)) : null, feedback === null ? null : JSON.stringify(feedback), resultJson, null, null, createdAt, null, null, terminal?.settledAt ?? null, settlementDeliveryId, actionDelivery?.delivery_id ?? null, null, null, companionRetiredAt, createdAt);
+    }
+    const invalid = cachedStatement(db, "SELECT request_id FROM human_requests WHERE state = 'settled' AND result_json IS NULL").get();
+    if (invalid !== undefined)
+        throw new Error(`human request migration produced terminal row without result: ${invalid.request_id}`);
+    if (cachedStatement(db, "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'review_comments'").get() !== undefined) {
+        const orphan = cachedStatement(db, "SELECT review_id FROM review_comments WHERE review_id NOT IN (SELECT request_id FROM human_requests WHERE kind = 'review') LIMIT 1").get();
+        if (orphan !== undefined)
+            throw new Error(`review comment has no migrated review request: ${orphan.review_id}`);
+    }
+}

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

@@ -0,0 +1,4 @@
+export declare function inboxActivityPath(): string;
+/** Signal one durable ticket mutation to every open inbox without watching every ticket directory. */
+export declare function signalInboxActivity(): void;
+export declare function watchInboxActivity(onChange: () => void): () => void;

package/dist/core/human/root.js

@@ -0,0 +1,11 @@
+import { activityPath, signalActivity, watchActivity } from '../activity-signal.js';
+export function inboxActivityPath() {
+    return activityPath('inbox-activity');
+}
+/** Signal one durable ticket mutation to every open inbox without watching every ticket directory. */
+export function signalInboxActivity() {
+    signalActivity('inbox-activity');
+}
+export function watchInboxActivity(onChange) {
+    return watchActivity('inbox-activity', onChange);
+}

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

@@ -0,0 +1,3 @@
+import type { PageManifest, PageResponses } from './page-schema.js';
+/** The stable one-line digest stored in the terminal request result. */
+export declare function buildPageSummary(manifest: PageManifest, responses: PageResponses): string;

package/dist/core/human/summary.js

@@ -0,0 +1,5 @@
+import { describePageAnswer } from './answer.js';
+/** The stable one-line digest stored in the terminal request result. */
+export function buildPageSummary(manifest, responses) {
+    return describePageAnswer(manifest, responses, { completedAt: '' }).digest;
+}