@north-light/crouter 0.3.173 → 0.3.174

package/dist/commands/human/queue.js

@@ -217,55 +217,22 @@ function parseResolveBody(raw) {
         throw new InputError({ error: 'invalid_field', message: 'responses must be an array', field: 'responses', next: 'Pass {"responses":[{"interaction_id":"...","selected_option_ids":["..."]}]}.' });
     }
     return parsed.responses.map((r) => {
-        const id = r.interaction_id ?? r.id;
-        if (id === undefined || id === '') {
+        if (r.interaction_id === undefined || r.interaction_id === '') {
             throw new InputError({ error: 'invalid_field', message: 'each response needs interaction_id', field: 'responses', next: 'Include interaction_id for every response.' });
         }
-        const selectedOptionIds = r.selected_option_ids ?? r.selectedOptionIds;
-        const selectedOptionId = r.selected_option_id ?? r.selectedOptionId;
         return {
-            id,
-            ...(selectedOptionIds !== undefined ? { selectedOptionIds } : {}),
-            ...(selectedOptionId !== undefined ? { selectedOptionId } : {}),
+            id: r.interaction_id,
+            ...(r.selected_option_ids !== undefined ? { selectedOptionIds: r.selected_option_ids } : {}),
+            ...(r.selected_option_id !== undefined ? { selectedOptionId: r.selected_option_id } : {}),
             ...(r.freetext !== undefined ? { freetext: r.freetext } : {}),
-            ...(r.optionComments !== undefined ? { optionComments: r.optionComments } : {}),
+            ...(r.option_comments !== undefined ? { optionComments: r.option_comments } : {}),
         };
     });
 }
