@north-light/crouter 0.3.154

package/dist/commands/human/prompts.js

@@ -0,0 +1,427 @@
+/**
+ * Prompt-design gap: a person opens asks from background agents without the
+ * task or conversation context. Human-ask help therefore teaches agents to
+ * make every interruption self-contained and answerable before its evidence.
+ */
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient } from '../api-client.js';
+import { nodeDir } from '../../core/canvas/paths.js';
+import { mkdirSync, existsSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { tmuxServerReachable } from '../../core/spawn.js';
+import { BrokerClient, BrokerUnavailableError } from '../../core/broker-client/index.js';
+import { markStopSignal } from '../../core/runtime/stop-signals.js';
+import { validateDeck, notifyDeck, atomicWriteJson, submitDeck, submitReview, display, } from '@crouton-kit/humanloop';
+import { DECK_SCHEMA_HINT, registerCrouterRoot, resolveMaxPanes } from './shared.js';
+import { inboxOpenInstruction, inboxPopupHint } from '../../core/keybindings/index.js';
+/** The asking node's id, or null when run from a bare shell (no parent to route to). */
+function askingNode() {
+    return process.env['CRTR_NODE_ID'] ?? null;
+}
+/** Humanloop's optional presentation label. Ticket identity and attribution
+ * come from the bridge node directory and parent relation, never ticket data. */
+export async function sourceStamp() {
+    const nodeId = askingNode();
+    if (nodeId === null || nodeId === '')
+        return {};
+    try {
+        const sessionName = (await cliClient().getNode(nodeId)).name.trim();
+        return sessionName === '' ? {} : { sessionName };
+    }
+    catch {
+        return {};
+    }
+}
+function requireAskTitle(title) {
+    if (title !== undefined)
+        return title;
+    throw new InputError({
+        error: 'missing_parameter',
+        message: 'stdin questions require a non-empty --title',
+        field: 'title',
+        next: 'Retry with a short --title naming the topic being decided.',
+    });
+}
+function requireSubtitle(subtitle, field = 'subtitle') {
+    if (subtitle !== undefined && subtitle.trim() !== '')
+        return subtitle.trim();
+    throw new InputError({
+        error: 'missing_parameter',
+        message: 'a non-empty subtitle is required',
+        field,
+        next: 'Write one plain-English sentence stating the decision, recommendation or status, and stakes.',
+    });
+}
+function validateTitledDeck(input) {
+    const title = typeof input === 'object' && input !== null
+        ? input.title
+        : undefined;
+    if (typeof title !== 'string' || title.trim() === '') {
+        throw new Error('deck title is required');
+    }
+    return validateDeck(input);
+}
+function buildHumanAskDeck(title, subtitle, question) {
+    return validateTitledDeck({
+        title,
+        interactions: [
+            {
+                id: 'question',
+                title,
+                subtitle,
+                body: question,
+                options: [],
+                allowFreetext: true,
+                freetextLabel: 'Your answer',
+            },
+        ],
+    });
+}
+/** Crouter authors decision decks by default. Persist the explicit kind so
+ * consumers can rely on Humanloop's strict interaction-kind contract. */
+function canonicalizeAskKinds(deck) {
+    return {
+        ...deck,
+        interactions: deck.interactions.map((interaction) => ({
+            ...interaction,
+            kind: interaction.kind ?? 'decision',
+        })),
+    };
+}
+const HUMAN_FORK_COORDINATES_TIMEOUT_MS = 10_000;
+const EXACT_MODEL_SPEC = /^[^/\s:]+\/[^/\s:]+:(?:off|minimal|low|medium|high|xhigh|max)$/;
+class InvalidHumanForkCoordinatesError extends Error {
+}
+class InvalidHumanForkModelError extends Error {
+}
+/** Read one pure ask-time coordinate from the source broker. Materialization is
+ * deliberately separate so this observer connection can never change its live
+ * session manager. */
+function getHumanForkCoordinates(nodeId) {
+    return new Promise((resolve, reject) => {
+        const client = new BrokerClient(nodeId);
+        let settled = false;
+        const timer = setTimeout(() => finish(() => reject(new BrokerUnavailableError(nodeId))), HUMAN_FORK_COORDINATES_TIMEOUT_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        function finish(act) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            client.close();
+            act();
+        }
+        client.on('error', () => finish(() => reject(new BrokerUnavailableError(nodeId))));
+        client.on('close', () => finish(() => reject(new BrokerUnavailableError(nodeId))));
+        client.on('connect', () => {
+            client.send({ type: 'hello', role: 'observer', client_id: randomUUID() });
+            client
+                .request({ type: 'get_human_fork_coordinates' })
+                .then((frame) => finish(() => resolve(frame)))
+                .catch(() => finish(() => reject(new BrokerUnavailableError(nodeId))));
+        });
+        client.connect();
+    });
+}
+function assertHumanForkCoordinates(coordinates) {
+    if (coordinates.kind !== 'human_fork_coordinates' || !isAbsolute(coordinates.sourceFile) || coordinates.sourceSessionId === '' || coordinates.leafId === '') {
+        throw new InvalidHumanForkCoordinatesError('broker returned invalid human fork coordinates');
+    }
+    if (coordinates.modelSpec === null || !EXACT_MODEL_SPEC.test(coordinates.modelSpec)) {
+        throw new InvalidHumanForkModelError('broker returned no exact human fork model');
+    }
+}
+function unavailableForkDetail(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return detail === '' ? undefined : detail.slice(0, 240);
+}
+/** The non-blocking status peek returned by ask/review. Resolved per call so
+ *  the inbox affordance reflects the human's current keybinding (or the CLI
+ *  fallback when the toggle is disabled). */
+function queuedFollowUp() {
+    return `Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block. To see the queue, ${inboxOpenInstruction()}.`;
+}
+// ---------------------------------------------------------------------------
+// ask
+// ---------------------------------------------------------------------------
+export const humanAsk = defineLeaf({
+    name: 'ask',
+    description: 'put a structured choice or open question to a person',
+    whenToUse: 'you would otherwise lay a decision, a set of options, or a question out for the user as prose — reach for this instead, for anything from a quick yes/no to a judgment-heavy call: gating a handoff, merge, deploy, destructive/irreversible operation, or real budget on an explicit human sign-off (offer Yes/No options), reviewing all the requirements before building, choosing among implementation patterns, walking a list of risks and deciding what to do about each, settling a naming or scope question, picking which of several findings to act on. Works for open-ended asks too (set `allowFreetext`, offer a few `options` as starting points).',
+    help: {
+        name: 'human ask',
+        summary: 'put a humanloop decision deck in front of a person; returns a job handle immediately.',
+        guide: 'Write every interaction as a self-contained decision brief for a supervisor who has not followed this agent or task: use the title to identify the inbox topic; write a one-sentence subtitle stating the decision, your recommendation, and what it changes; then give the minimum plain-language context and tradeoffs needed to decide in the body. Never coin a term, code name, or shorthand for a system, mechanism, or state, and expand any project-internal name you do use: name the thing plainly and say what it does. Invented vocabulary is not compression — the reader has to decode it before they can decide. Put supporting evidence, chronology, and technical detail under `## Details` so the person can answer without logs, screenshots, or prior conversation. For a simple open-text question, supply the short topic with --title, the required sentence with --subtitle, and pipe the markdown body on stdin. Use --context-file for a fully structured deck; its deck title and every interaction title and subtitle are required. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. Ask only what materially changes your next step, and offer genuine alternatives as `options`.',
+        params: [
+            { kind: 'flag', name: 'title', type: 'string', required: false, constraint: 'Required with stdin: a short ≤~4-word inbox topic. Mutually exclusive with --context-file, whose JSON carries its own required title.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'Required with stdin: one plain-English sentence stating the decision, recommendation, and stakes. Mutually exclusive with --context-file, whose JSON requires every interaction subtitle.' },
+            { kind: 'stdin', name: 'question', required: false, constraint: "Simple open-text ask body. Pipe markdown from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Requires --title and --subtitle; mutually exclusive with --context-file." },
+            { kind: 'context-file', name: 'deck', required: false, constraint: 'Strict structured deck JSON with a required deck title and non-empty subtitle on every interaction. Use this for multiple interactions, options, or other deck structure. Mutually exclusive with --title, --subtitle, and the question shorthand.', shape: DECK_SCHEMA_HINT },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this human interaction. Its answer is pushed to your inbox when the human responds.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding deck.json/run.json/response.json.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek; the answer arrives via your inbox.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates a kind:"human" node under you and enqueues a decision deck in the humanloop inbox.',
+            `Returns immediately; nothing opens on screen. The human answers from the inbox popup (${inboxPopupHint()}) on their own time.`,
+        ],
+    },
+    run: async (input) => {
+        // Optional stdin reaches the leaf as an empty string when omitted, including
+        // when --context-file is supplied. Keep the raw non-empty bytes untouched.
+        const titleRaw = input['title'];
+        const title = typeof titleRaw === 'string' && titleRaw.trim() !== '' ? titleRaw.trim() : undefined;
+        const questionRaw = input['question'];
+        const question = typeof questionRaw === 'string' && questionRaw !== '' ? questionRaw : undefined;
+        const subtitleRaw = input['subtitle'];
+        const subtitle = typeof subtitleRaw === 'string' && subtitleRaw.trim() !== '' ? subtitleRaw.trim() : undefined;
+        const deckInput = input['deck'];
+        if (deckInput !== undefined && (question !== undefined || titleRaw !== undefined || subtitleRaw !== undefined)) {
+            throw new InputError({
+                error: 'bad_invocation',
+                message: 'use --title and --subtitle with stdin question text, or --context-file, not both',
+                next: 'Retry with --title, --subtitle, and a piped question body, or with --context-file alone.',
+            });
+        }
+        if (question === undefined && deckInput === undefined) {
+            throw new InputError({
+                error: 'missing_parameter',
+                message: 'human ask needs stdin question text or --context-file deck.json',
+                next: 'Pipe a question body with --title and --subtitle, or pass --context-file for a structured deck.',
+            });
+        }
+        const simpleAsk = question === undefined
+            ? undefined
+            : { title: requireAskTitle(title), subtitle: requireSubtitle(subtitle), question };
+        let deck;
+        try {
+            if (simpleAsk !== undefined) {
+                deck = buildHumanAskDeck(simpleAsk.title, simpleAsk.subtitle, simpleAsk.question);
+            }
+            else {
+                deck = validateTitledDeck(deckInput);
+            }
+            deck = canonicalizeAskKinds(deck);
+        }
+        catch (e) {
+            throw new InputError({
+                error: 'deck_invalid',
+                message: String(e),
+                field: 'deck',
+                next: DECK_SCHEMA_HINT,
+            });
+        }
+        // Crouter owns this provenance. Never synthesize labels from deck content:
+        // an unavailable daemon leaves only machine attribution for routing.
+        deck = { ...deck, source: { ...await sourceStamp(), visual: 'humanloop.visual/v1' } };
+        const cwd = process.cwd();
+        const jobId = (await cliClient().createHumanBridge({ kind: 'human', parent: askingNode(), cwd, name: 'human-ask' })).node_id;
+        const idir = nodeDir(jobId);
+        mkdirSync(idir, { recursive: true });
+        const rc = { mode: 'ask', job_id: jobId };
+        const capturedAt = new Date().toISOString();
+        const originNodeId = askingNode();
+        if (originNodeId === null) {
+            rc.conversation_fork = { status: 'unavailable', reason: 'no_origin', captured_at: capturedAt };
+        }
+        else {
+            try {
+                const coordinates = await getHumanForkCoordinates(originNodeId);
+                assertHumanForkCoordinates(coordinates);
+                // Loaded on demand: session-branch pulls pi's SessionManager, whose
+                // module graph costs ~385ms. Only a conversation fork needs it, so a
+                // static import would charge that to EVERY `crtr human` invocation.
+                const { materializeSessionBranchAt } = await import('../../core/runtime/session-branch.js');
+                materializeSessionBranchAt(coordinates, join(idir, 'branch-point.jsonl'));
+                rc.conversation_fork = {
+                    status: 'ready',
+                    source_node_id: originNodeId,
+                    source_file: coordinates.sourceFile,
+                    source_session_id: coordinates.sourceSessionId,
+                    leaf_id: coordinates.leafId,
+                    model_spec: coordinates.modelSpec,
+                    branch_point: 'branch-point.jsonl',
+                    captured_at: new Date().toISOString(),
+                };
+            }
+            catch (err) {
+                const reason = err instanceof BrokerUnavailableError
+                    ? 'broker_unavailable'
+                    : err instanceof InvalidHumanForkCoordinatesError
+                        ? 'invalid_coordinates'
+                        : err instanceof InvalidHumanForkModelError
+                            ? 'invalid_model'
+                            : 'materialization_failed';
+                rc.conversation_fork = {
+                    status: 'unavailable',
+                    reason,
+                    detail: unavailableForkDetail(err),
+                    captured_at: capturedAt,
+                };
+            }
+        }
+        atomicWriteJson(join(idir, 'run.json'), rc);
+        const root = registerCrouterRoot();
+        const { dir } = submitDeck({ root, id: jobId, deck });
+        if (originNodeId !== null && originNodeId !== '')
+            markStopSignal(originNodeId, 'askedHuman');
+        return { job_id: jobId, dir, follow_up: queuedFollowUp() };
+    },
+});
+// ---------------------------------------------------------------------------
+// review
+// ---------------------------------------------------------------------------
+export const humanReview = defineLeaf({
+    name: 'review',
+    description: 'collect anchored comments on a document or source file',
+    whenToUse: 'a human should comment line-by-line on a document rather than give one overall answer: reviewing a plan or spec before you build it, marking up a draft, flagging specific sections to change. The comments come back anchored to the lines they touch. Use `ask` instead for a single yes/no sign-off on the whole thing, or to pose a discrete choice',
+    help: {
+        name: 'human review',
+        summary: "queue a .md artifact or a source file for anchored, line-by-line human comments; returns a job handle instantly (a non-blocking kickoff, like ask). The human opens it from the inbox popup, which previews the live doc and re-reads it on every save, so edit in place rather than re-presenting.",
+        guide: `A kickoff, not a blocking call: it returns at once and the human reviews on their own time from the inbox (${inboxPopupHint()}). When they submit, the FeedbackResult (anchored comments, plus any line edits they made) is pushed to your inbox — waking you — and autosaved to \`output\`. The inbox preview is a LIVE view of the file: keep editing it in place and it updates, so do not cancel and re-present to show a change. Write the subtitle and the document itself in plain words: no coined terms or internal shorthand for a system or concept — name it and explain what it does, with enough context for someone who has not followed this work. A .md file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`termrender doc -h\` for the directive set before authoring one. Any other UTF-8 text file (a .ts/.py/.sql source) is reviewed as a syntax-highlighted source panel anchored to its real line numbers; limits are 2 MB and 5,000 lines.`,
+        params: [
+            { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Absolute path to an existing UTF-8 text file: a .md artifact, or a source file to review as code.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: true, constraint: 'One plain-English sentence stating what review feedback is needed and why it matters.' },
+            { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where the FeedbackResult JSON is written. Default: <dir>/feedback.json.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of the kind:"human" node backing this review. Its FeedbackResult is pushed to your inbox when the human submits.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding run.json and the autosaved feedback.json.' },
+            { name: 'output', type: 'string', required: true, constraint: 'Path the FeedbackResult JSON is autosaved to when the human submits.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek; comments arrive via your inbox when the human submits.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates a kind:"human" node under you and enqueues an anchored review in the humanloop inbox.',
+            `Returns immediately; nothing opens on screen. The human reviews from the inbox popup (${inboxPopupHint()}); comments fan into your inbox when they submit.`,
+        ],
+    },
+    run: async (input) => {
+        const fileArg = input['file'];
+        const abs = resolve(fileArg);
+        if (!existsSync(abs)) {
+            throw new InputError({
+                error: 'file_not_found',
+                message: `file not found: ${abs}`,
+                field: 'file',
+                next: 'Provide an absolute path to an existing file.',
+            });
+        }
+        const subtitle = requireSubtitle(input['subtitle']);
+        const cwd = process.cwd();
+        const jobId = (await cliClient().createHumanBridge({ kind: 'human', parent: askingNode(), cwd, name: 'human-review' })).node_id;
+        const idir = nodeDir(jobId);
+        mkdirSync(idir, { recursive: true });
+        const rc = { mode: 'review', job_id: jobId };
+        atomicWriteJson(join(idir, 'run.json'), rc);
+        const outputArg = input['output'];
+        const root = registerCrouterRoot();
+        const { dir } = submitReview({
+            root,
+            id: jobId,
+            review: {
+                file: abs,
+                ...(outputArg !== undefined ? { output: resolve(outputArg) } : {}),
+                title: abs.split('/').pop() ?? abs,
+                subtitle,
+                source: await sourceStamp(),
+            },
+        });
+        const output = outputArg !== undefined ? resolve(outputArg) : join(dir, 'feedback.json');
+        return { job_id: jobId, dir, output, follow_up: queuedFollowUp() };
+    },
+});
+// ---------------------------------------------------------------------------
+// notify (no job)
+// ---------------------------------------------------------------------------
+export const humanNotify = defineLeaf({
+    name: 'notify',
+    description: 'fire-and-forget acknowledgement, no reply expected',
+    whenToUse: 'informing a person without blocking or expecting an answer',
+    help: {
+        name: 'human notify',
+        summary: 'enqueue a fire-and-forget acknowledgement in the human inbox; creates no job',
+        guide: 'State what happened in plain words — no coined terms or internal shorthand for a system or concept; name it and say what it does. The body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
+        params: [
+            { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The notification headline.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: true, constraint: 'One plain-English sentence stating the notification status and stakes.' },
+            { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body.' },
+        ],
+        output: [
+            { name: 'queued', type: 'boolean', required: true, constraint: 'Always true — the notify deck is durable inbox state the human acknowledges from the popup.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding deck.json.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Enqueues a durable notify deck in the human inbox. Creates no node; nothing opens on screen.',
+        ],
+    },
+    run: async (input) => {
+        const title = input['title'];
+        const subtitle = requireSubtitle(input['subtitle']);
+        const body = input['body'];
+        let deck = notifyDeck(title, { subtitle, ...(body !== undefined ? { body } : {}) });
+        deck = { ...deck, source: await sourceStamp() };
+        const id = `nfy-${randomBytes(4).toString('hex')}`;
+        const idir = nodeDir(id);
+        mkdirSync(idir, { recursive: true });
+        const rc = { mode: 'notify' };
+        atomicWriteJson(join(idir, 'run.json'), rc);
+        const root = registerCrouterRoot();
+        const { dir } = submitDeck({ root, id, deck });
+        return { queued: true, dir };
+    },
+});
+// ---------------------------------------------------------------------------
+// show (no job, non-blocking passthrough) — passive live document display, NOT
+// a ticket surface. Retained per the tmux-inbox cutover: `display()` puts a
+// file live in a watch pane and never enqueues anything.
+// ---------------------------------------------------------------------------
+export const humanShow = defineLeaf({
+    name: 'show',
+    description: "put a file live on the human's screen",
+    whenToUse: 'displaying a doc on screen while a human comments',
+    help: {
+        name: 'human show',
+        summary: 'put a file live on screen in a tmux pane via humanloop display',
+        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
+        params: [
+            { kind: 'positional', name: 'path', type: 'path', required: true, constraint: 'Path to the file to render.' },
+            { kind: 'flag', name: 'window', type: 'enum', choices: ['auto', 'split', 'new'], required: false, default: 'auto', constraint: 'Placement. Default auto.' },
+        ],
+        output: [
+            { name: 'pane_id', type: 'string | null', required: true, constraint: 'Tmux pane id, or null when not displayed.' },
+            { name: 'reason', type: 'string | null', required: true, constraint: 'Why no pane was created, or null on success.' },
+        ],
+        outputKind: 'object',
+        effects: ['Spawns a live-watch tmux pane when possible. No job. Always exits 0.'],
+    },
+    run: async (input) => {
+        const path = input['path'];
+        const windowArg = input['window'];
+        const window = windowArg !== undefined ? windowArg : 'auto';
+        // `human show` must never fail the caller: any display error degrades to
+        // {pane_id:null, reason} with exit 0 (matches humanloop display semantics).
+        let paneId;
+        try {
+            const r = display(path, { window, maxPanes: resolveMaxPanes() });
+            paneId = r.paneId;
+        }
+        catch {
+            paneId = undefined;
+        }
+        if (paneId !== undefined) {
+            return { pane_id: paneId, reason: null };
+        }
+        const reason = tmuxServerReachable()
+            ? 'renderer unavailable (termrender/uv missing)'
+            : 'not in tmux';
+        return { pane_id: null, reason };
+    },
+});

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

@@ -0,0 +1,12 @@
+import type { Deck, InteractionResponse } from '@crouton-kit/humanloop';
+export declare const humanList: import("../../core/command.js").LeafDef;
+export declare const humanDeck: import("../../core/command.js").LeafDef;
+/** Pure core of {@link coerceSingleSelect}, split out so it is testable without
+ *  a deck.json on disk. */
+export declare function coerceSingleSelectAgainst(responses: InteractionResponse[], deck: Deck): InteractionResponse[];
+export declare const humanResolve: import("../../core/command.js").LeafDef;
+export declare const humanCancel: import("../../core/command.js").LeafDef;
+export declare const humanDeliver: import("../../core/command.js").LeafDef;
+export declare const humanConsult: import("../../core/command.js").LeafDef;
+export declare const humanVisual: import("../../core/command.js").LeafDef;
+export declare const humanFocus: import("../../core/command.js").LeafDef;