@crouton-kit/crouter 0.2.5 → 0.3.1

package/dist/core/command.d.ts

@@ -0,0 +1,36 @@
+import type { RootHelp, BranchHelp, LeafHelp, InputParam } from './help.js';
+export interface LeafDef {
+    kind: 'leaf';
+    name: string;
+    help: LeafHelp;
+    run: (input: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
+}
+export interface BranchDef {
+    kind: 'branch';
+    name: string;
+    help: BranchHelp;
+    children: (LeafDef | BranchDef)[];
+}
+export interface RootDef {
+    kind: 'root';
+    help: RootHelp;
+    subtrees: BranchDef[];
+}
+export declare function defineLeaf(opts: {
+    name: string;
+    help: LeafHelp;
+    run: (input: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
+}): LeafDef;
+export declare function defineBranch(opts: {
+    name: string;
+    help: BranchHelp;
+    children: (LeafDef | BranchDef)[];
+}): BranchDef;
+export declare function defineRoot(opts: {
+    help: RootHelp;
+    subtrees: BranchDef[];
+}): RootDef;
+/** Parse remaining argv tokens against the leaf's InputParam schema.
+ *  Returns a plain object whose keys are camelCase parameter names. */
+export declare function parseArgv(params: InputParam[], tokens: string[]): Promise<Record<string, unknown>>;
+export declare function runCli(root: RootDef, argv: string[]): Promise<void>;

package/dist/core/command.js

@@ -0,0 +1,287 @@
+// Registration kit for the agent-first crtr CLI.
+// Hand-rolled path walker — no commander. Rationale: the spec requires flags
+// and positional args on input (argv model). Commander's abstraction is more
+// complexity than a plain array walk for this interface contract.
+// A plain array walk + a small flag parser is ~120 lines and has no surprising
+// edge cases.
+import { renderRoot, renderBranch, renderLeafArgv } from './help.js';
+import { readStdinRaw, emit, handle } from './io.js';
+import { CrtrError } from './errors.js';
+import { ExitCode } from '../types.js';
+import { readFileSync } from 'node:fs';
+// ---------------------------------------------------------------------------
+// Factory functions
+// ---------------------------------------------------------------------------
+export function defineLeaf(opts) {
+    return {
+        kind: 'leaf',
+        name: opts.name,
+        help: opts.help,
+        run: opts.run,
+    };
+}
+export function defineBranch(opts) {
+    return { kind: 'branch', name: opts.name, help: opts.help, children: opts.children };
+}
+export function defineRoot(opts) {
+    return { kind: 'root', help: opts.help, subtrees: opts.subtrees };
+}
+/** Validate and return child names for an unknown-path error. */
+function childNames(node) {
+    if (node.kind === 'root')
+        return node.subtrees.map((s) => s.name);
+    if (node.kind === 'branch')
+        return node.children.map((c) => c.name);
+    return [];
+}
+/** Walk argv tokens to the deepest matched node.
+ *  Returns { node, remaining } where remaining are unconsumed tokens.
+ *  -h / --help tokens are NOT consumed here — the caller checks for them. */
+function walk(root, tokens) {
+    let current = root;
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        // Stop consuming on -h / --help — leave them for caller to detect
+        if (token === '-h' || token === '--help')
+            break;
+        if (current.kind === 'root') {
+            const nextNode = current.subtrees.find((s) => s.name === token);
+            if (nextNode === undefined)
+                break;
+            current = nextNode;
+            i++;
+        }
+        else if (current.kind === 'branch') {
+            const nextNode = current.children.find((c) => c.name === token);
+            if (nextNode === undefined)
+                break;
+            current = nextNode;
+            i++;
+        }
+        else {
+            // leaf — cannot descend further
+            break;
+        }
+    }
+    return { node: current, remaining: tokens.slice(i) };
+}
+function renderNode(node) {
+    if (node.kind === 'root')
+        return renderRoot(node.help);
+    if (node.kind === 'branch')
+        return renderBranch(node.help);
+    return renderLeafArgv(node.help);
+}
+function helpRequested(remaining) {
+    return remaining.some((t) => t === '-h' || t === '--help');
+}
+/** Build a structured unknown-path error. Names valid children of the deepest
+ *  matched node and names the entry command per the spec. No fuzzy matching. */
+function unknownPathError(node, bad) {
+    const valid = childNames(node);
+    const validStr = valid.length > 0 ? valid.join(', ') : '(none)';
+    const entryCmd = node.kind === 'root'
+        ? 'crtr -h'
+        : node.kind === 'branch'
+            ? `crtr ${node.name} -h`
+            : 'crtr -h';
+    return new CrtrError('unknown_path', `unknown subcommand: ${bad}`, ExitCode.USAGE, {
+        received: bad,
+        next: `Valid children: ${validStr}. Run \`${entryCmd}\` for the full list.`,
+    });
+}
+// ---------------------------------------------------------------------------
+// Argv parser
+// ---------------------------------------------------------------------------
+function parseArgvError(code, message, received, field, next) {
+    return new CrtrError(code, message, ExitCode.USAGE, {
+        received,
+        field,
+        next: next !== undefined ? next : 'Run the command with -h to see the parameter schema.',
+    });
+}
+/** Convert kebab-case flag name to camelCase key. e.g. context-file → contextFile */
+function flagNameToKey(name) {
+    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** Parse remaining argv tokens against the leaf's InputParam schema.
+ *  Returns a plain object whose keys are camelCase parameter names. */
+export async function parseArgv(params, tokens) {
+    const result = {};
+    // Index params by kind for quick lookup
+    const positionalParam = params.find((p) => p.kind === 'positional');
+    const stdinParam = params.find((p) => p.kind === 'stdin');
+    const contextFileParam = params.find((p) => p.kind === 'context-file');
+    const flagParams = params.filter((p) => p.kind === 'flag');
+    const flagsByName = new Map(flagParams.map((f) => [f.name, f]));
+    // Apply defaults for bool flags
+    for (const f of flagParams) {
+        if (f.type === 'bool') {
+            result[flagNameToKey(f.name)] = f.default !== undefined ? f.default : false;
+        }
+        else if (f.default !== undefined) {
+            result[flagNameToKey(f.name)] = f.default;
+        }
+    }
+    let positionalValue;
+    let forcedPositional = false; // true after bare --
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if (token === '--' && !forcedPositional) {
+            forcedPositional = true;
+            i++;
+            continue;
+        }
+        if (!forcedPositional && token.startsWith('--')) {
+            // Flag: --name or --name=value
+            const eqIdx = token.indexOf('=');
+            let flagName;
+            let inlineValue;
+            if (eqIdx !== -1) {
+                flagName = token.slice(2, eqIdx);
+                inlineValue = token.slice(eqIdx + 1);
+            }
+            else {
+                flagName = token.slice(2);
+            }
+            // --context-file is handled specially regardless of declared schema
+            if (flagName === 'context-file') {
+                if (contextFileParam === undefined) {
+                    throw parseArgvError('unknown_flag', `unknown flag: --context-file`, '--context-file', undefined, 'This leaf does not accept --context-file.');
+                }
+                const pathVal = inlineValue !== undefined ? inlineValue : tokens[++i];
+                if (pathVal === undefined) {
+                    throw parseArgvError('missing_parameter', '--context-file requires a PATH argument', '--context-file', 'context-file');
+                }
+                let fileContent;
+                try {
+                    fileContent = readFileSync(pathVal, 'utf8');
+                }
+                catch (err) {
+                    throw parseArgvError('invalid_type', `--context-file: cannot read file: ${pathVal}`, pathVal, 'context-file', 'Provide a readable file path.');
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(fileContent);
+                }
+                catch {
+                    throw parseArgvError('invalid_type', `--context-file: file is not valid JSON: ${pathVal}`, pathVal, 'context-file', 'Ensure the file contains a valid JSON object.');
+                }
+                result[flagNameToKey(contextFileParam.name)] = parsed;
+                i++;
+                continue;
+            }
+            const flagDef = flagsByName.get(flagName);
+            if (flagDef === undefined) {
+                throw parseArgvError('unknown_flag', `unknown flag: --${flagName}`, `--${flagName}`, undefined, 'Use --<flag-name> for declared flags only. Run -h for the schema.');
+            }
+            const key = flagNameToKey(flagName);
+            if (flagDef.type === 'bool') {
+                if (inlineValue !== undefined) {
+                    throw parseArgvError('invalid_type', `boolean flag --${flagName} takes no value`, `--${flagName}=${inlineValue}`, flagName, `Use --${flagName} (presence = true) with no value.`);
+                }
+                result[key] = true;
+                i++;
+                continue;
+            }
+            const rawVal = inlineValue !== undefined ? inlineValue : tokens[++i];
+            if (rawVal === undefined || rawVal.startsWith('--')) {
+                throw parseArgvError('missing_parameter', `--${flagName} requires a value`, `--${flagName}`, flagName);
+            }
+            if (flagDef.type === 'int') {
+                const n = Number(rawVal);
+                if (!Number.isInteger(n)) {
+                    throw parseArgvError('invalid_type', `--${flagName} must be an integer`, rawVal, flagName, `Provide an integer value for --${flagName}.`);
+                }
+                result[key] = n;
+            }
+            else if (flagDef.type === 'enum') {
+                const choices = flagDef.choices;
+                if (choices !== undefined && !choices.includes(rawVal)) {
+                    throw parseArgvError('invalid_type', `--${flagName} must be one of: ${choices.join(', ')}`, rawVal, flagName, `Retry with one of: ${choices.join(', ')}.`);
+                }
+                result[key] = rawVal;
+            }
+            else {
+                // string or path
+                result[key] = rawVal;
+            }
+            i++;
+            continue;
+        }
+        // Positional (or token after --)
+        if (positionalValue !== undefined) {
+            throw parseArgvError('bad_invocation', `unexpected extra positional argument: ${token}`, tokens.join(' '), undefined, 'Use --flag for parameters; only one positional allowed.');
+        }
+        if (positionalParam === undefined) {
+            throw parseArgvError('bad_invocation', `this leaf takes no positional arguments: ${token}`, token, undefined, 'Use --flag for parameters. Run -h for the schema.');
+        }
+        positionalValue = token;
+        i++;
+    }
+    // Assign positional
+    if (positionalValue !== undefined && positionalParam !== undefined) {
+        result[flagNameToKey(positionalParam.name)] = positionalValue;
+    }
+    // Read stdin if declared
+    if (stdinParam !== undefined) {
+        const raw = await readStdinRaw();
+        if (raw.trim() === '' && stdinParam.required) {
+            throw parseArgvError('missing_parameter', `stdin is required for this leaf`, '', stdinParam.name, 'Pipe the required content on stdin.');
+        }
+        result[flagNameToKey(stdinParam.name)] = raw;
+    }
+    // Validate required params
+    for (const p of params) {
+        const key = flagNameToKey(p.kind === 'context-file' ? p.name : p.name);
+        if (p.required && (result[key] === undefined || result[key] === null)) {
+            const display = p.kind === 'positional'
+                ? `positional ${p.name.toUpperCase()}`
+                : p.kind === 'flag'
+                    ? `--${p.name}`
+                    : p.kind === 'context-file'
+                        ? `--context-file`
+                        : 'stdin';
+            throw parseArgvError('missing_parameter', `required parameter is missing: ${display}`, undefined, p.name, `Provide ${display}. Run -h for the schema.`);
+        }
+    }
+    return result;
+}
+export async function runCli(root, argv) {
+    // argv is process.argv — strip node binary + script path
+    const tokens = argv.slice(2);
+    // Bare root invocation or -h at root
+    if (tokens.length === 0 || (tokens.length === 1 && (tokens[0] === '-h' || tokens[0] === '--help'))) {
+        process.stdout.write(renderRoot(root.help) + '\n');
+        process.exit(ExitCode.SUCCESS);
+    }
+    const { node, remaining } = walk(root, tokens);
+    try {
+        // Help anywhere in remaining tokens → print node help and exit
+        if (helpRequested(remaining)) {
+            process.stdout.write(renderNode(node) + '\n');
+            process.exit(ExitCode.SUCCESS);
+        }
+        // Bare branch or bare root (no -h, but no leaf selected) → help surface
+        if (node.kind === 'root' || node.kind === 'branch') {
+            if (remaining.length > 0) {
+                throw unknownPathError(node, remaining[0]);
+            }
+            process.stdout.write(renderNode(node) + '\n');
+            process.exit(ExitCode.SUCCESS);
+        }
+        // Leaf dispatch — argv input model only
+        const params = node.help.params !== undefined ? node.help.params : [];
+        const input = await parseArgv(params, remaining);
+        const result = await node.run(input);
+        if (result !== undefined && result !== null) {
+            emit(result);
+        }
+        // JSONL leaves call emitLine themselves and return void
+    }
+    catch (e) {
+        handle(e);
+    }
+}

package/dist/core/errors.d.ts

@@ -10,3 +10,6 @@ export declare function usage(message: string, details?: Record<string, unknown>
 export declare function ambiguous(message: string, details?: Record<string, unknown>): CrtrError;
 export declare function network(message: string, details?: Record<string, unknown>): CrtrError;
 export declare function general(message: string, details?: Record<string, unknown>): CrtrError;
+/** Thrown by stub handlers for leaves not yet wired in P3+.
+ *  code='not_implemented', exitCode=GENERAL, next names the node. */
+export declare function notImplemented(node: string): CrtrError;

package/dist/core/errors.js

@@ -26,3 +26,8 @@ export function network(message, details) {
 export function general(message, details) {
     return new CrtrError('error', message, ExitCode.GENERAL, details);
 }
+/** Thrown by stub handlers for leaves not yet wired in P3+.
+ *  code='not_implemented', exitCode=GENERAL, next names the node. */
+export function notImplemented(node) {
+    return new CrtrError('not_implemented', `${node} is not yet implemented.`, ExitCode.GENERAL, { next: 'This leaf is not yet wired.' });
+}

package/dist/core/fs-utils.d.ts

@@ -4,6 +4,7 @@ export declare function readJson<T = unknown>(path: string): T;
 export declare function readJsonIfExists<T = unknown>(path: string): T | null;
 export declare function readTextIfExists(path: string): string | null;
 export declare function readText(path: string): string;
+export declare function writeText(path: string, content: string): void;
 export declare function isDir(path: string): boolean;
 export declare function isSymlink(path: string): boolean;
 export declare function pathExists(path: string): boolean;

package/dist/core/fs-utils.js

@@ -24,6 +24,10 @@ export function readTextIfExists(path) {
 export function readText(path) {
     return readFileSync(path, 'utf8');
 }
+export function writeText(path, content) {
+    ensureDir(dirname(path));
+    writeFileSync(path, content, 'utf8');
+}
 export function isDir(path) {
     try {
         return statSync(path).isDirectory();

package/dist/core/help.d.ts

@@ -0,0 +1,98 @@
+export interface Field {
+    name: string;
+    type: string;
+    required: boolean;
+    /** Inline semantic constraint — bounds, enum, "must reference an active plan",
+     *  token caps. Lives here, never in a separate Preconditions section. */
+    constraint: string;
+}
+/** Positional argument — at most one per leaf. */
+export interface PositionalParam {
+    kind: 'positional';
+    name: string;
+    /** Display hint only; always parsed as string. */
+    type?: 'string' | 'path';
+    required: boolean;
+    constraint: string;
+}
+/** Long-form flag (`--name`). */
+export interface FlagParam {
+    kind: 'flag';
+    name: string;
+    /** 'bool' flags take no value — presence = true. */
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum';
+    /** Required only when type is 'enum'. */
+    choices?: string[];
+    required: boolean;
+    constraint: string;
+    default?: string | number | boolean;
+    /** When true, the flag may appear multiple times; values accumulate into an
+     *  array. TODO: no current leaf needs this — implement when first leaf migrates. */
+    repeatable?: boolean;
+}
+/** Raw stdin content blob (piped text, not parsed as JSON). */
+export interface StdinParam {
+    kind: 'stdin';
+    name: string;
+    required: boolean;
+    constraint: string;
+}
+/** --context-file PATH: reads and JSON-parses the file at PATH. */
+export interface ContextFileParam {
+    kind: 'context-file';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Optional description of the expected JSON shape. */
+    shape?: string;
+}
+export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+export interface RootHelp {
+    tagline: string;
+    /** Vocabulary block — rendered before subtrees. */
+    concepts: {
+        name: string;
+        desc: string;
+    }[];
+    subtrees: {
+        name: string;
+        desc: string;
+        useWhen: string;
+    }[];
+    globals: {
+        name: string;
+        desc: string;
+    }[];
+}
+export interface BranchHelp {
+    name: string;
+    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. */
+    dynamicState?: () => string | null;
+    children: {
+        name: string;
+        desc: string;
+        useWhen: string;
+    }[];
+}
+export interface LeafHelp {
+    name: string;
+    summary: string;
+    /** Optional long-form workflow prose rendered immediately after the summary
+     *  line. Only plan new / spec new carry this; it precedes the schema. */
+    guide?: string;
+    params?: InputParam[];
+    /** Note appended when there is no input (replaces the Input block). */
+    inputNote?: string;
+    output: Field[];
+    outputKind: 'object' | 'jsonl';
+    /** Every persistent change the command makes to the world. For read-only
+     *  leaves use exactly: ["None. Read-only."] */
+    effects: 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

@@ -0,0 +1,163 @@
+// Descriptor types and renderers for the -h layer of the crtr CLI.
+// Pure functions — no side effects, no commander, no process.exit.
+// Rendering matches reference.md shapes exactly:
+//   root L11-32, branch L43-58, leaf L65-189.
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Return the longest string length in an array of names. */
+function maxLen(names) {
+    let max = 0;
+    for (const n of names) {
+        if (n.length > max)
+            max = n.length;
+    }
+    return max;
+}
+/** Pad a string to the given width with trailing spaces. */
+function pad(s, width) {
+    return s + ' '.repeat(Math.max(0, width - s.length));
+}
+// ---------------------------------------------------------------------------
+// renderRoot
+// ---------------------------------------------------------------------------
+const IO_CONTRACT = 'I/O contract: flags and positional args on input, JSON on stdout (JSONL for streams).\n' +
+    'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h.';
+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}`);
+    }
+    lines.push('');
+    // Globals block
+    lines.push('Globals');
+    const gNameW = maxLen(h.globals.map((g) => g.name));
+    for (const g of h.globals) {
+        lines.push(`  ${pad(g.name, gNameW)}  ${g.desc}`);
+    }
+    lines.push('');
+    lines.push(IO_CONTRACT);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// renderBranch
+// ---------------------------------------------------------------------------
+export function renderBranch(h) {
+    const lines = [];
+    lines.push(`${h.name}: ${h.summary}.`);
+    if (h.model !== undefined) {
+        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));
+    const descW = maxLen(h.children.map((c) => c.desc));
+    for (const c of h.children) {
+        lines.push(`  ${pad(c.name, nameW)}  ${pad(c.desc, descW)}  | use when ${c.useWhen}`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// renderLeafArgv
+// ---------------------------------------------------------------------------
+/** Build the display label for a param entry (left column). */
+function paramLabel(p) {
+    if (p.kind === 'positional')
+        return p.name.toUpperCase();
+    if (p.kind === 'stdin')
+        return 'stdin';
+    if (p.kind === 'context-file')
+        return '--context-file PATH';
+    // flag
+    const f = p;
+    if (f.type === 'bool')
+        return `--${f.name}`;
+    return `--${f.name} ${f.name.toUpperCase().replace(/-/g, '_')}`;
+}
+/** Build the description line for a param entry (right column). */
+function paramDesc(p) {
+    const req = p.required ? 'required' : 'optional';
+    if (p.kind === 'positional')
+        return `positional, ${req}. ${p.constraint}`;
+    if (p.kind === 'stdin')
+        return `${req}. ${p.constraint}`;
+    if (p.kind === 'context-file') {
+        const shape = p.shape !== undefined
+            ? ` Shape: ${p.shape}`
+            : '';
+        return `${req}. Path to a JSON file.${shape} ${p.constraint}`.trim();
+    }
+    // flag
+    const f = p;
+    if (f.type === 'bool')
+        return `optional boolean. Presence means true. ${f.constraint}`.trim();
+    const dflt = f.default !== undefined ? ` Default: ${String(f.default)}.` : '';
+    const choices = f.type === 'enum' && f.choices !== undefined
+        ? ` One of: ${f.choices.join(', ')}.`
+        : '';
+    return `${f.type}, ${req}.${choices}${dflt} ${f.constraint}`.trim();
+}
+export function renderLeafArgv(h) {
+    const lines = [];
+    lines.push(`${h.name}: ${h.summary}.`);
+    if (h.guide !== undefined) {
+        lines.push('');
+        lines.push(h.guide);
+    }
+    lines.push('');
+    const params = h.params ?? [];
+    if (params.length > 0) {
+        lines.push('Input');
+        const labels = params.map(paramLabel);
+        const colW = maxLen(labels);
+        for (let i = 0; i < params.length; i++) {
+            lines.push(`  ${pad(labels[i], colW)}  ${paramDesc(params[i])}`);
+        }
+    }
+    else {
+        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);
+    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}`);
+    }
+    lines.push('');
+    lines.push('Effects');
+    for (const e of h.effects) {
+        lines.push(`  ${e}`);
+    }
+    return lines.join('\n');
+}

package/dist/core/io.d.ts

@@ -0,0 +1,29 @@
+import { CrtrError } from './errors.js';
+import { type ExitCodeValue } from '../types.js';
+/** Structured error payload. `error` is a stable code the agent branches on;
+ *  `next` is the recovery road sign. */
+export interface ErrorPayload {
+    error: string;
+    message: string;
+    received?: unknown;
+    field?: string;
+    next: string;
+}
+/** A command-level failure: surfaces as the JSON response on stdout. */
+export declare class InputError extends CrtrError {
+    payload: ErrorPayload;
+    constructor(payload: ErrorPayload, exitCode?: ExitCodeValue);
+}
+/** 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. */
+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;
+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
+ *  contract. Runtime/internal failures go to stderr as `{error:"internal"}` —
+ *  raw traces never reach the agent. Exits non-zero either way. */
+export declare function handle(e: unknown): never;