@north-light/cli 0.0.0 → 0.3.413

package/dist/core/human/page-synth.js

@@ -0,0 +1,11 @@
+var a=Object.defineProperty;var n=(e,t)=>a(e,"name",{value:t,configurable:!0});import{join as o}from"node:path";import{mkdtempSync as u,writeFileSync as m}from"node:fs";import{tmpdir as f}from"node:os";function i(e){return`{${JSON.stringify(e)}}`}n(i,"jsxText");function d(e){return e===""?"":`      <p className="whitespace-pre-wrap">${e.replace(/\r\n/g,`
+`).split(`
+`).map(i).join("<br />")}</p>
+`}n(d,"bodyJsx");function h(e,t,r,s){const p=s?`      <UserText id="response" initialText="" />
+`:"",c=t===""?"":` subtitle=${i(t)}`;return`export default function SynthesizedPage() {
+  return (
+    <Page title=${i(e)}${c}>
+${d(r)}${p}    </Page>
+  );
+}
+`}n(h,"synthesizedPageDocument");function y(e){const t=u(o(f(),"crtr-human-page-")),r=o(t,"page.tsx");return m(r,e,{encoding:"utf8",mode:384}),{dir:t,path:r}}n(y,"writeSynthesizedPage");export{h as synthesizedPageDocument,y as writeSynthesizedPage};

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

@@ -0,0 +1,16 @@
+import type { ProductPageComponents } from '../../types.js';
+import { type PageDelivery, type PageManifest, type PageSource } from './page-schema.js';
+import { PageAuthoringError } from './page-errors.js';
+export { PageAuthoringError };
+/** Compile one authored TSX page to the CommonJS module the Gateway evaluates.
+ *  Registry names stay free identifiers; the Gateway supplies them at eval. */
+export declare function compilePage(document: string): string;
+/** Derive the transport manifest from one authored TSX page document. */
+export declare function derivePageManifestFromDocument(document: string, productComponents?: ProductPageComponents, source?: PageSource, delivery?: PageDelivery): PageManifest;
+export declare function deriveHtmlPageManifest(document: string, source?: PageSource, delivery?: PageDelivery): PageManifest;
+/** Derive the transport manifest from one authored TSX page source file. */
+export declare function derivePageManifest(sourceFile: string, productComponents?: ProductPageComponents, source?: PageSource, delivery?: PageDelivery): PageManifest;
+/** Read and validate page.json from a ticket directory. */
+export declare function parsePage(dir: string): PageManifest;
+/** Read only the stable delivery envelope without interpreting component config. */
+export declare function parsePageDelivery(dir: string): PageDelivery;

package/dist/core/human/page.js

