@itookit/dsht 0.3.7 → 0.5.1

package/dist/session-title.d.ts

@@ -0,0 +1,9 @@
+/** Read a session summary's display title.
+ *
+ * Host rows carry their title inside a projection, and both the domain (matching a target by name)
+ * and the UI (labelling a row) need the same reading, so it lives in its own leaf rather than in
+ * either layer.
+ */
+import { type ObjectValue } from './json.ts';
+/** Resolve the host's title projection, falling back to the session ID. */
+export declare function sessionLabel(session: ObjectValue): string;

package/dist/session-title.js

@@ -0,0 +1,21 @@
+/** Read a session summary's display title.
+ *
+ * Host rows carry their title inside a projection, and both the domain (matching a target by name)
+ * and the UI (labelling a row) need the same reading, so it lives in its own leaf rather than in
+ * either layer.
+ */
+import { string } from "./json.js";
+import { safeText } from "./text.js";
+/** Resolve the host's title projection, falling back to the session ID. */
+export function sessionLabel(session) {
+    const projections = session.projections;
+    if (projections && typeof projections === 'object' && !Array.isArray(projections)) {
+        const values = projections.values;
+        const title = values && typeof values === 'object' && !Array.isArray(values) ? values.title : undefined;
+        if (typeof title === 'string' && safeText(title).trim())
+            return safeText(title).trim();
+        if (title && typeof title === 'object' && !Array.isArray(title) && typeof title.title === 'string' && safeText(title.title).trim())
+            return safeText(title.title).trim();
+    }
+    return string(session.sessionId);
+}

package/dist/shell/controller.d.ts

@@ -0,0 +1,97 @@
+/** Readable id of one `!` run's own output, so its transcript bar and its source entry agree. */
+export declare function localSourceId(id: number): string;
+/** One local command and the output retained for it.
+ *
+ * A block is either a `!` process (`shell`) or a client command echoed so its bar can be read and
+ * clicked (`note`). A note runs nothing; it carries the readable source its bar opens, which the
+ * application links once the thing it announced exists.
+ */
+export interface ShellBlock {
+    id: number;
+    /** What produced the block: a local process, or a command echoed for reading. */
+    kind: 'shell' | 'note';
+    /** Readable source this block's bar opens: its own lines, or the session a note announces. */
+    source?: string;
+    command: string;
+    /** Retained output lines, oldest first. */
+    lines: string[];
+    /** Lines dropped from the front because the block exceeded its budget. */
+    dropped: number;
+    /** Durable sequence that was newest when the command started; the block is shown after it. */
+    anchor: number;
+    status: 'running' | 'exited';
+    /** Exit code, once the command ended; null when a signal ended it. */
+    code?: number | null;
+    signal?: string | null;
+    startedAt: number;
+    endedAt?: number;
+}
+/** Plain read-only view of the local `!` runs, so the UI never reads the service object. */
+export interface ShellSnapshot {
+    running: boolean;
+    blocks: readonly ShellBlock[];
+}
+/** What one shell controller needs from its owner. */
+export interface ShellHost {
+    /** Repaint after output or a status change. */
+    publish(): void;
+    /** Client working directory the command runs in. */
+    cwd(): string;
+    /** Environment for the child, already stripped of client credentials. */
+    env(): NodeJS.ProcessEnv;
+    /** Newest durable sequence of the selected session, so a block stays where it happened. */
+    anchor(): number;
+}
+/** Owns the `!` commands of this client process: one at a time, bounded, killable. */
+export declare class ShellController {
+    private readonly host;
+    readonly enabled: boolean;
+    private readonly blocks;
+    private readonly bytes;
+    private nextId;
+    private task;
+    private abort;
+    private lastPublish;
+    constructor(host: ShellHost, /** Whether `!` is allowed at all. */ enabled?: boolean);
+    /** Runs in creation order, oldest first; the newest is what the transcript shows at its end. */
+    get runs(): readonly ShellBlock[];
+    /** Whether a command is still running. */
+    get running(): boolean;
+    /** The plain snapshot `AppState.shell` publishes; blocks stay owned here. */
+    snapshot(): ShellSnapshot;
+    /** Start one command.
+     *
+     * One command runs at a time: a second `!` while the first is live is refused rather than queued,
+     * because the transcript shows a single result block and the reader can stop the first with Ctrl+C.
+     * @param command - Command line typed after `!`.
+     * @returns The block created for it.
+     */
+    start(command: string): ShellBlock;
+    /** Stop the running command: its process group gets SIGTERM, then SIGKILL after a grace period.
+     * @returns Whether a run was stopped.
+     */
+    cancel(): boolean;
+    /** Echo one client command as a local block, so the transcript holds a bar for it.
+     *
+     * Nothing runs and nothing is retained: the bar exists to be read and clicked, and the application
+     * links it to a readable source afterwards (`link`). A command that only fills a composer frame
+     * never reaches here, so the transcript does not collect bars for forms that were never run.
+     * @param command - The command line as the operator submitted it.
+     * @param source - Readable source the bar opens, when one already exists; `link` adds a later one.
+     * @returns The block created for it.
+     */
+    note(command: string, source?: string): ShellBlock;
+    /** Point the newest note at a readable source, so its bar opens what the run is doing now. */
+    link(source: string): void;
+    /** One run's retained output, with dropped lines made explicit.
+     * @param id - Run to read; defaults to the newest.
+     * @returns The text, or undefined when the run is unknown.
+     */
+    output(id?: number): string | undefined;
+    /** Stop the running command and wait for it, so no child outlives this client. */
+    stop(): Promise<void>;
+    /** Append one output line, trimming the block to its budgets from the front. */
+    private append;
+    /** Repaint, at most once per interval unless the change is a status change. */
+    private publish;
+}

