@north-light/crouter 0.3.170 → 0.3.172

package/dist/commands/human/queue.js

@@ -1,28 +1,17 @@
+import { existsSync } from 'node:fs';
+import { basename } from 'node:path';
+import { ApiError } from '../../api/index.js';
 import { defineLeaf } from '../../core/command.js';
+import { ticketDir } from '../../core/human/root.js';
+import { scanInbox } from '../../core/human/scan.js';
+import { parseDeck } from '../../core/human/deck-schema.js';
+import { deckPath, isResolved, readJson, reviewPath } from '../../core/human/convention.js';
 import { InputError } from '../../core/io.js';
-import { ApiError } from '../../api/index.js';
-import { cliClient, rethrowAsCliError } from '../api-client.js';
-import { nodeDir, nodesRoot } from '../../core/canvas/paths.js';
 import { paginate } from '../../core/pagination.js';
-import { existsSync, realpathSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
-import { scanInbox, parseDeck, deckPath, reviewPath, isResolved, readJson, claimTicket, completeDeck, cancelTicket, listInboxRoots, } from '@crouton-kit/humanloop';
-import { crouterFocusHandler } from './shared.js';
-import { focusViewer } from '../node.js';
-/** Canonicalize a completion-event path the same way humanloop's registry does
- *  (realpath-resolved), falling back to a plain `resolve()` when the path no
- *  longer exists on disk, so the `_focus` containment/registration checks
- *  compare like against like regardless of symlinked path components. */
-function canonicalPath(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        return resolve(p);
-    }
-}
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { filterVisibleReviewTickets } from '../../clients/inbox/review-visibility.js';
 function toRef(n) {
-    return { node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent };
+    return { node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent, status: n.status };
 }
 /** The canvas roster, fetched ONCE per leaf run through the API and threaded
  *  into the sync provenance helpers below (they used to call `listNodes()`/
@@ -96,10 +85,17 @@ function summarizeTicket(summary, nodes, byId) {
     };
 }
 function interactionDirForJob(jobId, byId) {
-    if (byId.has(jobId))
-        return { dir: nodeDir(jobId) };
+    const node = byId.get(jobId);
+    if (node !== undefined)
+        return { dir: ticketDir(jobId), node };
     throw new InputError({ error: 'not_found', message: `no interaction node: ${jobId}`, field: 'job_id', next: 'Pass a job_id from `crtr human list`.' });
 }
+function isTerminalBridge(status) {
+    return status === 'done' || status === 'dead' || status === 'canceled';
+}
+function isAlreadyResolvedConflict(error) {
+    return error instanceof ApiError && error.status === 409 && error.code === 'ticket_already_resolved';
+}
 // ---------------------------------------------------------------------------
 // list (read-only, paginated)
 // ---------------------------------------------------------------------------
@@ -126,9 +122,10 @@ export const humanList = defineLeaf({
         const limitRaw = input['limit'];
         const limit = Math.min(Math.max(1, limitRaw), 100);
         const cursor = input['cursor'];
+        const { tickets } = await cliClient().listHumanInbox();
+        const raw = filterVisibleReviewTickets(scanInbox(), new Set(tickets.map((ticket) => ticket.ticket_id)));
         const nodes = await fetchNodeRefs();
         const byId = new Map(nodes.map((n) => [n.node_id, n]));
-        const raw = scanInbox([nodesRoot()]);
         const items = raw
             .flatMap((s) => {
             const item = summarizeTicket(s, nodes, byId);
@@ -153,7 +150,7 @@ export const humanList = defineLeaf({
 // ---------------------------------------------------------------------------
 export const humanDeck = defineLeaf({
     name: 'deck',
-    description: 'read one pending humanloop deck',
+    description: 'read one pending human deck',
     whenToUse: 'you need the full questions/options for a pending human interaction',
     help: {
         name: 'human deck',
@@ -236,13 +233,13 @@ function parseResolveBody(raw) {
     });
 }
 /**
- * Translate web-shaped answers into humanloop's response contract. Web clients
- * always send `selectedOptionIds` (an array) for every option pick, but
- * humanloop's strict deck validator rejects an array on any non-multiSelect
+ * Translate web-shaped answers into the ticket response contract. Web clients
+ * always send `selectedOptionIds` (an array) for every option pick, but the
+ * strict deck validator rejects an array on any non-multiSelect
  * interaction. For a single-select interaction we faithfully fold a
  * single-element array down to `selectedOptionId` (deterministic given the
  * deck's own multiSelect flag — not a lenient guess). Multi-select and freetext
- * responses pass through untouched; an unreadable deck is left to completeDeck.
+ * responses pass through untouched; an unreadable deck is left to the daemon.
  */
 function coerceSingleSelect(responses, dir) {
     const deck = readJson(deckPath(dir));
@@ -260,58 +257,54 @@ export function coerceSingleSelectAgainst(responses, deck) {
         if (r.selectedOptionId !== undefined || r.selectedOptionIds === undefined)
             return r;
         if (r.selectedOptionIds.length !== 1)
-            return r; // 0 or >1 stays → humanloop rejects
+            return r; // 0 or >1 stays → the validator rejects
         const { selectedOptionIds, ...keep } = r;
         return { ...keep, selectedOptionId: selectedOptionIds[0] };
     });
 }
 export const humanResolve = defineLeaf({
     name: 'resolve',
-    description: 'resolve one humanloop deck from stdin answers',
-    whenToUse: 'a browser or local tool is submitting answers for a pending human interaction; this delegates to the humanloop finalize/completion path',
+    description: 'resolve one human deck from stdin answers',
+    whenToUse: 'a browser or local tool is submitting answers for a pending human interaction.',
     tier: 'hidden',
     help: {
         name: 'human resolve',
-        summary: 'claim a pending deck through humanloop, finalize it with the given answers, and let the completion boundary deliver back to the asking node',
+        summary: 'resolve a pending deck with the given answers and deliver them to the asking node',
         params: [
             { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'job_id from human ask/review/list.' },
             { kind: 'stdin', name: 'body', required: true, constraint: 'JSON {responses:[{interaction_id, selected_option_ids?, freetext?}]}.' },
         ],
         output: [
-            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call won and finalized the deck. Delivery to the asking node happens asynchronously at humanloop\'s completion boundary and may lag or fail independently of this result.' },
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call answered and delivered the deck to the asking node.' },
             { name: 'job_id', type: 'string', required: true, constraint: 'Interaction job id.' },
             { name: 'reason', type: 'string', required: false, constraint: 'already_resolved or claimed when resolved is false.' },
         ],
         outputKind: 'object',
-        effects: ['Claims the ticket via humanloop, finalizes response.json through humanloop\'s exclusive publish, and lets humanloop invoke crouter\'s registered completion handler. Never writes response.json itself.'],
+        effects: ['The daemon publishes the answer, delivers it to the asking node, and retires the bridge before this call returns.'],
     },
     run: async (input) => {
         const jobId = input['job_id'];
         const nodes = await fetchNodeRefs();
         const byId = new Map(nodes.map((n) => [n.node_id, n]));
-        const { dir } = interactionDirForJob(jobId, byId);
+        const { dir, node } = interactionDirForJob(jobId, byId);
         if (!existsSync(deckPath(dir))) {
             throw new InputError({ error: 'not_found', message: `no deck for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
         }
         const responses = coerceSingleSelect(parseResolveBody(input['body']), dir);
-        if (isResolved(dir))
+        // A published result on a live bridge may be an interrupted delivery. The
+        // daemon re-drives that delivery before it returns its 409, so only bypass
+        // it when the bridge is already terminal.
+        if (isResolved(dir) && isTerminalBridge(node.status)) {
             return { resolved: false, job_id: jobId, reason: 'already_resolved' };
-        const claim = claimTicket(dir);
-        if (claim === null) {
-            return { resolved: false, job_id: jobId, reason: isResolved(dir) ? 'already_resolved' : 'claimed' };
         }
-        let won;
         try {
-            ({ won } = await completeDeck(dir, responses, claim.token));
+            await cliClient().resolveHumanTicket(jobId, { responses });
         }
         catch (e) {
-            throw new InputError({ error: 'invalid_field', message: String(e), field: 'responses', next: 'Use interaction/option ids from `crtr human deck <job_id> --json`.' });
+            if (isAlreadyResolvedConflict(e))
+                return { resolved: false, job_id: jobId, reason: 'already_resolved' };
+            rethrowAsCliError(e);
         }
-        if (!won)
-            return { resolved: false, job_id: jobId, reason: 'already_resolved' };
-        // Finalization won. Delivery back to the asking node is humanloop's
-        // completion-boundary responsibility (may lag or fail → delivery-error.json),
-        // so we do NOT claim delivery here — only that the deck was finalized.
         return { resolved: true, job_id: jobId };
     },
 });
@@ -325,7 +318,7 @@ export const humanCancel = defineLeaf({
     help: {
         name: 'human cancel',
         summary: 'retract a pending ask/review you posed — drops it from the human inbox and retires the bridge node. Reach for this the moment a question goes stale (you answered it yourself, the situation changed) so a human is not left resolving a prompt whose answer no longer matters',
-        guide: 'Pass the job_id returned by `human ask`/`review`. Best-effort and idempotent: if the human already answered, or it was already canceled, it reports canceled:false with reason "already_resolved" and changes nothing. Cancellation races the human\'s submit through humanloop\'s exclusive final publish; whichever wins is authoritative. The agent that posed the deck is almost always the one canceling it, so the caller is never messaged — only OTHER subscribers get a quiet deferred note that no answer is coming.',
+        guide: 'Pass the job_id returned by `human ask`/`review`. Best-effort and idempotent: if the human already answered, or it was already canceled, it reports canceled:false with reason "already_resolved" and changes nothing. Cancellation races the human\'s submit; whichever wins is authoritative. The agent that posed the deck is almost always the one canceling it, so the caller is never messaged — only OTHER subscribers get a quiet deferred note that no answer is coming.',
         params: [
             { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Node id of the interaction to cancel — the job_id returned by ask/review.' },
             { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Optional short note delivered to subscribers explaining why it was retracted.' },
@@ -337,8 +330,7 @@ export const humanCancel = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Races a canceled response.json through humanloop so the interaction drops out of the human inbox.',
-            'On a winning cancellation, humanloop invokes crouter\'s completion handler, which retires the bridge node and drops a deferred no-answer note to waiting subscribers other than the caller.',
+            'The daemon retires the bridge and notifies subscribers other than the caller that no answer is coming.',
         ],
     },
     run: async (input) => {
@@ -353,179 +345,25 @@ export const humanCancel = defineLeaf({
                 next: 'Pass the job_id from human ask/review, or list pending with `crtr human list`.',
             });
         }
-        const idir = nodeDir(jobId);
-        // Nothing live to cancel: already answered/canceled/retired, or the ticket
-        // never carried a request descriptor humanloop can cancel.
+        const idir = ticketDir(jobId);
+        // Nothing live to cancel: the bridge is already terminal, or the ticket
+        // never carried a request descriptor.
         const hasDescriptor = existsSync(deckPath(idir)) || existsSync(reviewPath(idir));
-        if (node.status === 'done' || node.status === 'dead' || node.status === 'canceled' || isResolved(idir) || !hasDescriptor) {
+        if (isTerminalBridge(node.status) || !hasDescriptor) {
             return { canceled: false, job_id: jobId, reason: 'already_resolved' };
         }
         const actor = process.env['CRTR_NODE_ID'] ?? 'human';
-        const { status } = await cancelTicket(idir, { ...(reason !== undefined && reason !== '' ? { reason } : {}), actor });
-        if (status === 'already_resolved') {
-            return { canceled: false, job_id: jobId, reason: 'already_resolved' };
-        }
-        // The winning cancellation dispatched completion → `_deliver` synchronously
-        // retired the bridge and notified subscribers. Nothing to do here.
-        return { canceled: true, job_id: jobId };
-    },
-    render: (r) => r['canceled'] === true
-        ? `Canceled human interaction ${r['job_id']} — it left the human inbox and subscribers were notified no answer is coming.`
-        : `Nothing to cancel for ${r['job_id']} — ${r['reason'] ?? 'nothing to cancel'}.`,
-});
-// ---------------------------------------------------------------------------
-// _deliver / _consult / _visual (hidden completion handlers; not listed in
-// branch help) — thin forwarders to crtrd.
-//
-// humanloop invokes `node dist/cli.js human _deliver|_consult|_visual` with the
-// event JSON on stdin (registered via `registerCrouterRoot`). The handler body
-// — every canvas mutation (spawnNode/reviveNode/transition/pushFinal/arm/claim/
-// retire/reconcile) plus the FULL trust binding re-verification — lives
-// server-side in `src/daemon/api/handlers/human.ts`. These leaves just parse
-// the stdin event and POST it to the daemon, which re-verifies the trust
-// binding before acting. Keeping ZERO canvas imports here is what lets the CLI
-// import graph stay clear of canvas.db (spec §1/§10).
-// ---------------------------------------------------------------------------
-/** Parse a humanloop event off stdin. A malformed body is the caller's error
- *  (humanloop always sends valid JSON), surfaced as a clean InputError rather
- *  than a raw SyntaxError. */
-function parseEvent(body) {
-    try {
-        return JSON.parse(body);
-    }
-    catch (e) {
-        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(e)}`, field: 'stdin', next: 'Only humanloop invokes this handler.' });
-    }
-}
-export const humanDeliver = defineLeaf({
-    name: '_deliver',
-    tier: 'hidden',
-    help: {
-        name: 'human _deliver',
-        summary: 'internal: the registered humanloop completion handler — turns a resolved/canceled ticket into the existing pushFinal delivery and bridge finalization',
-        params: [
-            { kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.completion/v1 event JSON on stdin. Not for manual use.' },
-        ],
-        output: [{ name: 'delivered', type: 'boolean', required: true, constraint: 'True once the bridge is delivered/retired (or already terminal).' }],
-        outputKind: 'object',
-        effects: ['Reads the completion event, forwards it to crtrd, which verifies root registration/containment then pushFinals the answer (ask/review) or retires the bridge (canceled). Idempotent: replay after a crash is safe.'],
-    },
-    run: async (input) => {
-        const event = parseEvent(input['body']);
         try {
-            return await cliClient().deliverHuman(event);
+            await cliClient().cancelHumanTicket(jobId, { ...(reason !== undefined && reason !== '' ? { reason } : {}), actor });
         }
         catch (e) {
+            if (isAlreadyResolvedConflict(e))
+                return { canceled: false, job_id: jobId, reason: 'already_resolved' };
             rethrowAsCliError(e);
         }
+        return { canceled: true, job_id: jobId };
     },
-});
-export const humanConsult = defineLeaf({
-    name: '_consult',
-    tier: 'hidden',
-    help: {
-        name: 'human _consult',
-        summary: 'internal: the registered humanloop follow-up handler — verifies capability + a live running request, then launches (or cancels) a private consult fork answering privately back to the ticket',
-        params: [
-            { kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.followup-request/v1 event JSON on stdin. Not for manual use.' },
-        ],
-        output: [
-            {
-                name: 'handled',
-                type: 'boolean',
-                required: true,
-                constraint: 'True when the start/cancel action was actually acted on; false when trust/currency checks rejected it as stale (already superseded/canceled/unregistered/not an ask ticket). Humanloop always gets a fast exit 0 either way — this never throws for a stale event.',
-            },
-        ],
-        outputKind: 'object',
-        effects: [
-            "action:start — crtrd verifies owner+capability+registration identity+run.json(ask)+a live running request, arms a receipted outbox row, launches a detached parent=null consult fork at the exact captured model from the captured branch point, then re-checks the request is still current and cancels the fork if it was superseded/canceled during launch.",
-            'action:cancel — crtrd cancels the request-bound consult fork (if any) and marks its outbox row canceled.',
-            'Once trust and request currency are both established, a missing/unreadable captured branch, a missing captured model, or a synchronous launch fault all publish an error follow-up result immediately instead of declining silently, so the ticket never sticks on "consulting\u2026".',
-        ],
-    },
-    run: async (input) => {
-        const event = parseEvent(input['body']);
-        try {
-            return await cliClient().consultHuman(event);
-        }
-        catch (e) {
-            rethrowAsCliError(e);
-        }
-    },
-});
-export const humanVisual = defineLeaf({
-    name: '_visual',
-    tier: 'hidden',
-    help: {
-        name: 'human _visual',
-        summary: 'internal: validates and launches or retires one exact Humanloop Visual fork',
-        params: [{ kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.visual-request-event/v1 event JSON. Not for manual use.' }],
-        output: [{ name: 'handled', type: 'boolean', required: true, constraint: 'True when the exact Visual delivery was acknowledged.' }],
-        outputKind: 'object',
-        effects: ['Forwards the event to crtrd, which creates at most one lifecycle-owned exact-model Visual child, or retires only its immutable matching child.'],
-    },
-    run: async (input) => {
-        const event = parseEvent(input['body']);
-        try {
-            return await cliClient().visualHuman(event);
-        }
-        catch (e) {
-            rethrowAsCliError(e);
-        }
-    },
-});
-// ---------------------------------------------------------------------------
-// _focus (hidden inbox-source handler; not listed in branch help)
-//
-// Unlike _deliver/_consult/_visual, focus is a pure VIEWER/tmux placement — it
-// reveals the originating conversation beside the inbox popup pane. tmux
-// placement is client-side in this architecture (crtrd owns canvas state, not
-// the viewer surface), so this leaf stays in the CLI: the canvas read routes
-// through `getNodeOrNull` (the API) and the revive + view.sock wait happen
-// inside `focusViewer` via `cliClient().ensureAttach()`.
-// ---------------------------------------------------------------------------
-export const humanFocus = defineLeaf({
-    name: '_focus',
-    tier: 'hidden',
-    help: {
-        name: 'human _focus',
-        summary: 'internal: reveal the conversation that created a humanloop ticket',
-        params: [{ kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.focus/v1 event JSON on stdin. Not for manual use.' }],
-        output: [{ name: 'focused', type: 'boolean', required: true, constraint: 'True once the originating conversation viewer is visible.' }],
-        outputKind: 'object',
-        effects: ['Verifies the registered ticket and focuses its source node beside the tmux pane underneath the inbox popup, opening a viewer when needed.'],
-    },
-    run: async (input) => {
-        const event = JSON.parse(input['body']);
-        if (event.schema !== 'humanloop.focus/v1') {
-            throw new InputError({ error: 'invalid_field', message: 'not a humanloop.focus/v1 event', field: 'stdin', next: 'Only humanloop invokes this handler.' });
-        }
-        const root = canonicalPath(event.root);
-        const dir = canonicalPath(event.dir);
-        if (resolve(dir, '..') !== root || basename(dir) !== event.ticketId) {
-            throw new InputError({ error: 'invalid_field', message: 'focus event does not identify a ticket directly beneath its root', field: 'stdin', next: 'Only humanloop invokes this handler.' });
-        }
-        const registration = listInboxRoots().find((candidate) => candidate.root === root && candidate.owner === 'crouter');
-        if (registration === undefined || JSON.stringify(registration.focusHandler) !== JSON.stringify(crouterFocusHandler())) {
-            throw new InputError({ error: 'invalid_field', message: `root has no trusted crouter focus handler: ${root}`, field: 'stdin', next: 'Only humanloop invokes this handler.' });
-        }
-        if (!/^%\d+$/.test(event.targetPane)) {
-            throw new InputError({ error: 'invalid_field', message: 'focus event has an invalid tmux target pane', field: 'stdin', next: 'Only humanloop invokes this handler.' });
-        }
-        const bridge = await getNodeOrNull(event.ticketId);
-        const sourceNodeId = bridge?.parent;
-        if (sourceNodeId === null || sourceNodeId === undefined || sourceNodeId === '') {
-            throw new InputError({ error: 'not_found', message: 'ticket has no originating canvas conversation', field: 'stdin', next: 'Close the inbox normally; this ticket was created outside a canvas conversation.' });
-        }
-        const source = await getNodeOrNull(sourceNodeId);
-        if (source === null || source.kind === 'human' || (source.status !== 'active' && source.status !== 'idle')) {
-            throw new InputError({ error: 'not_focusable', message: `originating conversation ${sourceNodeId} is no longer live`, field: 'stdin', next: 'Close the inbox normally; completed conversations are available through canvas history.' });
-        }
-        const result = await focusViewer(sourceNodeId, { pane: event.targetPane, cwd: source.cwd, name: source.name });
-        if (!result.focused) {
-            throw new InputError({ error: 'focus_failed', message: `could not bring originating conversation ${sourceNodeId} into view`, next: 'Close the inbox and focus the node from the canvas.' });
-        }
-        return { focused: true };
-    },
+    render: (r) => r['canceled'] === true
+        ? `Canceled human interaction ${r['job_id']} — it left the human inbox and subscribers were notified no answer is coming.`
+        : `Nothing to cancel for ${r['job_id']} — ${r['reason'] ?? 'nothing to cancel'}.`,
 });

package/dist/commands/human/review.d.ts

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../../core/command.js';
+export declare const humanReviewBranch: BranchDef;