@@ -0,0 +1 @@
+var q=Object.defineProperty;var i=(t,e)=>q(t,"name",{value:e,configurable:!0});import{readFileSync as v}from"node:fs";import{createRequire as C}from"node:module";import{join as D}from"node:path";import{BUILTIN_KIND_BY_TAG as O,BUILTIN_PAGE_COMPONENT_TAGS as M,DISPLAY_PAGE_COMPONENT_TAGS as L,pageComponentTag as E}from"./page-catalog.js";import{isResponseBearingSlot as R,pageDeliverySchema as F,validateAuthoredPageManifest as B,validatePageManifest as G}from"./page-schema.js";import{evaluatePageTree as J,jsonProps as K}from"./page-eval.js";import{PageAuthoringError as o}from"./page-errors.js";const T=C(import.meta.url);let U,X;function H(){return U??=T("esbuild")}i(H,"esbuild");function $(){return X??=T("typescript")}i($,"typescript");function k(t){return t instanceof o?t:new o(t instanceof Error?t.message:String(t))}i(k,"asPageAuthoringError");function A(t,e){try{const n=B(t,e),r=n.slots.filter(R);if(r.length>=2)for(const s of r){const c=s.config.label;if(typeof c!="string"||c==="")throw new o(`response-bearing slot "${s.id}" requires a nonempty config.label when the page has multiple response-bearing slots`)}return n}catch(n){throw k(n)}}i(A,"validateAuthoredManifest");const Y="a page is evaluated with React and every registry component already in scope, so it takes no imports \u2014 write `<Page>`, `<UserQuestion>`, `<Card>` and friends directly.";function z(t){try{return H().transformSync(t,{loader:"tsx",format:"cjs",jsx:"transform",jsxFactory:"React.createElement",jsxFragment:"React.Fragment",target:"es2020",sourcefile:"page.tsx"}).code}catch(e){const r=e.errors?.[0];if(r===void 0)throw k(e);const s=r.location==null?"":` (page.tsx:${r.location.line}:${r.location.column})`;throw new o(`page does not compile: ${r.text??"unknown error"}${s}`)}}i(z,"compilePage");function Q(t){const e=$();return e.createSourceFile("page.tsx",t,e.ScriptTarget.ES2022,!0,e.ScriptKind.TSX)}i(Q,"parseTsx");function j(t,e){e(t),t.forEachChild(n=>j(n,e))}i(j,"eachNode");function V(t){const e=$();let n;if(j(t,r=>{n===void 0&&(e.isImportDeclaration(r)||e.isImportEqualsDeclaration(r)?n="import":e.isExportDeclaration(r)&&r.moduleSpecifier!==void 0?n="export \u2026 from":e.isCallExpression(r)&&(r.expression.kind===e.SyntaxKind.ImportKeyword?n="dynamic import()":e.isIdentifier(r.expression)&&r.expression.text==="require"&&(n="require()")))}),n!==void 0)throw new o(`page source uses ${n}: ${Y}`)}i(V,"rejectModulePlumbing");function I(t,e){const n=t[e];if(n!==void 0){if(typeof n!="string")throw new o(`<Page> prop ${e} must be a string; it is part of the page manifest`);return n}}i(I,"stringProp");function W(t,e,n){V(Q(t));const r=[...M,...L,...n.map(l=>E(l.kind))],s=J(e,r),c=[],h=i(l=>{for(const a of l)a.kind!=="text"&&(a.tag==="Page"&&c.push(a),h(a.children))},"collectPages");if(h(s),c.length===0)throw new o('page default export must render exactly one <Page title="\u2026"> root; it rendered none');if(c.length>1)throw new o(`page default export renders ${c.length} <Page> elements; exactly one is allowed`);const d=c[0],w=(I(d.props,"title")??"").trim();if(w==="")throw new o("<Page> requires a nonempty title prop");const g=I(d.props,"subtitle")?.trim();if(d.props.placement!==void 0)throw new o("<Page> placement is not authored; choose --placement inline or --placement panel when sending the page.");const f=new Map;for(const l of n){const a=E(l.kind);if(M.has(a))throw new o(`product page component kind "${l.kind}" derives JSX tag "${a}", which collides with a built-in page component`);if(f.has(a))throw new o(`product page component kind "${l.kind}" derives JSX tag "${a}", which duplicates product page component kind "${f.get(a)}"`);f.set(a,l.kind)}const x=[];let y=0;const P=i((l,a)=>{for(const p of l){if(p.kind==="text")continue;const S=p.tag==="Step"?y++:a,m=O[p.tag],b=f.get(p.tag);if(m!==void 0||b!==void 0){const{id:u,..._}=K(p.props);if(u!==void 0&&typeof u!="string")throw new o(`<${p.tag}> id prop must be a string`);x.push({...u===void 0?{}:{id:u},kind:m??b,step:S,config:_,...m===void 0?{unvalidated:!0}:{}})}P(p.children,S)}},"collectSlots");return P(d.children,0),{title:w,...g===void 0||g===""?{}:{subtitle:g},steps:Math.max(y,1),slots:x}}i(W,"scanPage");function Z(t,e=[],n,r={placement:"inline",inbox:!1,reply:!1}){const s=W(t,z(t),e);return A({schema:"crtr.page/v2",dialect:"jsx",title:s.title,...s.subtitle===void 0?{}:{subtitle:s.subtitle},delivery:r,document:"page.tsx",steps:s.steps,slots:s.slots,...n===void 0?{}:{source:n}},e)}i(Z,"derivePageManifestFromDocument");function ee(t){const e=/<title\b[^>]*>([\s\S]*?)<\/title\s*>/i.exec(t)?.[1]?.replace(/<[^>]+>/g,"").trim();if(e===void 0||e==="")throw new o("HTML page requires a nonempty <title>.");const n=[...t.matchAll(/<meta\b[^>]*>/gi)].map(r=>r[0]).map(r=>{const s=new Map([...r.matchAll(/\b([^\s=/>]+)\s*=\s*(["'])([\s\S]*?)\2/g)].map(c=>[c[1].toLowerCase(),c[3]]));return s.get("name")?.toLowerCase()==="description"?s.get("content")?.trim():void 0}).find(r=>r!==void 0);return{title:e,...n===void 0||n===""?{}:{subtitle:n}}}i(ee,"htmlMetadata");function le(t,e,n={placement:"inline",inbox:!1,reply:!1}){const r=ee(t);return A({schema:"crtr.page/v2",dialect:"html",...r,delivery:n,document:"page.html",steps:1,slots:[],...e===void 0?{}:{source:e}},[])}i(le,"deriveHtmlPageManifest");function pe(t,e=[],n,r){return Z(v(t,"utf8"),e,n,r)}i(pe,"derivePageManifest");function N(t){try{return JSON.parse(v(D(t,"page.json"),"utf8"))}catch{throw new o("page.json is not valid JSON")}}i(N,"readPageJson");function de(t){return G(N(t))}i(de,"parsePage");function fe(t){const e=N(t),n=F.safeParse(typeof e=="object"&&e!==null&&!Array.isArray(e)?e.delivery:void 0);if(!n.success)throw new o("page.json has an invalid delivery envelope");return n.data}i(fe,"parsePageDelivery");export{o as PageAuthoringError,z as compilePage,le as deriveHtmlPageManifest,pe as derivePageManifest,Z as derivePageManifestFromDocument,de as parsePage,fe as parsePageDelivery};

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

@@ -0,0 +1,146 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type PreparedPage } from './page-authoring.js';
+import { type PageResponses } from './page-schema.js';
+export type HumanRequestKind = 'page' | 'review';
+export type HumanRequestState = 'binding' | 'open' | 'settled';
+export type HumanRequestOutcome = 'approved' | 'answered' | 'canceled' | 'dismissed';
+export interface HumanRequestRecord {
+    request_id: string;
+    kind: HumanRequestKind;
+    inbox_ticket_id: string;
+    request_dir: string;
+    /** The immutable complete page revision selected by SQL. Null for reviews. */
+    presentation_dir: string | null;
+    requester_node_id: string | null;
+    companion_node_id: string | null;
+    idempotency_key: string | null;
+    state: HumanRequestState;
+    outcome: HumanRequestOutcome | null;
+    inbox_listed: boolean;
+    settleable: boolean;
+    title: string;
+    subtitle: string | null;
+    file: string | null;
+    specification_json: string;
+    action_json: string | null;
+    progress_json: string | null;
+    feedback_json: string | null;
+    result_json: string | null;
+    anchor_base_sha256: string | null;
+    anchor_base_bytes: Buffer | null;
+    created_at: string;
+    opened_at: string | null;
+    submit_requested_at: string | null;
+    settled_at: string | null;
+    settlement_delivery_id: string | null;
+    action_delivery_id: string | null;
+    submit_note_delivery_id: string | null;
+    projected_at: string | null;
+    projection_error: string | null;
+    companion_retired_at: string | null;
+    updated_at: string;
+}
+export interface NewReviewRequest {
+    request_id: string;
+    idempotency_key: string;
+    requester_node_id: string;
+    companion_node_id: string;
+    request_dir: string;
+    file: string;
+    specification: Record<string, unknown>;
+    anchor_base_sha256: string;
+    anchor_base_bytes: Buffer;
+    created_at: string;
+    subtitle?: string | null;
+    /** The inbox title; defaults to the file's basename. */
+    title?: string;
+    inbox_listed: boolean;
+}
+export interface CreatePageRequestInput {
+    /** Frozen by a cron obligation when creation must be idempotent across a daemon death. */
+    request_id?: string;
+    inbox_ticket_id?: string;
+    prepared: PreparedPage;
+    requester_node_id?: string | null;
+    action_json?: string | null;
+}
+export interface SettleRequestArgs {
+    request_id: string;
+    outcome: HumanRequestOutcome;
+    result_json: string;
+    settled_at: string;
+}
+export interface RequestSettlementMarks {
+    settlement_delivery_id?: string | null;
+    action_delivery_id?: string | null;
+}
+export declare function humanRequestsRoot(): string;
+export declare function requestDir(requestId: string): string;
+export interface PageRevisionStorage {
+    writeFile(path: string, content: string): void;
+    syncFile(path: string): void;
+    syncDirectory(path: string): void;
+}
+/** Publish a complete, immutable revision before a request can select it. */
+export declare function publishPageRevision(dir: string, prepared: PreparedPage, storage?: PageRevisionStorage): string;
+/** The SQL-selected page revision. There is no path-based fallback for page reads. */
+export declare function presentationDir(request: HumanRequestRecord): string;
+/** Creates one SQL-authoritative page request. `request_id` is optional for ordinary callers and frozen by cron creation. */
+export declare function createPageRequest(input: CreatePageRequestInput): HumanRequestRecord;
+/** Claims a review idempotency key before companion realization. */
+export declare function commitBindingRequest(input: NewReviewRequest): {
+    request_id: string;
+    won: boolean;
+};
+export declare function getRequest(requestId: string): HumanRequestRecord | null;
+export declare function getRequestByInboxTicket(ticketId: string): HumanRequestRecord | null;
+export declare function getRequestByDirectory(dir: string): HumanRequestRecord | null;
+export declare function getRequestByCompanion(nodeId: string): HumanRequestRecord | null;
+export declare function getRequestByIdempotencyKey(key: string): HumanRequestRecord | null;
+/** 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 declare const NOT_OTHER_APP_QUESTION = "NOT (kind = 'page' AND EXISTS (SELECT 1 FROM node_rows n WHERE n.node_id = human_requests.requester_node_id\n  AND n.run_id IS NOT NULL AND n.grantee IS NOT NULL AND n.grantee <> 'app:terminal'))";
+export declare function listOpenInboxRequests(): HumanRequestRecord[];
+export declare function openRequestsByRequester(nodeId: string): HumanRequestRecord[];
+export declare function hasOpenReplyBearingRequestByRequester(nodeId: string): boolean;
+/** Indexed attention projection: only open inbox-listed requests with a reply target keep a node wakeable. */
+export declare function listOpenReplyBearingRequests(): HumanRequestRecord[];
+export declare function listBindingRequests(): HumanRequestRecord[];
+export declare function listSubmitRequestedRequests(): HumanRequestRecord[];
+export declare function listUnprojectedReviews(): HumanRequestRecord[];
+export declare function listRequests(filter?: {
+    kind?: HumanRequestKind;
+    state?: HumanRequestState;
+    requester_node_id?: string;
+    file?: string;
+    page_source_node_id?: string;
+}): HumanRequestRecord[];
+/** An indexed preflight preserves the old map-before-filter error for corrupt page JSON. */
+export declare function hasPageResultException(): boolean;
+export declare function firstInvalidPageSpecification(): Pick<HumanRequestRecord, 'request_id' | 'specification_json'> | null;
+export declare function openRequest(requestId: string, openedAt: string): boolean;
+/** A binding whose immutable branch disappeared never recaptures a new origin. */
+export declare function cancelBindingRequest(requestId: string, at: string, reason: string): boolean;
+export declare function requestSubmit(requestId: string, at: string): boolean;
+/** The first-writer-wins terminal transition. Callers add obligations in this same `withCanvasWrite` boundary. */
+export declare function settleRequestLocked(db: DatabaseSync, args: SettleRequestArgs): HumanRequestRecord | null;
+export declare function setSettlementDeliveryMarksLocked(db: DatabaseSync, requestId: string, marks: RequestSettlementMarks): void;
+export declare function setSubmitNoteDeliveryLocked(db: DatabaseSync, requestId: string, deliveryId: string): boolean;
+export declare function revisePageRequest(requestId: string, values: {
+    presentation_dir: string;
+    specification_json: string;
+    title: string;
+    subtitle: string | null;
+    inbox_listed: boolean;
+    settleable: boolean;
+}): boolean;
+export declare function writeProgress(ticketId: string, responses: PageResponses): boolean;
+export declare function markProjected(requestId: string, at: string): void;
+export declare function markProjectionError(requestId: string, error: string): void;
+export declare function markCompanionRetired(requestId: string, at: string): void;
+export declare function readAnchorBase(requestId: string): {
+    bytes: Buffer;
+    sha256: string;
+} | null;
+export declare function replaceAnchorBaseLocked(db: DatabaseSync, requestId: string, bytes: Buffer, sha256: string): void;
+export declare function migrateHumanRequestsState(db: DatabaseSync): void;

package/dist/core/human/requests.js

@@ -0,0 +1,82 @@
+var ue=Object.defineProperty;var i=(e,t)=>ue(e,"name",{value:t,configurable:!0});import{prepared as o}from"../sqlite-statements.js";import{createHash as ce,randomBytes as w}from"node:crypto";import{existsSync as y,mkdirSync as D,readFileSync as V,readdirSync as le,realpathSync as L,statSync as _e,writeFileSync as me}from"node:fs";import{basename as C,join as l}from"node:path";import{z as u}from"zod";import{crtrHome as Q,isSafeNodeId as pe,nodesRoot as b}from"../canvas/paths.js";import{openDb as _,withCanvasWrite as E}from"../canvas/db.js";import{syncDirectory as fe,syncFile as Ee}from"../fs-utils.js";import{newNodeId as ge}from"../runtime/nodes.js";import{pageManifestPath as ye,pageModulePath as Ne,pagePath as he}from"./convention.js";import{preparePageSource as qe}from"./page-authoring.js";import{pageDeliverySchema as Te,validatePageManifest as z}from"./page-schema.js";import{appendWaitingOnUser as be}from"../runs/questions.js";function G(e){return e===1||e===!0}i(G,"bool");function Z(e){return{request_id:e.request_id,kind:e.kind,inbox_ticket_id:e.inbox_ticket_id,request_dir:e.request_dir,presentation_dir:e.presentation_dir,requester_node_id:e.requester_node_id,companion_node_id:e.companion_node_id,idempotency_key:e.idempotency_key,state:e.state,outcome:e.outcome,inbox_listed:G(e.inbox_listed),settleable:G(e.settleable),title:e.title,subtitle:e.subtitle,file:e.file,specification_json:e.specification_json,action_json:e.action_json,progress_json:e.progress_json,feedback_json:e.feedback_json,result_json:e.result_json,anchor_base_sha256:e.anchor_base_sha256,anchor_base_bytes:e.anchor_base_bytes===null?null:Buffer.from(e.anchor_base_bytes),created_at:e.created_at,opened_at:e.opened_at,submit_requested_at:e.submit_requested_at,settled_at:e.settled_at,settlement_delivery_id:e.settlement_delivery_id,action_delivery_id:e.action_delivery_id,submit_note_delivery_id:e.submit_note_delivery_id,projected_at:e.projected_at,projection_error:e.projection_error,companion_retired_at:e.companion_retired_at,updated_at:e.updated_at}}i(Z,"recordFromRow");function q(e,t,...r){const s=e.prepare(`SELECT * FROM human_requests WHERE ${t}`).get(...r);return s===void 0?null:Z(s)}i(q,"one");function S(e,t,r=[],s="created_at ASC, request_id ASC"){return e.prepare(`SELECT * FROM human_requests WHERE ${t} ORDER BY ${s}`).all(...r).map(Z)}i(S,"many");function ee(){return l(Q(),"requests")}i(ee,"humanRequestsRoot");function P(e){if(!pe(e))throw new TypeError(`request_id must be a safe path segment: ${e}`);const t=ee();return D(t,{recursive:!0,mode:448}),l(L(t),e)}i(P,"requestDir");function U(){return w(32).toString("hex")}i(U,"randomTicketId");function H(e,t){return ce("sha256").update(`${L(e)}\0${t}`,"utf8").digest("hex")}i(H,"legacyTicketId");const Se={writeFile(e,t){me(e,t,{flag:"wx",mode:384})},syncFile:Ee,syncDirectory:fe};function ve(e){return l(e,"revisions")}i(ve,"revisionRoot");function te(e,t,r=Se){D(e,{recursive:!0,mode:448});const s=ve(e);D(s,{recursive:!0,mode:448});const n=l(s,w(16).toString("hex"));D(n,{mode:448});const a=he(n,t.manifest.dialect);if(r.writeFile(a,t.document),r.syncFile(a),t.manifest.dialect==="jsx"){const d=Ne(n);r.writeFile(d,t.module),r.syncFile(d)}const c=ye(n);return r.writeFile(c,`${JSON.stringify(t.manifest,null,2)}
+`),r.syncFile(c),r.syncDirectory(n),r.syncDirectory(s),r.syncDirectory(e),r.syncDirectory(ee()),n}i(te,"publishPageRevision");function et(e){if(e.kind!=="page"||e.presentation_dir===null)throw new Error(`page request has no selected presentation: ${e.request_id}`);return e.presentation_dir}i(et,"presentationDir");function tt(e){const t=e.request_id??ge(),r=P(t),s=te(r,e.prepared),n=new Date().toISOString(),a=e.prepared.manifest;return E(c=>{o(c,`
+      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(t,e.inbox_ticket_id??U(),r,s,e.requester_node_id??null,a.delivery.inbox?1:0,a.delivery.inbox||a.delivery.reply?1:0,a.title,a.subtitle??null,JSON.stringify(a),e.action_json??null,n,n);const d=q(c,"request_id = ?",t);if(d===null)throw new Error(`page request insert did not produce a row: ${t}`);return be(c,d),d})}i(tt,"createPageRequest");function nt(e){return E(t=>{const r=o(t,`
+      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(e.request_id,U(),e.request_dir,e.requester_node_id,e.companion_node_id,e.idempotency_key,e.inbox_listed?1:0,e.title??C(e.file),e.subtitle??null,e.file,JSON.stringify(e.specification),e.anchor_base_sha256,e.anchor_base_bytes,e.created_at,e.created_at),s=q(t,"idempotency_key = ?",e.idempotency_key);if(s===null)throw new Error(`review binding insert did not produce a row: ${e.idempotency_key}`);return{request_id:s.request_id,won:r.changes>0}})}i(nt,"commitBindingRequest");function rt(e){return q(_(),"request_id = ?",e)}i(rt,"getRequest");function it(e){return q(_(),"inbox_ticket_id = ?",e)}i(it,"getRequestByInboxTicket");function st(e){let t=e;try{t=L(e)}catch{}return q(_(),"request_dir = ?",t)}i(st,"getRequestByDirectory");function ot(e){return q(_(),"companion_node_id = ? AND state <> 'binding'",e)}i(ot,"getRequestByCompanion");function at(e){return q(_(),"idempotency_key = ?",e)}i(at,"getRequestByIdempotencyKey");const Re=`NOT (kind = 'page' AND EXISTS (SELECT 1 FROM node_rows n WHERE n.node_id = human_requests.requester_node_id
+  AND n.run_id IS NOT NULL AND n.grantee IS NOT NULL AND n.grantee <> 'app:terminal'))`;function dt(){return S(_(),`state = 'open' AND inbox_listed = 1 AND ${Re}`,[],"created_at DESC, request_id DESC")}i(dt,"listOpenInboxRequests");function Ae(e){return S(_(),"state = 'open' AND requester_node_id = ?",[e],"created_at DESC, request_id DESC")}i(Ae,"openRequestsByRequester");function ut(e){return Ae(e).some(t=>t.kind==="review"?!0:JSON.parse(t.specification_json).delivery?.reply===!0)}i(ut,"hasOpenReplyBearingRequestByRequester");function ct(){return S(_(),"state = 'open' AND inbox_listed = 1 AND requester_node_id IS NOT NULL",[],"created_at DESC, request_id DESC")}i(ct,"listOpenReplyBearingRequests");function lt(){return S(_(),"kind = 'review' AND state = 'binding'")}i(lt,"listBindingRequests");function _t(){return S(_(),"kind = 'review' AND state = 'open' AND submit_requested_at IS NOT NULL")}i(_t,"listSubmitRequestedRequests");function mt(){return S(_(),"kind = 'review' AND state = 'settled' AND projected_at IS NULL")}i(mt,"listUnprojectedReviews");function pt(e={}){const t=["1"],r=[];for(const[s,n]of Object.entries(e))n!==void 0&&(t.push(s==="page_source_node_id"?"CASE WHEN json_valid(specification_json) THEN json_extract(specification_json, '$.source.nodeId') END = ?":`${s} = ?`),r.push(n));return S(_(),t.join(" AND "),r)}i(pt,"listRequests");function ft(){return o(_(),`
+    SELECT 1 FROM human_requests INDEXED BY idx_human_requests_page_result_exception
+    WHERE kind = 'page' AND result_json IS NOT NULL AND
+      CASE WHEN json_valid(result_json) THEN
+        json_extract(result_json, '$.kind') = 'page'
+        AND json_type(result_json, '$.summary') IS NOT 'text'
+      ELSE 1 END
+    LIMIT 1
+  `).get()!==void 0}i(ft,"hasPageResultException");function Et(){return o(_(),`
+    SELECT request_id, specification_json FROM human_requests INDEXED BY idx_human_requests_page_invalid_spec
+    WHERE kind = 'page' AND (NOT json_valid(specification_json)
+      OR CASE WHEN json_valid(specification_json) THEN json_type(specification_json) != 'object' END)
+    ORDER BY created_at ASC, request_id ASC LIMIT 1
+  `).get()??null}i(Et,"firstInvalidPageSpecification");function gt(e,t){return E(r=>o(r,"UPDATE human_requests SET state = 'open', opened_at = ?, updated_at = ? WHERE request_id = ? AND state = 'binding'").run(t,t,e).changes>0)}i(gt,"openRequest");function yt(e,t,r){return E(s=>o(s,`
+    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:t,reason:r}),t,t,e).changes>0)}i(yt,"cancelBindingRequest");function Nt(e,t){return E(r=>o(r,"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(t,t,e).changes>0)}i(Nt,"requestSubmit");function ht(e,t){return o(e,`
+    UPDATE human_requests SET state = 'settled', outcome = ?, result_json = ?, settled_at = ?,
+      progress_json = NULL, updated_at = ?
+    WHERE request_id = ? AND state = 'open'
+  `).run(t.outcome,t.result_json,t.settled_at,t.settled_at,t.request_id).changes===0?null:q(e,"request_id = ?",t.request_id)}i(ht,"settleRequestLocked");function qt(e,t,r){o(e,"UPDATE human_requests SET settlement_delivery_id = ?, action_delivery_id = ?, updated_at = ? WHERE request_id = ?").run(r.settlement_delivery_id??null,r.action_delivery_id??null,new Date().toISOString(),t)}i(qt,"setSettlementDeliveryMarksLocked");function Tt(e,t,r){return o(e,"UPDATE human_requests SET submit_note_delivery_id = ?, updated_at = ? WHERE request_id = ? AND state = 'open' AND submit_note_delivery_id IS NULL").run(r,new Date().toISOString(),t).changes>0}i(Tt,"setSubmitNoteDeliveryLocked");function bt(e,t){return E(r=>o(r,`
+    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(t.presentation_dir,t.specification_json,t.title,t.subtitle,t.inbox_listed?1:0,t.settleable?1:0,new Date().toISOString(),e).changes>0)}i(bt,"revisePageRequest");function St(e,t){return E(r=>o(r,`
+    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:t,savedAt:new Date().toISOString()}),new Date().toISOString(),e).changes>0)}i(St,"writeProgress");function vt(e,t){E(r=>o(r,"UPDATE human_requests SET projected_at = ?, projection_error = NULL, updated_at = ? WHERE request_id = ?").run(t,t,e))}i(vt,"markProjected");function Rt(e,t){E(r=>o(r,"UPDATE human_requests SET projection_error = ?, updated_at = ? WHERE request_id = ? AND projected_at IS NULL").run(t,new Date().toISOString(),e))}i(Rt,"markProjectionError");function At(e,t){E(r=>o(r,"UPDATE human_requests SET companion_retired_at = ?, updated_at = ? WHERE request_id = ? AND companion_retired_at IS NULL").run(t,t,e))}i(At,"markCompanionRetired");function Dt(e){const t=o(_(),"SELECT anchor_base_bytes, anchor_base_sha256 FROM human_requests WHERE request_id = ?").get(e);return t===void 0||t.anchor_base_bytes===null||t.anchor_base_sha256===null?null:{bytes:Buffer.from(t.anchor_base_bytes),sha256:t.anchor_base_sha256}}i(Dt,"readAnchorBase");function Ot(e,t,r,s){o(e,"UPDATE human_requests SET anchor_base_bytes = ?, anchor_base_sha256 = ?, updated_at = ? WHERE request_id = ?").run(r,s,new Date().toISOString(),t)}i(Ot,"replaceAnchorBaseLocked");function De(e){if(typeof e!="object"||e===null)throw new Error("result is not an object");const t=e;return t.kind==="canceled"?{outcome:t.disposition==="dismissed"?"dismissed":"canceled",settledAt:String(t.canceledAt)}:{outcome:"answered",settledAt:String(t.completedAt)}}i(De,"legacyPageResult");function A(e){try{return JSON.parse(V(e,"utf8"))}catch(t){throw new Error(`corrupt required input: ${e}`,{cause:t})}}i(A,"readJson");function X(){return w(16).toString("hex")}i(X,"migrationId");function Oe(e){return Number(o(e,"SELECT COALESCE(MAX(seq), 0) AS seq FROM messages").get().seq)+1}i(Oe,"nextMessageSeq");function je(e,t,r,s){return(s==="page"?o(e,`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(r,t):o(e,`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(r,`%"review_id":"${t}"%`))?.delivery_id??null}i(je,"importedTerminalDelivery");function ne(e,t,r){if(t===null||r===null)return!1;const s=o(e,"SELECT status, final_report FROM nodes WHERE node_id = ?").get(t);return s?.status==="canceled"||r==="approved"&&s?.status==="done"&&s.final_report!==null}i(ne,"companionRetirementProven");function re(e){if(typeof e!="object"||e===null)return"no reason was given";const t=e.reason;return typeof t=="string"&&t!==""?t:"no reason was given"}i(re,"migratedCancellationReason");function Ie(e,t){const r=e.outcome==="canceled"||e.outcome==="dismissed";return[e.kind==="review"?r?`Review ${e.requestId} was canceled \u2014 ${re(t)}.`:`Review ${e.requestId} was approved by the user.`:r?`Human request ${e.requestId} was canceled \u2014 ${re(t)}.`:`Human request ${e.requestId} was answered.`,...e.kind==="review"?[`The review result is at ${e.requestDir}/result.json.`]:[],`Result:
+${JSON.stringify(t,null,2)}`].join(`
+
+`)}i(Ie,"migratedTerminalBody");function Le(e,t){const r=X(),s=X(),n=Date.parse(t.settledAt),a=Number.isFinite(n)?n:0,c=t.outcome==="answered"||t.outcome==="approved"?"human-answer":"human-canceled",d=JSON.parse(t.resultJson),m=Ie(t,d);return o(e,`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(r,Oe(e),X(),t.settledAt,m.split(`
+`,1)[0],JSON.stringify({body:m,result:d}),c),o(e,`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(s,r,t.requesterNodeId,a,a),s}i(Le,"createMigratedTerminalDelivery");function ie(e,t){if(t.requesterNodeId===null||t.outcome===null||t.resultJson===null||t.settledAt===null)return null;const r=je(e,t.requestId,t.requesterNodeId,t.kind);return r!==null?r:t.deliveredAt!==null&&t.deliveredAt!==void 0?null:Le(e,{requestId:t.requestId,requesterNodeId:t.requesterNodeId,kind:t.kind,outcome:t.outcome,resultJson:t.resultJson,settledAt:t.settledAt,requestDir:t.requestDir})}i(ie,"terminalDeliveryMark");const xe=u.object({sessionName:u.string().optional(),askedBy:u.string().optional(),blockedSince:u.string().optional(),profileName:u.string().optional(),nodeId:u.string().optional()}).strict(),ke=u.object({id:u.string().regex(/^[A-Za-z0-9_-]{1,64}$/).optional(),kind:u.string().min(1),step:u.number().int().nonnegative(),config:u.record(u.string(),u.unknown()),unvalidated:u.literal(!0).optional(),display:u.literal(!0).optional()}).strict(),we=u.object({schema:u.literal("crtr.page/v1"),dialect:u.enum(["md","html","jsx"]),title:u.string().trim().min(1),subtitle:u.string().optional(),placement:u.enum(["inline","panel"]),document:u.enum(["page.md","page.html","page.tsx"]),steps:u.number().int().positive(),slots:u.array(ke),source:xe.optional()}).strict().superRefine((e,t)=>{const r=e.dialect==="md"?"page.md":e.dialect==="html"?"page.html":"page.tsx";e.document!==r&&t.addIssue({code:"custom",path:["document"],message:"document must agree with dialect"}),e.dialect==="md"&&e.steps!==1&&t.addIssue({code:"custom",path:["steps"],message:"md pages have exactly one step"})});function Ce(e){if(e.source===void 0)return;const{blockedSince:t,...r}=e.source,s={...r,...t!==void 0&&u.string().datetime({offset:!0}).safeParse(t).success?{emittedAt:t}:{}};return Object.keys(s).length===0?void 0:s}i(Ce,"legacyPresentationSource");function Pe(e,t,r){return`export default function LegacyPage() { return <Page title={${JSON.stringify(e)}}${t===void 0?"":` subtitle={${JSON.stringify(t)}}`}><pre>{${JSON.stringify(r)}}</pre></Page>; }
+`}i(Pe,"legacyReplayDocument");function se(e){return Array.isArray(e.slots)?{...e,slots:e.slots.map(t=>{if(typeof t!="object"||t===null||Array.isArray(t))return t;const r=t;if(r.kind!=="text"||typeof r.config!="object"||r.config===null||Array.isArray(r.config))return t;const{editable:s,...n}=r.config;return{...r,config:n}})}:e}i(se,"withoutLegacyTextEditable");function Ue(e,t){const r=l(e,"page.json"),s=we.safeParse(t);if(!s.success)throw new Error(s.error.message);const n=s.data,a=Ce(n),c={placement:n.placement,inbox:!0,reply:n.source?.blockedSince!==void 0};z(se({schema:"crtr.page/v2",dialect:"jsx",title:n.title,...n.subtitle===void 0?{}:{subtitle:n.subtitle},delivery:c,document:"page.tsx",steps:n.steps,slots:n.slots,...a===void 0?{}:{source:a}}));const d=l(e,n.document);if(!y(d))throw new Error(`corrupt required input: ${d}`);const m=V(d,"utf8"),f=qe({dialect:"jsx",document:Pe(n.title,n.subtitle,m),source:a,delivery:c});if(a!==void 0)return f;const{source:g,...N}=f.manifest;return{...f,manifest:N}}i(Ue,"migrateLegacyPage");function jt(e){e.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 t=o(e,`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(o(e,"SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'reviews'").get()!==void 0){const s=o(e,"SELECT * FROM reviews").all();for(const n of s){const a=n.state,c=a==="approved"||a==="canceled",d=a==="canceled"&&n.result_json===null?JSON.stringify({schema:"humanloop.cancel/v1",kind:"canceled",canceledAt:n.canceled_at,...n.cancel_reason===""||n.cancel_reason===null?{}:{reason:n.cancel_reason},...n.cancel_actor===null?{}:{actor:n.cancel_actor}}):n.result_json;if(c&&d===null)throw new Error(`corrupt required input: reviews/${n.review_id} has no terminal result`);const m=n.bridge_node_id===null?l(Q(),"reviews",n.review_id):l(b(),n.bridge_node_id),f={origin_kind:n.origin_kind,bridge_node_id:n.bridge_node_id,origin_session_file:n.origin_session_file,origin_session_id:n.origin_session_id,origin_leaf_id:n.origin_leaf_id,model_spec:n.model_spec,branch_file:n.branch_file,baseline_sha256:n.baseline_sha256,baseline_bytes:n.baseline_bytes,captured_at:n.captured_at,output_path:n.output_path},g=c?a==="approved"?"approved":"canceled":null,N=c?a==="approved"?n.approved_at:n.canceled_at:null,v=ie(e,{requestId:n.review_id,requesterNodeId:n.origin_node_id,kind:"review",outcome:g,resultJson:d,settledAt:N,requestDir:m,deliveredAt:n.delivered_at}),O=ne(e,n.companion_node_id,g)?N:null;t.run(n.review_id,"review",n.origin_kind==="ticket"?H(b(),C(m)):U(),m,null,n.origin_node_id,n.companion_node_id,n.idempotency_key,c?"settled":a,g,n.origin_kind==="ticket"?1:0,1,C(n.file),n.subtitle,n.file,JSON.stringify(f),null,null,null,d,n.anchor_base_sha256,n.anchor_base_bytes,n.created,n.opened_at,n.submit_requested_at,N,v,null,n.projected_at,n.projection_error,O,n.created)}e.exec("DROP TABLE reviews")}for(const s of y(b())?le(b(),{withFileTypes:!0}):[]){if(!s.isDirectory())continue;const n=l(b(),s.name),a=l(n,"page.json"),c=l(n,"review.json");if(!y(a)){if(y(c))continue;continue}if(o(e,"SELECT 1 FROM human_requests WHERE request_id = ?").get(s.name)!==void 0)continue;let d,m,f,g;try{const p=A(a);if(typeof p!="object"||p===null||Array.isArray(p))throw new Error("page manifest must be an object");d=p,d.schema==="crtr.page/v1"?(m=Ue(n,p),d=m.manifest):d.schema==="crtr.page/v2"&&(d=se(d));const R=Te.safeParse(d.delivery);if(typeof d.title!="string"||!R.success)throw new Error(R.success?"page title must be a string":R.error.message);g=R.data,f=z(d)}catch(p){const R=p instanceof Error&&p.cause instanceof Error?p.cause.message:p instanceof Error?p.message:String(p);console.warn(`skipping legacy page ${a}: ${R}`);continue}let N=L(n);m!==void 0&&(N=te(P(s.name),m));const v=f.source,O=l(n,"response.json"),j=y(O)?A(O):null,h=j===null?null:De(j),oe=o(e,"SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'deliveries'").get()===void 0?null:o(e,"SELECT delivery_id FROM deliveries WHERE idempotency_key = ?").get(`human-action:${H(b(),s.name)}`),$=l(n,"action.json"),M=l(n,"progress.json"),x=l(n,"feedback-comments.json"),k=l(n,"reply-route.json"),T=y(x)?A(x):null;if(T!==null&&(typeof T!="object"||typeof T.companionNodeId<"u"&&typeof T.companionNodeId!="string"))throw new Error(`corrupt required input: ${x}`);const I=y(k)?A(k):null;if(I!==null&&(typeof I!="object"||typeof I.bridge_node_id!="string"))throw new Error(`corrupt required input: ${k}`);const W=I?.bridge_node_id,F=(typeof W!="string"||o(e,"SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'nodes'").get()===void 0?null:o(e,"SELECT parent FROM nodes WHERE node_id = ?").get(W))?.parent??(typeof v?.nodeId=="string"?v.nodeId:null),J=T?.companionNodeId,B=typeof v?.emittedAt=="string"?v.emittedAt:_e(a).mtime.toISOString(),K=j===null?null:JSON.stringify(j),ae=ie(e,{requestId:s.name,requesterNodeId:F,kind:"page",outcome:h?.outcome??null,resultJson:K,settledAt:h?.settledAt??null,requestDir:n}),de=ne(e,J??null,h?.outcome??null)?h?.settledAt??null:null,Y=P(s.name);D(Y,{recursive:!0,mode:448}),t.run(s.name,"page",H(b(),s.name),Y,N,F,J??null,null,h===null?"open":"settled",h?.outcome??null,g.inbox?1:0,g.inbox||g.reply?1:0,f.title,f.subtitle??null,null,JSON.stringify(f),y($)?JSON.stringify(A($)):null,y(M)&&h===null?JSON.stringify(A(M)):null,T===null?null:JSON.stringify(T),K,null,null,B,null,null,h?.settledAt??null,ae,oe?.delivery_id??null,null,null,de,B)}const r=o(e,"SELECT request_id FROM human_requests WHERE state = 'settled' AND result_json IS NULL").get();if(r!==void 0)throw new Error(`human request migration produced terminal row without result: ${r.request_id}`);if(o(e,"SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'review_comments'").get()!==void 0){const s=o(e,"SELECT review_id FROM review_comments WHERE review_id NOT IN (SELECT request_id FROM human_requests WHERE kind = 'review') LIMIT 1").get();if(s!==void 0)throw new Error(`review comment has no migrated review request: ${s.review_id}`)}}i(jt,"migrateHumanRequestsState");export{Re as NOT_OTHER_APP_QUESTION,yt as cancelBindingRequest,nt as commitBindingRequest,tt as createPageRequest,Et as firstInvalidPageSpecification,rt as getRequest,ot as getRequestByCompanion,st as getRequestByDirectory,at as getRequestByIdempotencyKey,it as getRequestByInboxTicket,ut as hasOpenReplyBearingRequestByRequester,ft as hasPageResultException,ee as humanRequestsRoot,lt as listBindingRequests,dt as listOpenInboxRequests,ct as listOpenReplyBearingRequests,pt as listRequests,_t as listSubmitRequestedRequests,mt as listUnprojectedReviews,At as markCompanionRetired,vt as markProjected,Rt as markProjectionError,jt as migrateHumanRequestsState,gt as openRequest,Ae as openRequestsByRequester,et as presentationDir,te as publishPageRevision,Dt as readAnchorBase,Ot as replaceAnchorBaseLocked,P as requestDir,Nt as requestSubmit,bt as revisePageRequest,qt as setSettlementDeliveryMarksLocked,Tt as setSubmitNoteDeliveryLocked,ht as settleRequestLocked,St as writeProgress};

package/dist/core/human/review-schema.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { ReviewDescriptor } from './types.js';
+export declare const reviewDescriptorSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"humanloop.review/v1">;
+    file: z.ZodString;
+    output: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodString;
+    source: z.ZodObject<{
+        sessionName: z.ZodOptional<z.ZodString>;
+        askedBy: z.ZodOptional<z.ZodString>;
+        blockedSince: z.ZodOptional<z.ZodString>;
+        profileName: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    blockedSince: z.ZodString;
+}, z.core.$strict>;
+export declare function validateReviewDescriptor(parsed: unknown): ReviewDescriptor;
+/** Canonicalize and authorize the one review projection boundary before every write. */
+export declare function validateReviewProjection(dir: string, parsed: unknown): ReviewDescriptor;

package/dist/core/human/review-schema.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var s=(t,i)=>f(t,"name",{value:i,configurable:!0});import{existsSync as w,realpathSync as l}from"node:fs";import{basename as c,dirname as h,isAbsolute as p,resolve as v}from"node:path";import{claimPath as b,pageManifestPath as g,progressPath as S,responsePath as j,reviewPath as P}from"./convention.js";import{z as e}from"zod";import{checkReviewableFile as d}from"./visible-paths.js";const k=e.object({sessionName:e.string().optional(),askedBy:e.string().optional(),blockedSince:e.string().optional(),profileName:e.string().optional(),nodeId:e.string().optional()}),x=e.object({schema:e.literal("humanloop.review/v1"),file:e.string().min(1).refine(p,"file must be absolute"),output:e.string().min(1).refine(p,"output must be absolute"),title:e.string().trim().min(1),subtitle:e.string().trim().min(1),source:k,blockedSince:e.string().datetime({offset:!0})}).strict();function y(t){return x.parse(t)}s(y,"validateReviewDescriptor");function B(t,i){const o=y(i);if(!w(o.file))throw new Error("review file must be an existing absolute path");const n=d(o.file);if(!n.ok)throw new Error(`review file is not reviewable: ${n.reason}`);const a=l(o.file),r=v(l(h(o.output)),c(o.output)),m=new Set(["page.json","review.json","response.json","progress.json","claim.json"]),u=new Set([g(t),P(t),j(t),S(t),b(t)]);if(r===a||m.has(c(r))||u.has(r))throw new Error("review output must not alias the source or ticket protocol files");return{...o,file:a,output:r}}s(B,"validateReviewProjection");export{x as reviewDescriptorSchema,y as validateReviewDescriptor,B as validateReviewProjection};

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 @@
+var c=Object.defineProperty;var t=(i,n)=>c(i,"name",{value:n,configurable:!0});import{activityPath as o,signalActivity as a,watchActivity as r}from"../activity-signal.js";function y(){return o("inbox-activity")}t(y,"inboxActivityPath");function b(){a("inbox-activity")}t(b,"signalInboxActivity");function e(i){return r("inbox-activity",i)}t(e,"watchInboxActivity");export{y as inboxActivityPath,b as signalInboxActivity,e as watchInboxActivity};

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

@@ -0,0 +1,6 @@
+import type { PageTicketSummary, TicketSummary } from './types.js';
+/** SQL-backed inbox discovery. Files in request_dir are presentation projections only. */
+export declare function scanInbox(): TicketSummary[];
+export type PageHistoryEntry = PageTicketSummary;
+/** SQL-backed page history, including terminal requests. */
+export declare function scanPageHistory(nodeId?: string): PageHistoryEntry[];

package/dist/core/human/scan.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var n=(e,t)=>l(e,"name",{value:t,configurable:!0});import{pageAwaitsResponse as p,pageOverviewActions as u}from"./page-schema.js";import{firstInvalidPageSpecification as m,hasPageResultException as f,listOpenInboxRequests as _,listRequests as g}from"./requests.js";function d(e){try{const t=JSON.parse(e.specification_json);if(typeof t!="object"||t===null)throw new Error("not an object");return t}catch(t){throw new Error(`corrupt human request specification: ${e.request_id}`,{cause:t})}}n(d,"specification");function a(e){const t=d(e),{recommendedOptions:i,fastAction:o}=u(t),s=e.result_json===null?null:JSON.parse(e.result_json),c=e.state!=="settled"?e.settleable?"pending":"passive":e.outcome==="canceled"||e.outcome==="dismissed"?"canceled":"resolved";return{dir:e.request_dir,id:e.request_id,inboxTicketId:e.inbox_ticket_id,kind:"page",title:e.title,subtitle:e.subtitle??"",dialect:t.dialect,placement:t.delivery.placement,inbox:e.inbox_listed,steps:t.steps,slotKinds:t.slots.map(r=>r.kind),awaitsResponse:p(t),source:t.source??{},emittedAt:typeof t.source?.emittedAt=="string"?t.source.emittedAt:e.created_at,recommendedOptions:i,...o===void 0||c!=="pending"?{}:{fastAction:o},state:c,...s?.kind==="page"?{answerDigest:s.summary.replace(/\s+/g," ").trim()}:{}}}n(a,"pageSummary");function k(e){const t=d(e),i={nodeId:e.requester_node_id??void 0};return{dir:e.request_dir,id:e.request_id,inboxTicketId:e.inbox_ticket_id,kind:"review",title:e.title,subtitle:e.subtitle??"",file:e.file??"",output:typeof t.output_path=="string"?t.output_path:`${e.request_dir}/result.json`,source:i,blockedSince:e.created_at}}n(k,"reviewSummary");function A(){return _().map(e=>e.kind==="page"?a(e):k(e)).sort((e,t)=>(t.kind==="page"?t.emittedAt:t.blockedSince).localeCompare(e.kind==="page"?e.emittedAt:e.blockedSince)||e.id.localeCompare(t.id))}n(A,"scanInbox");function v(e){const t=e!==void 0&&(m()!==null||f());return g({kind:"page",page_source_node_id:t?void 0:e}).map(a).filter(i=>!t||i.source.nodeId===e).sort((i,o)=>Date.parse(i.emittedAt)-Date.parse(o.emittedAt)||i.id.localeCompare(o.id))}n(v,"scanPageHistory");export{A as scanInbox,v as scanPageHistory};

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 @@
+var i=Object.defineProperty;var t=(e,r)=>i(e,"name",{value:r,configurable:!0});import{describePageAnswer as m}from"./answer.js";function n(e,r){return m(e,r,{completedAt:""}).digest}t(n,"buildPageSummary");export{n as buildPageSummary};

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

@@ -0,0 +1,68 @@
+import type { TicketResult } from './types.js';
+import type { PreparedPage } from './page-authoring.js';
+import { type PageManifest, type PageResponses } from './page-schema.js';
+/** Strict decoder for the canonical SQL terminal result. A corrupt result throws
+ *  rather than being treated as absent, because that would hide data loss from
+ *  the caller that owns the failure boundary. */
+export declare function readTicketResult(dir: string): TicketResult | null;
+/** Publish an immutable revision, then atomically select it with its matching specification. */
+export declare function publishPage(dir: string, prepared: PreparedPage): {
+    id: string;
+    dir: string;
+    kind: 'page';
+    manifest: PageManifest;
+};
+/** Resolve a stable request directory to the SQL-selected immutable page revision. */
+export declare function selectedPageDir(dir: string): string;
+/** Validate a final page response against its ticket's reply contract. */
+export declare function validateFinalPageResponses(manifest: PageManifest, responses: unknown): PageResponses;
+/** Validate a page resolution against its SQL-selected immutable revision. */
+export declare function validatePageTicketResponses(dir: string, responses: unknown): PageResponses;
+/** Page state is derived from the SQL request row. */
+export declare function pageTicketState(dir: string): 'pending' | 'resolved' | 'canceled' | 'passive';
+/** Autosave partial page work. Every supplied response is validated; omitted components are permitted. */
+export declare function writePageProgress(dir: string, responses: unknown): PageResponses;
+/** Saved partial work from the request row, or null when none exists. */
+export declare function readPageProgress(dir: string): PageResponses | null;
+export interface PageTicket {
+    dir: string;
+    id: string;
+    manifest: PageManifest;
+    /** The authored TSX source document, verbatim. */
+    document: string;
+    /** The compiled module the Gateway evaluates, for JSX pages. */
+    module?: string;
+    state: 'pending' | 'resolved' | 'canceled' | 'passive';
+    progress: PageResponses | null;
+}
+/** Read one addressable page ticket — pending, resolved or canceled alike. */
+export declare function readPageTicket(dir: string): PageTicket;
+export interface CompletePageOptions {
+    completedAt?: string;
+    actor?: string;
+}
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function completePage(_dir: string, _responses: unknown, _claimToken: string, _opts?: CompletePageOptions): {
+    won: boolean;
+    result: TicketResult;
+};
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function takeoverAndCompletePage(_dir: string, _responses: unknown, _owner: {
+    host: string;
+    pid: number;
+}, _opts?: CompletePageOptions): {
+    won: boolean;
+    result: TicketResult;
+};
+export interface CancelTicketOptions {
+    reason?: string;
+    actor?: string;
+    disposition?: 'canceled' | 'dismissed';
+}
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function cancelTicket(_dir: string, _opts?: CancelTicketOptions): {
+    status: 'canceled' | 'already_resolved';
+    result: TicketResult;
+};
+/** Review projection is performed by daemon/review/finish after its SQL terminal transition. */
+export declare function projectReviewOutput(_dir: string): 'projected' | 'not_a_review' | 'no_result';

package/dist/core/human/tickets.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var i=(t,e)=>w(t,"name",{value:e,configurable:!0});import{mkdirSync as q,readFileSync as d,realpathSync as _}from"node:fs";import{basename as y,isAbsolute as P,resolve as k}from"node:path";import{z as r}from"zod";import{pageModulePath as R,pagePath as S}from"./convention.js";import{parsePage as p}from"./page.js";import{validatePageResponses as E,validatePartialPageResponses as m}from"./page-schema.js";import{signalInboxActivity as g}from"./root.js";import{createPageRequest as x,getRequestByDirectory as l,presentationDir as f,publishPageRevision as j,revisePageRequest as A,writeProgress as T}from"./requests.js";const $=r.object({id:r.string().min(1),line:r.number().int().positive(),endLine:r.number().int().positive(),quote:r.string().optional(),colStart:r.number().int().nonnegative().optional(),colEnd:r.number().int().nonnegative().optional(),lineText:r.string(),comment:r.string().min(1),createdAt:r.string().min(1)}).strict(),o=r.string().datetime({offset:!0}),I=r.object({file:r.string().min(1).refine(P,"file must be absolute").refine(t=>k(t)===t,"file must be canonical"),submitted:r.literal(!0),approved:r.boolean(),comments:r.array($),submittedAt:o,savedAt:o,reviewId:r.string().optional(),changed:r.boolean().optional(),baselineSha256:r.string().optional(),approvedSha256:r.string().optional(),companionNodeId:r.string().optional(),commentsTotal:r.number().int().nonnegative().optional(),commentsUnresolved:r.number().int().nonnegative().optional()}).strict().superRefine((t,e)=>{t.comments.forEach((n,s)=>{n.endLine<n.line&&e.addIssue({code:"custom",message:"endLine must be >= line",path:["comments",s,"endLine"]}),n.colStart===void 0!=(n.colEnd===void 0)&&e.addIssue({code:"custom",message:"columns must be supplied together",path:["comments",s]}),n.line===n.endLine&&n.colStart!==void 0&&n.colEnd!==void 0&&n.colEnd<=n.colStart&&e.addIssue({code:"custom",message:"colEnd must exceed colStart",path:["comments",s,"colEnd"]})})}),h=r.record(r.string(),r.unknown()),L=r.object({schema:r.literal("crtr.page-response/v1"),kind:r.literal("page"),responses:r.record(r.string(),h),summary:r.string(),completedAt:o,actor:r.string().optional()}).strict(),Z=r.object({kind:r.literal("page"),responses:r.record(r.string(),h),savedAt:o}).strict(),O=r.object({schema:r.literal("humanloop.review-response/v1"),kind:r.literal("review"),result:I,completedAt:o}).strict(),N=r.object({schema:r.literal("humanloop.cancel/v1"),kind:r.literal("canceled"),canceledAt:o,reason:r.string().optional(),actor:r.string().optional(),disposition:r.enum(["canceled","dismissed"]).optional()}).strict();function ee(t){const e=l(t);if(e===null)throw new Error(`unknown human request directory: ${t}`);if(e.state!=="settled"||e.result_json===null)return null;let n;try{n=JSON.parse(e.result_json)}catch(b){throw new Error(`corrupt human request result: ${e.request_id}`,{cause:b})}const s=L.safeParse(n);if(s.success)return s.data;const c=O.safeParse(n);if(c.success)return c.data;const a=N.safeParse(n);if(a.success)return a.data;throw new Error(`human request has an invalid terminal result: ${e.request_id}`)}i(ee,"readTicketResult");function te(t,e){q(t,{recursive:!0,mode:448});const n=_(t),s=l(n);if(s===null){const a=x({request_id:y(n),prepared:e});return g(),{id:a.request_id,dir:a.request_dir,kind:"page",manifest:e.manifest}}const c=j(n,e);if(!A(s.request_id,{presentation_dir:c,specification_json:JSON.stringify(e.manifest),title:e.manifest.title,subtitle:e.manifest.subtitle??null,inbox_listed:e.manifest.delivery.inbox,settleable:e.manifest.delivery.inbox||e.manifest.delivery.reply}))throw new Error(`page request is not open: ${s.request_id}`);return g(),{id:s.request_id,dir:n,kind:"page",manifest:e.manifest}}i(te,"publishPage");function u(t){const e=l(t);if(e===null||e.kind!=="page")throw new Error(`unknown page request directory: ${t}`);return e}i(u,"pageRequest");function D(t){return f(u(t))}i(D,"selectedPageDir");function F(t){return p(D(t))}i(F,"requirePage");function v(t){const e=F(t);if(!e.delivery.inbox&&!e.delivery.reply)throw new Error("page_has_no_response_lifecycle");return e}i(v,"requireSettleablePage");function H(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)&&Object.keys(t).length===0}i(H,"isEmptyResponseMap");function J(t,e){return!t.delivery.reply&&H(e)?m(t,e):E(t,e)}i(J,"validateFinalPageResponses");function C(t,e){return J(v(t),e)}i(C,"validateFinalPageTicketResponses");function re(t,e){return C(t,e)}i(re,"validatePageTicketResponses");function M(t){const e=u(t);return e.settleable?e.state!=="settled"?"pending":e.outcome==="canceled"||e.outcome==="dismissed"?"canceled":"resolved":"passive"}i(M,"pageTicketState");function ne(t,e){const n=u(t),s=m(v(t),e);if(!T(n.inbox_ticket_id,s))throw new Error(`page request is not open and settleable: ${n.request_id}`);return s}i(ne,"writePageProgress");function z(t){const e=u(t);if(e.progress_json===null)return null;try{const n=JSON.parse(e.progress_json);if(n.kind!=="page")throw new Error("wrong kind");return n.responses}catch(n){throw new Error(`page progress is malformed for ${e.request_id}`,{cause:n})}}i(z,"readPageProgress");function se(t){const e=u(t),n=f(e),s=p(n);return{dir:e.request_dir,id:e.request_id,manifest:s,document:d(S(n,s.dialect),"utf8"),...s.dialect==="jsx"?{module:d(R(n),"utf8")}:{module:void 0},state:M(e.request_dir),progress:s.delivery.inbox||s.delivery.reply?z(e.request_dir):null}}i(se,"readPageTicket");function ie(t,e,n,s={}){throw new Error("page completion must use settleHumanRequest")}i(ie,"completePage");function oe(t,e,n,s={}){throw new Error("page completion must use settleHumanRequest")}i(oe,"takeoverAndCompletePage");function ae(t,e={}){throw new Error("page cancellation must use settleHumanRequest")}i(ae,"cancelTicket");function ue(t){throw new Error("review projection must use projectReviewResult")}i(ue,"projectReviewOutput");export{ae as cancelTicket,ie as completePage,M as pageTicketState,ue as projectReviewOutput,te as publishPage,z as readPageProgress,se as readPageTicket,ee as readTicketResult,D as selectedPageDir,oe as takeoverAndCompletePage,J as validateFinalPageResponses,re as validatePageTicketResponses,ne as writePageProgress};

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

@@ -0,0 +1,118 @@
+import type { PageResponses } from './page-schema.js';
+/** Provenance stamped onto every ticket request — page and review alike. */
+export interface TicketSource {
+    sessionName?: string;
+    askedBy?: string;
+    blockedSince?: string;
+    /** Profile name the originating node runs under. Product consumers use this stable name to resolve the applet or worker identity behind the ticket. */
+    profileName?: string;
+    /** Originating canvas node id (CRTR_NODE_ID) when the ask was raised inside a crouter canvas node. */
+    nodeId?: string;
+}
+export interface FeedbackComment {
+    id: string;
+    line: number;
+    endLine: number;
+    quote?: string;
+    colStart?: number;
+    colEnd?: number;
+    lineText: string;
+    comment: string;
+    createdAt: string;
+}
+export interface FeedbackResult {
+    file: string;
+    submitted: boolean;
+    approved: boolean;
+    comments: FeedbackComment[];
+    submittedAt?: string;
+    savedAt: string;
+}
+export interface ClaimSummary {
+    owner: string;
+    claimedAt: string;
+    heartbeatAt: string;
+}
+interface TicketSummaryBase {
+    dir: string;
+    id: string;
+    /** Stored opaque inbox identity. It may differ from `id` after legacy migration. */
+    inboxTicketId: string;
+    title: string;
+    subtitle: string;
+    blockedSince: string;
+    source: TicketSource;
+    claim?: ClaimSummary;
+}
+export interface ReviewTicketSummary extends TicketSummaryBase {
+    kind: 'review';
+    file: string;
+    output: string;
+}
+/** Page triage fields: a client picks a transcript rendering without a second fetch. */
+export interface PageTicketSummary {
+    dir: string;
+    id: string;
+    /** Stored opaque inbox identity. It may differ from `id` after legacy migration. */
+    inboxTicketId: string;
+    kind: 'page';
+    title: string;
+    subtitle: string;
+    source: import('./page-schema.js').PageSource;
+    emittedAt: string;
+    claim?: ClaimSummary;
+    /** Present on resolved history entries; the stored one-line response digest. */
+    answerDigest?: string;
+    dialect: 'jsx' | 'html';
+    placement: 'inline' | 'panel';
+    inbox: boolean;
+    steps: number;
+    slotKinds: string[];
+    /** This ticket is waiting on the person: it asks something, or an agent bridge is parked on its reply. */
+    awaitsResponse: boolean;
+    /** Every question's recommended option, for a row that says what is suggested without opening the page. */
+    recommendedOptions: import('./page-schema.js').RecommendedOption[];
+    /** Present when this ticket can be settled straight from a list row; absent when only the page can answer it. */
+    fastAction?: import('./page-schema.js').PageFastAction;
+    state: 'pending' | 'resolved' | 'canceled' | 'passive';
+}
+/** The only pending-ticket shape scanners expose. */
+export type TicketSummary = ReviewTicketSummary | PageTicketSummary;
+export interface ReviewDescriptor {
+    schema: 'humanloop.review/v1';
+    file: string;
+    output: string;
+    title: string;
+    subtitle: string;
+    source: TicketSource;
+    blockedSince: string;
+}
+export interface PageTicketResult {
+    schema: 'crtr.page-response/v1';
+    kind: 'page';
+    /** An acknowledgement is the empty map; there is no second shape. */
+    responses: PageResponses;
+    summary: string;
+    completedAt: string;
+    /** Recorded when an authorized programmatic writer answered instead of a person. */
+    actor?: string;
+}
+export interface ReviewTicketResult {
+    schema: 'humanloop.review-response/v1';
+    kind: 'review';
+    result: FeedbackResult;
+    completedAt: string;
+}
+export interface CanceledTicketResult {
+    schema: 'humanloop.cancel/v1';
+    kind: 'canceled';
+    canceledAt: string;
+    reason?: string;
+    actor?: string;
+    /** Who ended it without an answer: the recipient (`dismissed`) or the
+     * requester (`canceled`). Absent on records written before the field. */
+    disposition?: 'canceled' | 'dismissed';
+}
+/** The canonical terminal-result union stored in the human request row. */
+export type TicketResult = PageTicketResult | ReviewTicketResult | CanceledTicketResult;
+export {};

package/dist/core/human/visible-paths.d.ts

@@ -0,0 +1,9 @@
+/** Extract existing file paths from surface text, preserving occurrence order. */
+export declare function extractFilePaths(texts: readonly string[], cwd: string): string[];
+/** Check whether a local file fits the review surface's limits. */
+export declare function checkReviewableFile(abs: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/core/human/visible-paths.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var r=(n,t)=>f(n,"name",{value:t,configurable:!0});import{existsSync as u,readFileSync as d,statSync as a}from"node:fs";import{homedir as m}from"node:os";import{isAbsolute as h,resolve as s}from"node:path";import{documentLines as p}from"../document-lines.js";const A=50,F=2*1024*1024,E=5e3,k=/[A-Za-z0-9._~@\-/]+(?::\d+(?::\d+)?)?/g,S=/\.[A-Za-z][A-Za-z0-9]{0,15}$/;function _(n){let t=n.replace(/^[`'"(]+/,"").replace(/[`'".,;:)\]}]+$/,"");return t=t.replace(/:\d+(?::\d+)?$/,""),t.replace(/[`'".,;:)\]}]+$/,"")}r(_,"normalizeCandidate");function x(n,t){let e=_(n);return!e||!e.includes("/")&&!S.test(e)?null:(e.startsWith("~/")&&(e=s(m(),e.slice(2))),s(h(e)?e:s(t,e)))}r(x,"candidatePath");function I(n,t){const e=[],i=new Set;for(const l of n)for(const c of l.matchAll(k)){const o=x(c[0],t);if(!(o===null||i.has(o))){try{if(!u(o)||!a(o).isFile())continue}catch{continue}if(i.add(o),e.push(o),e.length===A)return e}}return e}r(I,"extractFilePaths");function v(n){let t;try{const i=a(n);if(!i.isFile())return{ok:!1,reason:"not a file"};t=i.size}catch{return{ok:!1,reason:"not a file"}}if(t>F)return{ok:!1,reason:"file is too large to review (2 MB limit)"};let e;try{e=d(n,"utf8")}catch{return{ok:!1,reason:"not a file"}}return e.includes("\uFFFD")||e.includes("\0")?{ok:!1,reason:"file is not UTF-8 text"}:p(e).length>E?{ok:!1,reason:"file is too long to review (5,000 line limit)"}:{ok:!0}}r(v,"checkReviewableFile");export{v as checkReviewableFile,I as extractFilePaths};