-/**
- * 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 the daemon.
- */
-function coerceSingleSelect(responses, dir) {
-    const deck = readJson(deckPath(dir));
-    if (deck === null || deck === undefined)
-        return responses;
-    return coerceSingleSelectAgainst(responses, deck);
-}
-/** Pure core of {@link coerceSingleSelect}, split out so it is testable without
- *  a deck.json on disk. */
-export function coerceSingleSelectAgainst(responses, deck) {
-    const isMulti = new Map(deck.interactions.map((it) => [it.id, it.multiSelect === true]));
-    return responses.map((r) => {
-        if (isMulti.get(r.id) === true)
-            return r;
-        if (r.selectedOptionId !== undefined || r.selectedOptionIds === undefined)
-            return r;
-        if (r.selectedOptionIds.length !== 1)
-            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 human deck from stdin answers',
-    whenToUse: 'a browser or local tool is submitting answers for a pending human interaction.',
+    whenToUse: 'an API client or local tool is submitting answers for a pending human interaction.',
     tier: 'hidden',
     help: {
         name: 'human resolve',
@@ -290,7 +257,7 @@ export const humanResolve = defineLeaf({
         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);
+        const responses = parseResolveBody(input['body']);
         // 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.

package/dist/commands/memory/list.d.ts

@@ -1 +1,15 @@
+import type { MemoryDoc, MemoryScope } from '../../core/memory-resolver.js';
+/** A fully-resolved memory inventory before command pagination/output shaping.
+ * Shared in-process consumers retain `memory list`'s scope ordering and
+ * identity behavior without rescanning the corpus once per output page. */
+export interface ListedMemoryDoc {
+    name: string;
+    kind: string;
+    scope: MemoryScope;
+    path: string;
+    shortForm: string;
+    isDir: boolean;
+    slash: boolean;
+}
+export declare function listMemoryDocs(kindFilter?: string, scopeFilter?: MemoryScope, quiet?: boolean, docs?: readonly MemoryDoc[]): ListedMemoryDoc[];
 export declare const listLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/list.js

@@ -4,6 +4,40 @@ import { parseSubstrateDoc } from '../../core/substrate/schema.js';
 import { isIndexName, indexDirOf } from '../../core/substrate/ceiling.js';
 import { paginate } from '../../core/pagination.js';
 import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
+export function listMemoryDocs(kindFilter, scopeFilter, quiet = false, docs = listAllMemoryDocs(scopeFilter, quiet)) {
+    const seen = new Set(); // "scope/name" → first wins
+    const items = [];
+    const addItem = (item) => {
+        const id = `${item.scope}/${item.name}`;
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        items.push(item);
+    };
+    // Substrate memory docs (project > user > builtin precedence).
+    for (const doc of docs) {
+        const sub = parseSubstrateDoc(doc);
+        if (sub === null)
+            continue;
+        if (kindFilter !== undefined && sub.kind !== kindFilter)
+            continue;
+        // A directory INDEX surfaces as a dir entry: its dir path with a trailing
+        // slash, flagged is_dir, so the inventory distinguishes it from a doc.
+        const isDir = isIndexName(sub.name);
+        const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
+        addItem({ name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, isDir, slash: sub.slash });
+    }
+    items.sort((a, b) => {
+        const sr = scopeRank(a.scope) - scopeRank(b.scope);
+        if (sr !== 0)
+            return sr;
+        const kc = a.kind.localeCompare(b.kind);
+        if (kc !== 0)
+            return kc;
+        return a.name.localeCompare(b.name);
+    });
+    return items;
+}
 export const listLeaf = defineLeaf({
     name: 'list',
     description: 'inventory of stored memory documents',
@@ -34,37 +68,7 @@ export const listLeaf = defineLeaf({
         const limitRaw = input['limit'];
         const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
         const cursor = input['cursor'];
-        const seen = new Set(); // "scope/name" → first wins
-        const items = [];
-        const addItem = (item) => {
-            const id = `${item.scope}/${item.name}`;
-            if (seen.has(id))
-                return;
-            seen.add(id);
-            items.push(item);
-        };
-        // Substrate memory docs (project > user > builtin precedence).
-        for (const doc of listAllMemoryDocs(scopeFilter)) {
-            const sub = parseSubstrateDoc(doc);
-            if (sub === null)
-                continue;
-            if (kindFilter !== undefined && sub.kind !== kindFilter)
-                continue;
-            // A directory INDEX surfaces as a dir entry: its dir path with a trailing
-            // slash, flagged is_dir, so the inventory distinguishes it from a doc.
-            const isDir = isIndexName(sub.name);
-            const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
-            addItem({ name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, isDir });
-        }
-        items.sort((a, b) => {
-            const sr = scopeRank(a.scope) - scopeRank(b.scope);
-            if (sr !== 0)
-                return sr;
-            const kc = a.kind.localeCompare(b.kind);
-            if (kc !== 0)
-                return kc;
-            return a.name.localeCompare(b.name);
-        });
+        const items = listMemoryDocs(kindFilter, scopeFilter);
         const keyOf = (d) => `${String(scopeRank(d.scope) + 10).padStart(2, '0')}:${d.kind}:${d.name}`;
         const result = paginate(items, { limit, cursor }, { defaultLimit: 50, maxLimit: 200, keyOf, total: 'count' });
         return {

package/dist/commands/memory/read.d.ts

@@ -1 +1,8 @@
+import { createMemoryDocSnapshot, resolveMemoryDocs } from '../../core/memory-resolver.js';
+export { createMemoryDocSnapshot, resolveMemoryDocs };
+/** Load the body at an already-resolved memory path with the same frontmatter
+ * stripping and in-node path interpolation as `memory read`. Callers that
+ * already have the resolved path (such as slash-command discovery) avoid
+ * re-walking every memory store for each document. */
+export declare function readMemoryDocContent(path: string, includeFrontmatter?: boolean): string;
 export declare const readLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/read.js

@@ -1,12 +1,24 @@
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
-import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { createMemoryDocSnapshot, resolveMemoryDoc, resolveMemoryDocs } from '../../core/memory-resolver.js';
 import { effectiveDocKind } from '../../core/substrate/schema.js';
 import { displayName } from '../../core/substrate/ceiling.js';
 import { interpolateNodePaths } from '../../core/canvas/paths.js';
 import { readText } from '../../core/fs-utils.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
 import { MEMORY_KINDS } from './shared.js';
+export { createMemoryDocSnapshot, resolveMemoryDocs };
+/** Load the body at an already-resolved memory path with the same frontmatter
+ * stripping and in-node path interpolation as `memory read`. Callers that
+ * already have the resolved path (such as slash-command discovery) avoid
+ * re-walking every memory store for each document. */
+export function readMemoryDocContent(path, includeFrontmatter = false) {
+    const raw = readText(path);
+    const content = includeFrontmatter ? raw : parseFrontmatterGeneric(raw).body;
+    const nodeId = process.env['CRTR_NODE_ID'];
+    return nodeId ? interpolateNodePaths(content, nodeId) : content;
+}
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
@@ -51,13 +63,7 @@ export const readLeaf = defineLeaf({
         }
         if (doc !== undefined) {
             const kind = effectiveDocKind(doc);
-            const raw = includeFrontmatter ? readText(doc.path) : doc.body;
-            // In-node reads (CRTR_NODE_ID set) get the literal `$CRTR_CONTEXT_DIR`
-            // token swapped for this node's real absolute path, so agents don't
-            // paste it into the non-expanding Write tool. A human/contributor
-            // reading generically (env unset) keeps the token literal.
-            const nodeId = process.env['CRTR_NODE_ID'];
-            const content = nodeId ? interpolateNodePaths(raw, nodeId) : raw;
+            const content = readMemoryDocContent(doc.path, includeFrontmatter);
             // `[[name]]` doc links are pointers, never transclusion: surface which
             // linked names actually resolve so the reader can follow one when the
             // task needs that depth, without ever auto-loading a linked body.

package/dist/commands/node/bash.d.ts

@@ -0,0 +1 @@
+export declare const nodeBash: import("../../core/command.js").BranchDef;

package/dist/commands/node/bash.js

@@ -0,0 +1,198 @@
+// `crtr node bash` — file-backed background job controls.
+import { existsSync, writeFileSync } from 'node:fs';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { displayMessage } from '../../core/runtime/tmux-chrome.js';
+import { contextDir } from '../../core/canvas/paths.js';
+import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobPaths, formatBashElapsed, jobStartedAtMs, readJobPgid, tailJobLog } from '../../core/bash-jobs.js';
+import { cliClient, getNodeOrNull } from '../api-client.js';
+import { nodeInPane } from '../surface/node/placement.js';
+function resolveBashTarget(input, missingMessage) {
+    const pane = input['pane'] ?? process.env['TMUX_PANE'];
+    let id = input['node'];
+    if (id === undefined || id === '')
+        id = nodeInPane(pane);
+    if (id === undefined || id === '')
+        id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id === '') {
+        throw new InputError({ error: 'no_node', message: missingMessage, next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+    }
+    return { id, pane };
+}
+const nodeBashBackground = defineLeaf({
+    name: 'background',
+    description: 'hand the focused node’s running bash command to its background job system',
+    whenToUse: 'the tmux prefix menu invokes this when a foreground bash command should stop blocking the agent immediately but keep running as a file-backed background job',
+    tier: 'hidden',
+    help: {
+        name: 'node bash background',
+        summary: 'hand every running foreground bash command for one node to its file-backed background job system',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose running bash command to background. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE. The prefix menu passes this for you.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { name: 'backgrounded', type: 'number', required: true, constraint: 'Number of running bash commands handed off.' },
+            { name: 'job_ids', type: 'string[]', required: true, constraint: 'File-backed job ids now running independently of the agent tool call.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Per handed-off job {job_id, elapsed_ms} — the foreground elapsed time in milliseconds at the moment of handoff.' },
+        ],
+        outputKind: 'object',
+        effects: ['Signals every foreground bash command currently running for the node to return from its tool call immediately while its detached supervisor keeps the command running.', 'Each handed-off command retains its log under the node context jobs directory and sends the node an urgent inbox message when it exits, which steers the node mid-turn.'],
+    },
+    run: async (input) => {
+        const { id, pane } = resolveBashTarget(input, 'no node found for the bash handoff');
+        if ((await getNodeOrNull(id)) === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobs = backgroundRunningBashJobs(contextDir(id));
+        const now = Date.now();
+        const elapsed = jobs.map((job) => ({ job_id: job.jobId, elapsed_ms: now - (jobStartedAtMs(job.jobId) ?? now) }));
+        const toast = jobs.length === 0
+            ? 'crtr: no running bash command'
+            : jobs.length === 1
+                ? `crtr: bash handed off · ${formatBashElapsed(elapsed[0].elapsed_ms)}`
+                : `crtr: bash handed off (${jobs.length})`;
+        displayMessage(toast, pane);
+        return { node_id: id, backgrounded: jobs.length, job_ids: jobs.map((job) => job.jobId), jobs: elapsed };
+    },
+    render: (result) => {
+        if (result['backgrounded'] === 0)
+            return `No foreground bash command is running for ${result['node_id']}.`;
+        const jobs = result['jobs'];
+        const oldestElapsedMs = Math.max(...jobs.map((job) => job.elapsed_ms));
+        return `Handed ${result['backgrounded']} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
+    },
+});
+const nodeBashList = defineLeaf({
+    name: 'list',
+    description: 'list a node’s live background bash jobs',
+    whenToUse: 'the Inspector’s jobs section reads this to show what a node handed off to the background',
+    tier: 'hidden',
+    help: {
+        name: 'node bash list',
+        summary: 'read every still-running background bash job owned by one node',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose background jobs to list. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+            { kind: 'flag', name: 'tail', type: 'int', required: false, default: 0, constraint: 'Include this many trailing log lines per job (0 = none).' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Oldest-first {job_id, command, started_at, elapsed_ms, log_path, pgid, log_tail} for every live background job.' },
+        ],
+        outputKind: 'object',
+        effects: ['Reads the node context jobs directory. Changes nothing.'],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job list');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const now = Date.now();
+        const tail = Math.max(0, Math.trunc(Number(input['tail'] ?? 0)));
+        const dir = contextDir(node.node_id);
+        const jobs = activeBackgroundBashJobs(dir).map((job) => ({
+            job_id: job.jobId,
+            command: job.command,
+            started_at: new Date(job.startedAtMs).toISOString(),
+            elapsed_ms: now - job.startedAtMs,
+            log_path: job.logPath,
+            pgid: readJobPgid(dir, job.jobId) ?? null,
+            log_tail: tailJobLog(job.logPath, tail),
+        }));
+        return { node_id: node.node_id, jobs };
+    },
+    render: (result) => {
+        const jobs = result['jobs'];
+        if (jobs.length === 0)
+            return `No background bash jobs for ${result['node_id']}.`;
+        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${job.command.split('\n')[0]}\n  log: ${job.log_path}`).join('\n');
+    },
+});
+/** SIGTERM the job's process group, give it a moment, then SIGKILL. Returns
+ *  false only when the group was already gone at the first signal. */
+function stopJobGroup(pgid) {
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+const nodeBashKill = defineLeaf({
+    name: 'kill',
+    description: 'stop one of a node’s background bash jobs',
+    whenToUse: 'a human watching the Inspector or the attach cockpit’s bash row wants a long-running background job to stop now, or an agent is abandoning work it backgrounded',
+    tier: 'hidden',
+    help: {
+        name: 'node bash kill',
+        summary: 'terminate a background bash job’s process group and tell the owning node it was canceled',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The job that was stopped.' },
+            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when the process group was still alive and received SIGTERM.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Sends SIGTERM (then SIGKILL) to the job’s whole process group, stopping the command and anything it forked.',
+            'Records the job’s exit so it stops showing as live, and sends the owning node an urgent inbox message saying the job was stopped — which steers that node mid-turn.',
+        ],
+    },
+    run: async (input) => {
+        const { id } = resolveBashTarget(input, 'no node found for the bash job');
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        const dir = contextDir(node.node_id);
+        const paths = bashJobPaths(dir, jobId);
+        if (!existsSync(paths.dir)) {
+            throw new InputError({ error: 'not_found', message: `no background job ${jobId} for ${node.node_id}`, next: 'List live jobs with `crtr node bash list`.' });
+        }
+        const pgid = readJobPgid(dir, jobId);
+        if (pgid === undefined) {
+            throw new InputError({
+                error: 'not_stoppable',
+                message: `job ${jobId} recorded no process group`,
+                next: `It started before crtr persisted one. Stop it by hand, then it will disappear from the list. Log: ${paths.jobLog}`,
+            });
+        }
+        const signaled = stopJobGroup(pgid);
+        // The supervisor shares the group it leads, so it usually dies with the
+        // command and never writes job.exit. Record the cancellation ourselves —
+        // that sentinel is what retires the job from every live-jobs read.
+        await new Promise((r) => setTimeout(r, 400));
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        if (!existsSync(paths.jobExit))
+            writeFileSync(paths.jobExit, '143\n');
+        await cliClient().sendMessage(node.node_id, {
+            body: `Background bash job ${jobId} was stopped by the human before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
+            tier: 'urgent',
+        });
+        return { node_id: node.node_id, job_id: jobId, signaled };
+    },
+    render: (result) => `Canceled background bash job ${result['job_id']} for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
+});
+export const nodeBash = defineBranch({
+    name: 'bash',
+    description: 'control file-backed bash jobs owned by a node',
+    whenToUse: 'a running bash command must be handed off, listed, or stopped — the tmux prefix menu backgrounds, the Inspector’s jobs section lists and cancels',
+    tier: 'hidden',
+    help: {
+        name: 'node bash',
+        summary: 'control file-backed bash jobs owned by a node',
+    },
+    children: [nodeBashBackground, nodeBashList, nodeBashKill],
+});

package/dist/commands/node/create.d.ts

@@ -0,0 +1,23 @@
+/** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
+ *  but when the SPAWNER is an orchestrator whose context has already grown past
+ *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
+ *  the child's result. */
+export declare function childFollowUp(spawnerId: string | undefined): Promise<string>;
+/** Validate a `--kind` against the installed personas; throws a listing InputError. */
+export declare function assertKind(kind: string): void;
+/** A live `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
+ *  installed top-level persona kind (project > user > builtin), lazily built so
+ *  it reflects the caller's cwd/project scope. Appended to `node new -h` and
+ *  `node promote -h` so custom kinds appear in help. Soft-fails via the renderer.
+ *
+ *  Keep this block cheap and caller-agnostic: help should not depend on the
+ *  running node's current persona env, which can lag after polymorph. Sub-kinds
+ *  (e.g. `plan/reviewers/security`) are OMITTED here — `KindConfig.availableTo`
+ *  defaults to the sub-kind's own top-level ancestor, and this generic block has
+ *  no single ancestor to check against, so only an explicit `availableTo: ['*']`
+ *  sub-kind (universally available) earns a place in this list. A direct launch
+ *  by full sub-kind string is always valid regardless (visibility-only
+ *  filtering) — discover the roster for a specific kind via
+ *  `crtr sys prompt-review --list --kind <kind>`. */
+export declare function kindsStateBlock(): string;
+export declare const nodeNew: import("../../core/command.js").LeafDef;