package/dist/shell/controller.js

@@ -0,0 +1,158 @@
+/** Local shell runs the reader started with `!`, kept as bounded blocks for inline display.
+ *
+ * A block is the command line plus its retained output. Output is capped by both lines and bytes, so
+ * a runaway command can only fill its block, and only the newest blocks are kept. Nothing here is
+ * durable: no host record, no session state, no file.
+ */
+import { setTimeout as delay } from 'node:timers/promises';
+import { runShell } from "./runner.js";
+/** Output lines one block keeps before it drops the oldest. */
+const BLOCK_LINES = 200;
+/** Output bytes one block keeps before it drops the oldest. */
+const BLOCK_BYTES = 64 * 1024;
+/** Runs kept for display; the newest always survives. */
+const BLOCK_LIMIT = 20;
+/** Fastest repaint cadence while output streams; status changes always publish. */
+const PUBLISH_INTERVAL_MS = 80;
+/** Readable id of one `!` run's own output, so its transcript bar and its source entry agree. */
+export function localSourceId(id) { return `shell:${id}`; }
+/** Owns the `!` commands of this client process: one at a time, bounded, killable. */
+export class ShellController {
+    host;
+    enabled;
+    blocks = [];
+    bytes = new WeakMap();
+    nextId = 1;
+    task;
+    abort;
+    lastPublish = 0;
+    constructor(host, /** Whether `!` is allowed at all. */ enabled = true) {
+        this.host = host;
+        this.enabled = enabled;
+    }
+    /** Runs in creation order, oldest first; the newest is what the transcript shows at its end. */
+    get runs() { return this.blocks; }
+    /** Whether a command is still running. */
+    get running() { return this.blocks.some(block => block.status === 'running'); }
+    /** The plain snapshot `AppState.shell` publishes; blocks stay owned here. */
+    snapshot() { return { running: this.running, blocks: this.blocks }; }
+    /** Start one command.
+     *
+     * One command runs at a time: a second `!` while the first is live is refused rather than queued,
+     * because the transcript shows a single result block and the reader can stop the first with Ctrl+C.
+     * @param command - Command line typed after `!`.
+     * @returns The block created for it.
+     */
+    start(command) {
+        if (!this.enabled)
+            throw new Error('Shell commands are disabled (--no-shell or DSHT_NO_SHELL=1)');
+        if (this.task)
+            throw new Error('A shell command is already running; Ctrl+C stops it');
+        const id = this.nextId++;
+        const block = { id, kind: 'shell', source: localSourceId(id), command, lines: [], dropped: 0,
+            status: 'running', startedAt: Date.now(), anchor: this.host.anchor() };
+        this.blocks.push(block);
+        while (this.blocks.length > BLOCK_LIMIT)
+            this.blocks.shift();
+        this.bytes.set(block, 0);
+        const abort = new AbortController();
+        this.abort = abort;
+        this.publish(true);
+        const task = runShell(command, {
+            cwd: this.host.cwd(), env: this.host.env(), signal: abort.signal,
+            onLine: (line, stream) => this.append(block, line),
+        }).then(exit => {
+            block.status = 'exited';
+            block.code = exit.code;
+            block.signal = exit.signal;
+            block.endedAt = Date.now();
+        }, error => {
+            block.status = 'exited';
+            block.code = null;
+            this.append(block, `! ${error instanceof Error ? error.message : String(error)}`);
+        }).finally(() => {
+            if (this.abort === abort)
+                this.abort = undefined;
+            if (this.task === task)
+                this.task = undefined;
+            this.publish(true);
+        });
+        this.task = task;
+        return block;
+    }
+    /** Stop the running command: its process group gets SIGTERM, then SIGKILL after a grace period.
+     * @returns Whether a run was stopped.
+     */
+    cancel() {
+        if (!this.abort)
+            return false;
+        this.abort.abort();
+        return true;
+    }
+    /** Echo one client command as a local block, so the transcript holds a bar for it.
+     *
+     * Nothing runs and nothing is retained: the bar exists to be read and clicked, and the application
+     * links it to a readable source afterwards (`link`). A command that only fills a composer frame
+     * never reaches here, so the transcript does not collect bars for forms that were never run.
+     * @param command - The command line as the operator submitted it.
+     * @param source - Readable source the bar opens, when one already exists; `link` adds a later one.
+     * @returns The block created for it.
+     */
+    note(command, source) {
+        const block = { id: this.nextId++, kind: 'note', command, lines: [], dropped: 0,
+            status: 'exited', startedAt: Date.now(), endedAt: Date.now(), anchor: this.host.anchor(),
+            ...(source === undefined ? {} : { source }) };
+        this.blocks.push(block);
+        while (this.blocks.length > BLOCK_LIMIT)
+            this.blocks.shift();
+        this.publish(true);
+        return block;
+    }
+    /** Point the newest note at a readable source, so its bar opens what the run is doing now. */
+    link(source) {
+        const note = [...this.blocks].reverse().find(block => block.kind === 'note');
+        if (note === undefined || note.source === source)
+            return;
+        note.source = source;
+        this.publish(true);
+    }
+    /** One run's retained output, with dropped lines made explicit.
+     * @param id - Run to read; defaults to the newest.
+     * @returns The text, or undefined when the run is unknown.
+     */
+    output(id) {
+        const block = id === undefined ? this.blocks.at(-1) : this.blocks.find(item => item.id === id);
+        if (!block)
+            return undefined;
+        const head = block.dropped > 0 ? [`… ${block.dropped} earlier lines dropped …`] : [];
+        return [...head, ...block.lines].join('\n');
+    }
+    /** Stop the running command and wait for it, so no child outlives this client. */
+    async stop() {
+        this.cancel();
+        await this.task;
+        while (this.running)
+            await delay(20);
+    }
+    /** Append one output line, trimming the block to its budgets from the front. */
+    append(block, line) {
+        block.lines.push(line);
+        let bytes = (this.bytes.get(block) ?? 0) + line.length * 2;
+        while (block.lines.length > BLOCK_LINES || bytes > BLOCK_BYTES) {
+            if (block.lines.length === 1)
+                break;
+            bytes -= block.lines.shift().length * 2;
+            block.dropped++;
+        }
+        this.bytes.set(block, bytes);
+        this.publish(false);
+    }
+    /** Repaint, at most once per interval unless the change is a status change. */
+    publish(force) {
+        const now = Date.now();
+        if (!force && now - this.lastPublish < PUBLISH_INTERVAL_MS)
+            return;
+        this.lastPublish = now;
+        this.host.publish();
+    }
+}

