@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/feed/feed.js

@@ -0,0 +1,116 @@
+// Push engine for the pi-native canvas runtime.
+//
+// `push(nodeId, opts)` writes a report to the node's reports/ directory, then
+// fans out a lightweight inbox pointer to every subscriber. The inbox entry
+// carries the report path (ref), not the body — subscribers dereference on
+// demand.
+//
+// Compact timestamp format: 20260602T184512 (UTC, no separators) chosen for
+// file-system friendliness and lexicographic sort alignment.
+import { writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { reportsDir, subscribersOf, setStatus, updateNode, } from '../canvas/index.js';
+import { appendInbox } from './inbox.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Format a Date as `YYYYMMDDTHHmmss` (UTC, no separators). */
+function compactTs(d = new Date()) {
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    return (String(d.getUTCFullYear()) +
+        pad(d.getUTCMonth() + 1) +
+        pad(d.getUTCDate()) +
+        'T' +
+        pad(d.getUTCHours()) +
+        pad(d.getUTCMinutes()) +
+        pad(d.getUTCSeconds()));
+}
+/**
+ * Write a report file atomically (tmp + rename).
+ * Returns the final absolute path.
+ */
+function writeReport(nodeId, kind, ts, body) {
+    const dir = reportsDir(nodeId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const fileName = `${ts}-${kind}.md`;
+    const finalPath = join(dir, fileName);
+    const tmpPath = `${finalPath}.tmp`;
+    const isoTs = new Date().toISOString();
+    // YAML frontmatter: minimal, machine-readable, no freeform content in it.
+    const frontmatter = `---\nnode: ${nodeId}\nkind: ${kind}\nts: ${isoTs}\n---\n`;
+    writeFileSync(tmpPath, frontmatter + body, 'utf8');
+    renameSync(tmpPath, finalPath);
+    return finalPath;
+}
+/**
+ * Extract the first line of a string and truncate to `maxLen` chars.
+ * Used to populate the inbox entry's `label` field (~80 chars).
+ */
+function firstLine(text, maxLen = 80) {
+    const line = text.split('\n')[0] ?? '';
+    return line.length > maxLen ? line.slice(0, maxLen - 1) + '…' : line;
+}
+/** Map a PushKind to the appropriate inbox delivery tier. */
+function tierFor(kind) {
+    return kind === 'urgent' ? 'urgent' : 'normal';
+}
+// ---------------------------------------------------------------------------
+// Core push
+// ---------------------------------------------------------------------------
+/**
+ * Push a report from `nodeId` and fan it out as inbox pointers to all
+ * current subscribers.
+ *
+ * Steps:
+ *   (a) Write nodes/<nodeId>/reports/<ts>-<kind>.md (YAML front + body).
+ *   (b) For each active/passive subscriber, append a pointer to their inbox.
+ *   (c) If kind === 'final', mark the node done.
+ */
+export async function push(nodeId, opts) {
+    const { kind, body } = opts;
+    const from = opts.from ?? nodeId;
+    const now = new Date();
+    const ts = compactTs(now);
+    // (a) Write the report.
+    const reportPath = writeReport(nodeId, kind, ts, body);
+    // (b) Fan out inbox pointers to every subscriber (active and passive both
+    //     receive the pointer; the daemon decides whether to wake active ones).
+    const subscribers = subscribersOf(nodeId);
+    const deliveredTo = [];
+    const label = firstLine(body);
+    for (const sub of subscribers) {
+        appendInbox(sub.node_id, {
+            from,
+            tier: tierFor(kind),
+            kind,
+            ref: reportPath,
+            label,
+        });
+        deliveredTo.push(sub.node_id);
+    }
+    // (c) Finalise node when kind === 'final'.
+    if (kind === 'final') {
+        setStatus(nodeId, 'done');
+        updateNode(nodeId, { intent: 'done' });
+    }
+    return { reportPath, deliveredTo };
+}
+// ---------------------------------------------------------------------------
+// Convenience wrappers
+// ---------------------------------------------------------------------------
+/** Emit a routine progress update from `nodeId`. */
+export async function pushUpdate(nodeId, body, opts) {
+    return push(nodeId, { kind: 'update', body, ...opts });
+}
+/** Emit an urgent alert from `nodeId` (inbox tier: urgent). */
+export async function pushUrgent(nodeId, body, opts) {
+    return push(nodeId, { kind: 'urgent', body, ...opts });
+}
+/**
+ * Emit the final report from `nodeId` (inbox tier: normal, kind: final).
+ * Also transitions the node to status=done / intent=done.
+ */
+export async function pushFinal(nodeId, body, opts) {
+    return push(nodeId, { kind: 'final', body, ...opts });
+}

package/dist/core/feed/inbox.d.ts

@@ -0,0 +1,50 @@
+export type InboxTier = 'critical' | 'urgent' | 'normal' | 'deferred';
+export type InboxKind = 'update' | 'urgent' | 'final' | 'message' | 'completed';
+/** A single inbox entry — a pointer, not a copy of the content. */
+export interface InboxEntry {
+    /** ISO 8601 timestamp of delivery. */
+    ts: string;
+    /** Node id of the sender, or null for system-generated entries. */
+    from: string | null;
+    /** Priority band for the receiver's attention. */
+    tier: InboxTier;
+    /** Semantic kind of the push event. */
+    kind: InboxKind;
+    /** Absolute path to the report file, when this entry is a push pointer. */
+    ref?: string;
+    /** First ~80 chars of the body's first line — enough to decide if it matters. */
+    label: string;
+    /** Arbitrary structured payload for non-push message entries. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Atomically append one inbox entry to `nodes/<nodeId>/inbox.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export declare function appendInbox(nodeId: string, entry: Omit<InboxEntry, 'ts'>): InboxEntry;
+/**
+ * Return all inbox entries strictly after `cursorIso`.
+ * When `cursorIso` is undefined, returns every entry in the file.
+ */
+export declare function readInboxSince(nodeId: string, cursorIso?: string): InboxEntry[];
+/**
+ * Read the persisted cursor ISO for a node's inbox.
+ * Returns undefined if no cursor file exists yet.
+ */
+export declare function readCursor(nodeId: string): string | undefined;
+/**
+ * Persist a new cursor ISO for a node's inbox (atomic tmp+rename).
+ */
+export declare function writeCursor(nodeId: string, iso: string): void;
+/**
+ * Render many unread inbox pointers into one compact digest string.
+ *
+ * Format (per sender group):
+ *   From <sender> — <N> update(s):
+ *     [<kind>] <label>  (ref: <path>)
+ *     …
+ *
+ * A header line announces the total count and instructs the receiver to
+ * dereference only what matters.
+ */
+export declare function coalesce(entries: InboxEntry[]): string;

package/dist/core/feed/inbox.js

@@ -0,0 +1,124 @@
+// Per-node inbox.jsonl primitive for the pi-native canvas runtime.
+//
+// An inbox entry is a lightweight POINTER (~30 tokens), never content.
+// The report body lives in nodes/<id>/reports/; the inbox line carries only
+// enough to find it and decide whether to dereference.
+//
+// Layout:
+//   nodes/<id>/inbox.jsonl          — one JSON line per entry, append-only
+//   nodes/<id>/inbox.jsonl.cursor   — ISO 8601 of last-read entry (sidecar)
+import { appendFileSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { inboxPath } from '../canvas/index.js';
+// ---------------------------------------------------------------------------
+// Cursor sidecar path
+// ---------------------------------------------------------------------------
+function cursorPath(nodeId) {
+    return `${inboxPath(nodeId)}.cursor`;
+}
+// ---------------------------------------------------------------------------
+// Append
+// ---------------------------------------------------------------------------
+/**
+ * Atomically append one inbox entry to `nodes/<nodeId>/inbox.jsonl`.
+ * Fills `ts` (current ISO time). Returns the completed entry.
+ */
+export function appendInbox(nodeId, entry) {
+    const full = { ts: new Date().toISOString(), ...entry };
+    const line = JSON.stringify(full) + '\n';
+    // Ensure the parent directory exists (inbox.jsonl lives directly under the
+    // node dir, which ensureNodeDirs creates — but guard anyway for callers that
+    // haven't yet scaffolded the node).
+    const dir = dirname(inboxPath(nodeId));
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // appendFileSync is atomic within a single process (a single write(2) call for
+    // a short line is atomic on POSIX). For multi-process safety we rely on the
+    // OS-level append guarantee (O_APPEND) which Node honours via 'a' flag.
+    appendFileSync(inboxPath(nodeId), line, { encoding: 'utf8', flag: 'a' });
+    return full;
+}
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+/**
+ * Return all inbox entries strictly after `cursorIso`.
+ * When `cursorIso` is undefined, returns every entry in the file.
+ */
+export function readInboxSince(nodeId, cursorIso) {
+    const p = inboxPath(nodeId);
+    if (!existsSync(p))
+        return [];
+    const raw = readFileSync(p, 'utf8');
+    const entries = raw
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => JSON.parse(l));
+    if (cursorIso === undefined)
+        return entries;
+    // Entries are appended in chronological order; filter to those strictly
+    // after the cursor. We compare ISO strings lexicographically (valid for UTC).
+    return entries.filter((e) => e.ts > cursorIso);
+}
+// ---------------------------------------------------------------------------
+// Cursor persistence
+// ---------------------------------------------------------------------------
+/**
+ * Read the persisted cursor ISO for a node's inbox.
+ * Returns undefined if no cursor file exists yet.
+ */
+export function readCursor(nodeId) {
+    const p = cursorPath(nodeId);
+    if (!existsSync(p))
+        return undefined;
+    const val = readFileSync(p, 'utf8').trim();
+    return val !== '' ? val : undefined;
+}
+/**
+ * Persist a new cursor ISO for a node's inbox (atomic tmp+rename).
+ */
+export function writeCursor(nodeId, iso) {
+    const p = cursorPath(nodeId);
+    const tmp = `${p}.tmp`;
+    const dir = dirname(p);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(tmp, iso, 'utf8');
+    renameSync(tmp, p);
+}
+// ---------------------------------------------------------------------------
+// Coalesce
+// ---------------------------------------------------------------------------
+/**
+ * Render many unread inbox pointers into one compact digest string.
+ *
+ * Format (per sender group):
+ *   From <sender> — <N> update(s):
+ *     [<kind>] <label>  (ref: <path>)
+ *     …
+ *
+ * A header line announces the total count and instructs the receiver to
+ * dereference only what matters.
+ */
+export function coalesce(entries) {
+    if (entries.length === 0)
+        return '(inbox empty)';
+    const header = `${entries.length} update${entries.length === 1 ? '' : 's'} since last read — dereference what matters.\n`;
+    // Group by `from` (null → 'system').
+    const groups = new Map();
+    for (const e of entries) {
+        const key = e.from ?? 'system';
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(e);
+    }
+    const sections = [];
+    for (const [sender, items] of groups) {
+        const lines = items.map((e) => {
+            const refPart = e.ref !== undefined ? `  (ref: ${e.ref})` : '';
+            return `  [${e.kind}] ${e.label}${refPart}`;
+        });
+        sections.push(`From ${sender} — ${items.length} update${items.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
+    }
+    return header + sections.join('\n\n');
+}

package/dist/core/frontmatter.d.ts

@@ -5,4 +5,14 @@ export interface ParsedFrontmatter {
     raw: string;
 }
 export declare function parseFrontmatter(source: string): ParsedFrontmatter;
+export interface ParsedFrontmatterGeneric {
+    /** Raw, uncoerced key/value record from the YAML block (null when absent). */
+    data: Record<string, unknown> | null;
+    body: string;
+    raw: string;
+}
+/** Like parseFrontmatter but returns the raw key/value record instead of
+ *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
+ *  fields skills don't declare, such as `tools` and `model`. */
+export declare function parseFrontmatterGeneric(source: string): ParsedFrontmatterGeneric;
 export declare function serializeFrontmatter(data: SkillFrontmatter): string;

package/dist/core/frontmatter.js

@@ -7,9 +7,30 @@ export function parseFrontmatter(source) {
     }
     const raw = match[1];
     const body = source.slice(match[0].length);
-    return { data: parseSimpleYaml(raw), body, raw };
+    return { data: toSkillFrontmatter(parseYamlRecord(raw)), body, raw };
 }
-function parseSimpleYaml(yaml) {
+/** Like parseFrontmatter but returns the raw key/value record instead of
+ *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
+ *  fields skills don't declare, such as `tools` and `model`. */
+export function parseFrontmatterGeneric(source) {
+    const match = source.match(FRONTMATTER_RE);
+    if (!match) {
+        return { data: null, body: source, raw: '' };
+    }
+    const raw = match[1];
+    const body = source.slice(match[0].length);
+    return { data: parseYamlRecord(raw), body, raw };
+}
+function toSkillFrontmatter(out) {
+    const fm = {
+        name: typeof out.name === 'string' ? out.name : '',
+        description: typeof out.description === 'string' ? out.description : undefined,
+        keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
+        type: isSkillType(out.type) ? out.type : undefined,
+    };
+    return fm;
+}
+function parseYamlRecord(yaml) {
     const lines = yaml.split(/\r?\n/);
     const out = {};
     let i = 0;
@@ -123,13 +144,7 @@ function parseSimpleYaml(yaml) {
         out[key] = stripQuotes(rest);
         i++;
     }
-    const fm = {
-        name: typeof out.name === 'string' ? out.name : '',
-        description: typeof out.description === 'string' ? out.description : undefined,
-        keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
-        type: isSkillType(out.type) ? out.type : undefined,
-    };
-    return fm;
+    return out;
 }
 function stripQuotes(s) {
     if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {

package/dist/core/help.d.ts

@@ -47,17 +47,40 @@ export interface ContextFileParam {
     shape?: string;
 }
 export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+/** A subtree's self-description at the parent (root) level. Each subtree owns
+ *  the content that represents it one level up: its vocabulary line, its
+ *  selection rubric, and any bounded block it contributes to the parent's -h.
+ *  defineRoot assembles the root help from these — root never hardcodes a
+ *  subtree's representation. See cli-design "Each node owns its parent-level
+ *  representation". */
+export interface RootEntry {
+    /** One-line vocabulary desc — what this subtree is. Rendered first in the
+     *  subtree's <name> block at root. */
+    concept: string;
+    /** Operations summary (verb list). Carried for completeness; the root block
+     *  leads with concept + rubric, so this is available but not rendered. */
+    desc: string;
+    /** The selection rubric — `use when X` in the subtree's <name> block. */
+    useWhen: string;
+    /** Optional bounded block this subtree contributes to its <name> block at
+     *  root. Returns a complete self-named state element (build it with
+     *  stateBlock), e.g. `<skills count="42">…</skills>`. Aggregate, never an
+     *  unbounded enumeration on a cold path. Soft-fails to omission on
+     *  null/throw. */
+    dynamicState?: () => string | null;
+}
 export interface RootHelp {
     tagline: string;
-    /** Vocabulary block — rendered before subtrees. */
-    concepts: {
-        name: string;
-        desc: string;
-    }[];
-    subtrees: {
+    /** One entry per listed subtree. Each renders as its own <name> XML block at
+     *  root, carrying the subtree's concept, selection rubric, and any nested
+     *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
+     *  root hardcodes none of it. */
+    commands: {
         name: string;
+        concept: string;
         desc: string;
         useWhen: string;
+        dynamicState?: () => string | null;
     }[];
     globals: {
         name: string;
@@ -69,8 +92,9 @@ export interface BranchHelp {
     summary: string;
     /** Local lifecycle/model line that extends the parent definition. */
     model?: string;
-    /** Bounded runtime aggregate, e.g. "Current: 2 draft, 1 active".
-     *  Renderer soft-fails to omission if this returns null or throws. */
+    /** Bounded runtime aggregate as a complete self-named state element (build
+     *  it with stateBlock), e.g. `<skills count="42">…</skills>`. Renderer
+     *  soft-fails to omission if this returns null or throws. */
     dynamicState?: () => string | null;
     children: {
         name: string;
@@ -93,6 +117,13 @@ export interface LeafHelp {
      *  leaves use exactly: ["None. Read-only."] */
     effects: string[];
 }
+/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
+ *  subtree that owns the state authors it through this, so the tag name and any
+ *  scalar metadata (e.g. a count) travel with the data and render identically
+ *  at every level the block appears. The tag name carries the label, so the
+ *  body never repeats it. Attribute values are controlled (counts, short
+ *  tokens) and not escaped. */
+export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
 export declare function renderRoot(h: RootHelp): string;
 export declare function renderBranch(h: BranchHelp): string;
 export declare function renderLeafArgv(h: LeafHelp): string;

package/dist/core/help.js

@@ -5,6 +5,30 @@
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
+/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
+ *  subtree that owns the state authors it through this, so the tag name and any
+ *  scalar metadata (e.g. a count) travel with the data and render identically
+ *  at every level the block appears. The tag name carries the label, so the
+ *  body never repeats it. Attribute values are controlled (counts, short
+ *  tokens) and not escaped. */
+export function stateBlock(tag, attrs, body) {
+    const a = Object.entries(attrs)
+        .map(([k, v]) => ` ${k}="${v}"`)
+        .join('');
+    return `<${tag}${a}>\n${body}\n</${tag}>`;
+}
+/** Evaluate a dynamicState hook, soft-failing to null on throw or empty. */
+function evalDynamic(fn) {
+    if (fn === undefined)
+        return null;
+    try {
+        const s = fn();
+        return s !== null && s !== '' ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Return the longest string length in an array of names. */
 function maxLen(names) {
     let max = 0;
@@ -21,29 +45,41 @@ function pad(s, width) {
 // ---------------------------------------------------------------------------
 // renderRoot
 // ---------------------------------------------------------------------------
-const IO_CONTRACT = 'I/O contract: flags and positional args on input, JSON on stdout (JSONL for streams).\n' +
+const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is agent-ready markdown/XML you\n' +
+    'act on directly — read it as a continuation of your prompt, don\'t parse it as data.\n' +
     'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h.';
+// Behavioral instruction (not a schema) — engrained in the appended system
+// prompt so the model treats unfamiliar capabilities as a cue to discover the
+// contract, never to guess. Lives in the root guide, outside any leaf -h.
+const CAPABILITY_DISCOVERY = "If the user mentions or implies a crtr capability you don't fully understand, " +
+    'do not guess or assume it is unsupported — run `-h` on the relevant command ' +
+    '(append it anywhere along the path) to read the contract before acting.';
 export function renderRoot(h) {
     const lines = [];
     lines.push(`${h.tagline}`);
     lines.push('');
-    // Concepts block
-    lines.push('Concepts');
-    const cNameW = maxLen(h.concepts.map((c) => c.name));
-    for (const c of h.concepts) {
-        lines.push(`  ${pad(c.name, cNameW)}  ${c.desc}`);
-    }
-    lines.push('');
-    // Subtrees block
-    lines.push('Subtrees');
-    const sNameW = maxLen(h.subtrees.map((s) => s.name));
-    // Align desc column so "| use when X" starts at a consistent offset
-    const sDescW = maxLen(h.subtrees.map((s) => s.desc));
-    for (const s of h.subtrees) {
-        lines.push(`  ${pad(s.name, sNameW)}  ${pad(s.desc, sDescW)}  | use when ${s.useWhen}`);
+    // Each subtree is one <command name="…"> block. The uniform wrapper states
+    // "this is a command you invoke as `crtr <name>`" — so the model reads them
+    // by one rule, and a nested state element (which is never a <command>) can't
+    // be mistaken for a sibling command. Inside: the concept (what it is), the
+    // selection rubric (when to pick it), then any self-named state element
+    // grouped with the command it belongs to. Once injected into a system prompt,
+    // each block reads as one self-contained concern domain. Header (tagline) and
+    // footer (Globals + I/O contract + capability-discovery rule) are the only
+    // non-command areas. Two levels of nesting: <command> → <state>.
+    for (const c of h.commands) {
+        lines.push(`<command name="${c.name}">`);
+        lines.push(c.concept);
+        lines.push(`use when ${c.useWhen}`);
+        // dynamicState returns a complete self-named element (e.g.
+        // <skills count="42">…</skills>) — emit it as-is, nested in the command.
+        const state = evalDynamic(c.dynamicState);
+        if (state !== null)
+            lines.push(state);
+        lines.push('</command>');
+        lines.push('');
     }
-    lines.push('');
-    // Globals block
+    // Globals block (footer)
     lines.push('Globals');
     const gNameW = maxLen(h.globals.map((g) => g.name));
     for (const g of h.globals) {
@@ -51,6 +87,8 @@ export function renderRoot(h) {
     }
     lines.push('');
     lines.push(IO_CONTRACT);
+    lines.push('');
+    lines.push(CAPABILITY_DISCOVERY);
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------
@@ -59,25 +97,20 @@ export function renderRoot(h) {
 export function renderBranch(h) {
     const lines = [];
     lines.push(`${h.name}: ${h.summary}.`);
+    // Dynamic content leads — the live aggregate (e.g. the <skills> catalog)
+    // renders right after the name, before the hardcoded model prose, so current
+    // state is read first. The subtree authors the whole element, so the same
+    // self-named block appears identically at root and at `skill -h`.
+    const branchState = evalDynamic(h.dynamicState);
+    if (branchState !== null) {
+        // dynamicState returns a complete self-named element — emit as-is.
+        lines.push('');
+        lines.push(branchState);
+    }
     if (h.model !== undefined) {
+        lines.push('');
         lines.push(h.model);
     }
-    // Dynamic state — soft-fail to omission. Rendered as its own block,
-    // blank-line separated from the summary, so a multi-line runtime
-    // aggregate (e.g. the loaded-skills catalog) reads cleanly.
-    if (h.dynamicState !== undefined) {
-        let state = null;
-        try {
-            state = h.dynamicState();
-        }
-        catch {
-            // soft-fail: omit the block
-        }
-        if (state !== null && state !== '') {
-            lines.push('');
-            lines.push(state);
-        }
-    }
     lines.push('');
     lines.push('Branches');
     const nameW = maxLen(h.children.map((c) => c.name));
@@ -148,8 +181,9 @@ export function renderLeafArgv(h) {
         lines.push(h.inputNote !== undefined ? h.inputNote : 'No input parameters.');
     }
     lines.push('');
-    const outputLabel = h.outputKind === 'jsonl' ? 'Output (stdout, JSONL)' : 'Output (stdout, JSON)';
-    lines.push(outputLabel);
+    // The result is rendered as instruction-shaped XML+markdown; these fields are
+    // the information it carries, in order, not a literal JSON shape.
+    lines.push('Output (fields carried in the rendered result)');
     const outNameW = maxLen(h.output.map((f) => f.name));
     for (const f of h.output) {
         lines.push(`  ${pad(f.name, outNameW)}  ${f.type}. ${f.constraint}`);

package/dist/core/io.d.ts

@@ -1,5 +1,9 @@
 import { CrtrError } from './errors.js';
 import { type ExitCodeValue } from '../types.js';
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export declare function setJsonOutput(v: boolean): void;
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export declare function isJsonOutput(): boolean;
 /** Structured error payload. `error` is a stable code the agent branches on;
  *  `next` is the recovery road sign. */
 export interface ErrorPayload {
@@ -17,10 +21,20 @@ export declare class InputError extends CrtrError {
 /** Read raw stdin to EOF. Returns empty string when stdin is a TTY (no pipe).
  *  Called by the argv parser for leaves declaring a `stdin` parameter. */
 export declare function readStdinRaw(): Promise<string>;
-/** Single-shot response: one JSON object. The whole response is one value. */
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
 export declare function emit(obj: Record<string, unknown>): void;
 /** One JSONL record. Call per event in a stream; partial reads stay parseable. */
 export declare function emitLine(obj: Record<string, unknown>): void;
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export declare function writeStdout(s: string): Promise<boolean>;
 export declare function diag(message: string): void;
 /** Terminal error handler. Command-level failures (bad input, not-found,
  *  ambiguous) surface as the JSON response on stdout so the caller parses one