package/dist/shell/index.d.ts

@@ -0,0 +1,5 @@
+/** Shell domain: the local `!` command runner and the bounded blocks it produces. */
+export { ShellController, localSourceId } from './controller.ts';
+export type { ShellBlock, ShellHost, ShellSnapshot } from './controller.ts';
+export { runProcess, runShell } from './runner.ts';
+export type { ShellExit, ShellRunOptions, ShellStream } from './runner.ts';

package/dist/shell/index.js

@@ -0,0 +1,3 @@
+/** Shell domain: the local `!` command runner and the bounded blocks it produces. */
+export { ShellController, localSourceId } from "./controller.js";
+export { runProcess, runShell } from "./runner.js";

package/dist/shell/runner.d.ts

@@ -0,0 +1,38 @@
+/** Which pipe one line arrived on. */
+export type ShellStream = 'stdout' | 'stderr';
+/** How one command ended. */
+export interface ShellExit {
+    code: number | null;
+    signal: string | null;
+}
+/** One command's execution contract. */
+export interface ShellRunOptions {
+    /** Working directory; the client's own directory, not the host's. */
+    cwd: string;
+    /** Environment for the child; the caller strips client credentials first. */
+    env: NodeJS.ProcessEnv;
+    /** Cancels the run; the child's process group is terminated. */
+    signal: AbortSignal;
+    /** Receives every complete line, in arrival order across both pipes. */
+    onLine(line: string, stream: ShellStream): void;
+}
+/** Run one command through the operator's shell and stream its lines.
+ *
+ * Both pipes are merged into one line stream in arrival order. A line longer than the assemble
+ * budget is emitted once, truncated, and the remainder is discarded until the next newline, so a
+ * command that never emits one cannot grow the client's memory.
+ * @param command - Command line, exactly as typed after `!`.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the command ended.
+ */
+export declare function runShell(command: string, options: ShellRunOptions): Promise<ShellExit>;
+/** Run one program with its own arguments, without a shell.
+ *
+ * A forked verifier is spawned this way: arguments reach the child verbatim, so a prompt can never be
+ * re-read as shell syntax.
+ * @param file - Program to run.
+ * @param args - Arguments, passed verbatim.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the program ended.
+ */
+export declare function runProcess(file: string, args: readonly string[], options: ShellRunOptions): Promise<ShellExit>;

package/dist/shell/runner.js

@@ -0,0 +1,147 @@
+/** Running one local shell command for the reader, and nothing else.
+ *
+ * `!cmd` executes on the machine this client runs on — the operator's laptop or a jump host — never
+ * on the host the agent works in. The host's shell belongs to the model's own tools; this module is
+ * a separate, local facility, and it is the only place in `src/` allowed to spawn a process — including
+ * the `dsht` child that verifies a scored round in a session of its own.
+ */
+import { spawn } from 'node:child_process';
+/** Longest single output line kept while it is still being assembled. */
+const MAX_LINE_CHARS = 8 * 1024;
+/** How long a cancelled command may ignore SIGTERM before it is killed. */
+const KILL_GRACE_MS = 2_000;
+/** The interactive shell to run under, falling back to `sh` when `$SHELL` is unusable. */
+function shellPath() {
+    const chosen = process.env.SHELL;
+    return chosen !== undefined && chosen !== '' ? chosen : '/bin/sh';
+}
+/** Terminate one child's whole process group, so pipelines and background children die with it.
+ *
+ * The child is spawned detached, which gives it its own group; signalling the group is what makes
+ * cancellation behave like Ctrl+C in a terminal instead of leaving orphans holding the pipes.
+ * @param child - The spawned shell.
+ * @param signal - Signal to send the group.
+ */
+function signalGroup(child, signal) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch { /* already gone */ }
+    }
+}
+/** Run one command through the operator's shell and stream its lines.
+ *
+ * Both pipes are merged into one line stream in arrival order. A line longer than the assemble
+ * budget is emitted once, truncated, and the remainder is discarded until the next newline, so a
+ * command that never emits one cannot grow the client's memory.
+ * @param command - Command line, exactly as typed after `!`.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the command ended.
+ */
+export function runShell(command, options) {
+    return spawnLines(shellPath(), ['-c', command], options);
+}
+/** Run one program with its own arguments, without a shell.
+ *
+ * A forked verifier is spawned this way: arguments reach the child verbatim, so a prompt can never be
+ * re-read as shell syntax.
+ * @param file - Program to run.
+ * @param args - Arguments, passed verbatim.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the program ended.
+ */
+export function runProcess(file, args, options) {
+    return spawnLines(file, [...args], options);
+}
+/** Spawn one program, merge both pipes into a single line stream, and resolve when it closes.
+ * @param file - Program to run.
+ * @param args - Arguments, passed verbatim.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the program ended.
+ */
+function spawnLines(file, args, options) {
+    return new Promise(resolve => {
+        // Nothing to cancel yet: never spawn a process the caller already abandoned.
+        if (options.signal.aborted) {
+            resolve({ code: null, signal: 'SIGTERM' });
+            return;
+        }
+        const child = spawn(file, [...args], {
+            cwd: options.cwd, env: options.env, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const carry = { stdout: '', stderr: '' };
+        const discarding = { stdout: false, stderr: false };
+        let settled = false;
+        let graceTimer;
+        /** Emit one assembled line, truncated to the budget.
+         *
+         * The bound is applied to every emitted line, not only to a partial remainder that overflowed:
+         * pipe chunking decides whether one huge line arrives whole or in pieces, so a bound applied only
+         * to the remainder would make the client's memory depend on the operating system's read size.
+         */
+        const emit = (line, stream) => {
+            if (discarding[stream]) {
+                discarding[stream] = false;
+                return;
+            }
+            const clean = line.replace(/\r$/, '');
+            options.onLine(clean.length > MAX_LINE_CHARS ? `${clean.slice(0, MAX_LINE_CHARS)}…` : clean, stream);
+        };
+        /** Split one chunk into lines, keeping the partial remainder for the next chunk. */
+        const feed = (stream, chunk) => {
+            carry[stream] += chunk;
+            for (;;) {
+                const newline = carry[stream].indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = carry[stream].slice(0, newline);
+                carry[stream] = carry[stream].slice(newline + 1);
+                emit(line, stream);
+            }
+            if (carry[stream].length > MAX_LINE_CHARS) {
+                // No newline in sight: emit the head once and drop the rest of this line.
+                if (!discarding[stream]) {
+                    options.onLine(`${carry[stream].slice(0, MAX_LINE_CHARS)}…`, stream);
+                    discarding[stream] = true;
+                }
+                carry[stream] = '';
+            }
+        };
+        const flush = (stream) => {
+            if (carry[stream] !== '')
+                emit(carry[stream], stream);
+            carry[stream] = '';
+        };
+        const finish = (exit) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(graceTimer);
+            options.signal.removeEventListener('abort', onAbort);
+            flush('stdout');
+            flush('stderr');
+            resolve(exit);
+        };
+        const onAbort = () => {
+            signalGroup(child, 'SIGTERM');
+            graceTimer = setTimeout(() => { signalGroup(child, 'SIGKILL'); }, KILL_GRACE_MS);
+        };
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => feed('stdout', chunk));
+        child.stderr?.on('data', (chunk) => feed('stderr', chunk));
+        child.on('error', error => { options.onLine(`! ${error.message}`, 'stderr'); finish({ code: null, signal: null }); });
+        child.on('close', (code, signal) => finish({ code, signal }));
+        if (options.signal.aborted)
+            onAbort();
+        else
+            options.signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/slash/index.d.ts

@@ -0,0 +1,10 @@
+/** Slash-command domain: the command catalog, its syntax and the completion helpers.
+ *
+ * A pure leaf: it imports nothing from the application, the features or the UI.
+ */
+export { COMMAND_HINTS, COMMAND_LABELS, COMMAND_LABEL_WIDTH, COMMANDS, COMMAND_POLICY, argumentHint, commandMatches, commonPrefix, completeCommand, resolveCommand, suggestedCommands } from './registry.ts';
+export type { CommandHint, CommandPolicy } from './registry.ts';
+export { parseCommand, loopNameQuery, validLoopOption, LOOP_ABORT_USAGE, LOOP_ANSWER_USAGE, LOOP_STOP_USAGE, LOOP_USAGE } from './parse.ts';
+export type { Command, LoopOptions } from './parse.ts';
+export { interpret, normalize, authorize } from './pipeline.ts';
+export type { AuthorizeFacts, DeferReason, ExecutableSubmission, InterpretFacts, LineCommand, NormalizeFacts, Submission, UiAction, Verdict } from './pipeline.ts';

package/dist/slash/index.js

@@ -0,0 +1,7 @@
+/** Slash-command domain: the command catalog, its syntax and the completion helpers.
+ *
+ * A pure leaf: it imports nothing from the application, the features or the UI.
+ */
+export { COMMAND_HINTS, COMMAND_LABELS, COMMAND_LABEL_WIDTH, COMMANDS, COMMAND_POLICY, argumentHint, commandMatches, commonPrefix, completeCommand, resolveCommand, suggestedCommands } from "./registry.js";
+export { parseCommand, loopNameQuery, validLoopOption, LOOP_ABORT_USAGE, LOOP_ANSWER_USAGE, LOOP_STOP_USAGE, LOOP_USAGE } from "./parse.js";
+export { interpret, normalize, authorize } from "./pipeline.js";

package/dist/slash/parse.d.ts

@@ -0,0 +1,166 @@
+/** One parsed command; every side effect stays with the caller. */
+export type Command = {
+    kind: 'ignore';
+} | {
+    kind: 'copy';
+} | {
+    kind: 'quit';
+} | {
+    kind: 'panel';
+    panel: 'cost' | 'status' | 'help';
+} | {
+    kind: 'remove';
+    target: 'workspace' | 'session';
+    query: string;
+} | {
+    kind: 'navigate';
+    target: 'workspace' | 'session';
+    query?: string;
+} | {
+    kind: 'latest';
+} | {
+    kind: 'models';
+    args: string[];
+} | {
+    kind: 'queue';
+} | {
+    kind: 'newSession';
+}
+/** Open the saved-prompt picker, or save the following text as a shortcut prompt. */
+ | {
+    kind: 'prompts';
+} | {
+    kind: 'savePrompt';
+    text: string;
+} | {
+    kind: 'history';
+    query: string;
+} | {
+    kind: 'sessionSearch';
+    command: '/ssearch' | '/wsearch';
+    query: string;
+} | {
+    kind: 'historySearch';
+    query: string;
+} | {
+    kind: 'think';
+    target: string;
+} | {
+    kind: 'older';
+} | {
+    kind: 'compact';
+}
+/** Clear the client's own HANDOFF.md, then ask the agent to write a fresh session handoff. */
+ | {
+    kind: 'handoff';
+}
+/** Start the client-driven scored loop for one `loop.yaml` record. */
+ | {
+    kind: 'loop';
+    name: string;
+    options: LoopOptions;
+}
+/** Offer the `loop.yaml` records so one can be chosen instead of typed. */
+ | {
+    kind: 'loops';
+}
+/** Stop the running loop, running or paused. */
+ | {
+    kind: 'loopStop';
+}
+/** Answer a paused run, so the current artifact is judged again with the operator's addition. */
+ | {
+    kind: 'loopAnswer';
+    text: string;
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'approval';
+    allowed: boolean;
+} | {
+    kind: 'hostCommand';
+    line: string;
+}
+/** A local `!` command, run on this machine rather than the host. */
+ | {
+    kind: 'shell';
+    command: string;
+} | {
+    kind: 'export';
+    destination?: string;
+} | {
+    kind: 'exportHtml';
+    destination?: string;
+} | {
+    kind: 'coredump';
+    tag?: string;
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'prompt';
+    text: string;
+};
+/** Options carried by `/loop`.
+ *
+ * Only the fields the operator actually typed are present, so the syntax layer validates each value
+ * it sees and the application owns the defaults — command line first, then the record's `defaults`,
+ * then the global ones.
+ */
+export interface LoopOptions {
+    /** First step to run; default 1. */
+    from?: number;
+    /** Last step to run; default the record's last step. */
+    to?: number;
+    /** Passing score per step, 0-10 and possibly fractional; default the record's, else 8. */
+    score?: number;
+    /** Attempts allowed per step; default the record's, else 10. */
+    tries?: number;
+    /** Values that replace the record's own `vars` for this run, such as the document under review.
+     *
+     * The interactive form fills this in; the command line has no syntax for it, because the record —
+     * not the syntax layer — is what knows which names exist.
+     */
+    vars?: Readonly<Record<string, string>>;
+}
+/** The numeric options a flag can carry; `vars` is not one, so it stays out of the flag table. */
+type LoopNumberOption = 'from' | 'to' | 'score' | 'tries';
+/** Whether one numeric value is acceptable for one loop option.
+ *
+ * The command line and the interactive form share this rule, so a value the form accepts is exactly
+ * one the syntax would have accepted if it had been typed.
+ * @param key - Option being set.
+ * @param value - Candidate number.
+ * @returns True when the option may carry that value.
+ */
+export declare function validLoopOption(key: LoopNumberOption, value: number): boolean;
+/** The record name the composer is currently typing after `/loop`, if any.
+ *
+ * The loop-name menu appears while the line is `/loop` or `/loop <one unfinished token>`; a second
+ * token means the operator moved on to the flags, so the menu stays out of the way. A trailing space
+ * after a complete name still counts: the menu then confirms that name rather than filtering it out.
+ * @param line - Composer draft exactly as typed.
+ * @returns The unfinished name (empty when none was started), or undefined for any other line.
+ */
+export declare function loopNameQuery(line: string): string | undefined;
+/** The one message every malformed `/loop` line receives. */
+export declare const LOOP_USAGE = "Use /loop <name> [score] [tries] [--from N] [--to N] [--score X] [--tries N]";
+/** The one message a malformed `/loop stop` line receives. */
+export declare const LOOP_STOP_USAGE = "Use /loop stop (no arguments)";
+/** The one message a `/loop answer` line without an answer receives. */
+export declare const LOOP_ANSWER_USAGE = "Use /loop answer <text>";
+/** The one message a malformed `/loop abort` line receives. */
+export declare const LOOP_ABORT_USAGE = "Use /loop abort (no arguments)";
+/** Parse one composer line into a command without performing any of its effects.
+ *
+ * The order of the checks is the command precedence: the in-place panels, navigation and removal,
+ * then the session and host commands, then a plain prompt. Facts about the current screen or a
+ * pending interaction are deliberately absent: they decide whether a command may run, not what it is.
+ *
+ * A leading token that names exactly one command is resolved first, so `/pro Add tests` runs
+ * `/prompt Add tests`; an ambiguous token is left alone and reported with its candidates.
+ * @param line - Draft exactly as submitted.
+ * @returns The parsed command.
+ */
+export declare function parseCommand(line: string): Command;
+export {};