@itookit/dsht 0.3.8 → 0.5.1

package/dist/slash/parse.js

@@ -0,0 +1,259 @@
+/** Slash-command syntax: one composer line in, one semantic command out.
+ *
+ * This module is a pure leaf. It reads no UI facts, performs no effects and imports nothing from the
+ * application, so "what the line means" stays separate from "what Enter currently does" (which is
+ * `slash/pipeline.ts` in the front end) and from "may this run now" (the pipeline's `authorize`).
+ */
+import { commandMatches, resolveCommand } from "./registry.js";
+/** How each loop flag names an option and validates its value. */
+const LOOP_FLAGS = {
+    '--from': { key: 'from', valid: value => Number.isSafeInteger(value) && value >= 1 },
+    '--to': { key: 'to', valid: value => Number.isSafeInteger(value) && value >= 1 },
+    '--score': { key: 'score', valid: value => Number.isFinite(value) && value >= 0 && value <= 10 },
+    '--tries': { key: 'tries', valid: value => Number.isSafeInteger(value) && value >= 1 },
+};
+/** The flag that carries one option, so a form keyed by option validates with the same rule. */
+const LOOP_OPTION_FLAGS = {
+    from: '--from', to: '--to', score: '--score', tries: '--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 function validLoopOption(key, value) {
+    return LOOP_FLAGS[LOOP_OPTION_FLAGS[key]].valid(value);
+}
+/** 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 function loopNameQuery(line) {
+    if (!line.startsWith('/loop'))
+        return undefined;
+    const rest = line.slice('/loop'.length);
+    if (rest === '')
+        return '';
+    const match = /^[ \t]+(\S*)[ \t]*$/.exec(rest);
+    // The subcommands are never records, so the menu must not filter records by them.
+    return match?.[1] !== undefined && LOOP_SUBCOMMANDS.includes(match[1]) ? undefined : match?.[1];
+}
+/** Names `/loop` itself owns, so the record menu never treats one as the start of a record name. */
+const LOOP_SUBCOMMANDS = ['stop', 'abort', 'answer'];
+/** The one message every malformed `/loop` line receives. */
+export 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 const LOOP_STOP_USAGE = 'Use /loop stop (no arguments)';
+/** The one message a `/loop answer` line without an answer receives. */
+export const LOOP_ANSWER_USAGE = 'Use /loop answer <text>';
+/** The one message a malformed `/loop abort` line receives. */
+export const LOOP_ABORT_USAGE = 'Use /loop abort (no arguments)';
+/** Parse `/loop <name> [score] [tries] [flags]`.
+ *
+ * The name is a record in `loop.yaml`; the syntax layer cannot know which records exist, so it only
+ * requires a name that is not a flag and leaves the lookup (and its error, which lists the available
+ * names) to the application. Score and tries may be positional or flagged; the last one wins. A line
+ * with no name at all is the request to be offered the records instead of typing one; `stop`, `abort`
+ * and `answer <text>` are `/loop`'s own subcommands rather than records.
+ * @param value - Trimmed line that starts with `/loop`.
+ * @returns The command, or the usage error.
+ */
+function loopCommand(value) {
+    const words = value.slice('/loop'.length).trim().split(/\s+/).filter(Boolean);
+    const name = words[0];
+    if (name === undefined)
+        return { kind: 'loops' };
+    // `stop`, `answer` and `abort` belong to `/loop` itself, which is why a record may not take them.
+    if (name === 'stop')
+        return words.length === 1 ? { kind: 'loopStop' } : { kind: 'error', message: LOOP_STOP_USAGE };
+    if (name === 'abort')
+        return words.length === 1 ? { kind: 'loopStop' } : { kind: 'error', message: LOOP_ABORT_USAGE };
+    if (name === 'answer') {
+        const text = words.slice(1).join(' ').trim();
+        return text === '' ? { kind: 'error', message: LOOP_ANSWER_USAGE } : { kind: 'loopAnswer', text };
+    }
+    if (name.startsWith('--'))
+        return { kind: 'error', message: LOOP_USAGE };
+    const options = {};
+    let positionals = 0;
+    for (let index = 1; index < words.length; index += 1) {
+        const word = words[index];
+        if (word.startsWith('--')) {
+            const spec = LOOP_FLAGS[word];
+            const raw = words[index + 1];
+            if (spec === undefined || raw === undefined)
+                return { kind: 'error', message: LOOP_USAGE };
+            const number = Number(raw);
+            if (!spec.valid(number))
+                return { kind: 'error', message: LOOP_USAGE };
+            options[spec.key] = number;
+            index += 1;
+            continue;
+        }
+        // Two optional positionals: the passing score, then the attempt budget.
+        const number = Number(word);
+        if (positionals > 1)
+            return { kind: 'error', message: LOOP_USAGE };
+        const spec = positionals === 0 ? LOOP_FLAGS['--score'] : LOOP_FLAGS['--tries'];
+        if (!spec.valid(number))
+            return { kind: 'error', message: LOOP_USAGE };
+        options[spec.key] = number;
+        positionals += 1;
+    }
+    return { kind: 'loop', name, options };
+}
+/** Parse workspace and resume navigation, including their long aliases. */
+function navigationCommand(value) {
+    const match = /^\/(ws|workspace|workspaces|resume|session|sessions)(?:\s+(.+))?$/.exec(value);
+    if (!match)
+        return undefined;
+    return { kind: match[1] === 'ws' || match[1].startsWith('workspace') ? 'workspace' : 'session', query: match[2] };
+}
+/** Strip one pair of surrounding quotes from an argument. */
+function unquote(value) { return value.replace(/^(["'])(.*)\1$/, '$2'); }
+/** 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 function parseCommand(line) {
+    const raw = line.trim();
+    if (!raw)
+        return { kind: 'ignore' };
+    const value = resolveToken(raw);
+    // `!` runs on the machine this client is on; it never reaches the host or the model.
+    if (value.startsWith('!')) {
+        const command = value.slice(1).trim();
+        return command ? { kind: 'shell', command } : { kind: 'error', message: 'Type a command after !' };
+    }
+    if (value === '/copy')
+        return { kind: 'copy' };
+    if (value === '/quit')
+        return { kind: 'quit' };
+    if (value === '/cost')
+        return { kind: 'panel', panel: 'cost' };
+    if (value === '/status')
+        return { kind: 'panel', panel: 'status' };
+    if (value === '/help')
+        return { kind: 'panel', panel: 'help' };
+    const navigation = navigationCommand(value);
+    if (navigation && /^--(?:delete|archive)(?:\s|$)/.test(navigation.query ?? '')) {
+        const query = navigation.query.replace(/^--(?:delete|archive)\s*/, '');
+        if (!query)
+            return { kind: 'error', message: 'Specify the name or ID to remove' };
+        return { kind: 'remove', target: navigation.kind, query };
+    }
+    if (navigation)
+        return { kind: 'navigate', target: navigation.kind, query: navigation.query };
+    if (value === '/latest')
+        return { kind: 'latest' };
+    if (/^\/model(?: |$)/.test(value)) {
+        const args = value.split(/\s+/).slice(1);
+        if (args.length && (args.length < 2 || args.length > 3))
+            return { kind: 'error', message: 'Use /model [provider model [effort]]' };
+        return { kind: 'models', args };
+    }
+    if (value === '/queue')
+        return { kind: 'queue' };
+    if (value === '/new')
+        return { kind: 'newSession' };
+    // `/prompt` alone opens the list; any trailing text is the shortcut being saved. Quoting is
+    // deliberately not stripped here: the saved prompt is stored exactly as it will be sent.
+    if (/^\/prompt(?:\s|$)/.test(value)) {
+        const text = value.slice(7).trim();
+        return text ? { kind: 'savePrompt', text } : { kind: 'prompts' };
+    }
+    if (value === '/history' || value.startsWith('/history '))
+        return { kind: 'history', query: value.slice(8).trim() };
+    if (/^\/(?:search|ssearch|wsearch)(?: |$)/.test(value)) {
+        const [command, ...words] = value.split(' ');
+        const query = words.join(' ').trim();
+        if (!query)
+            return { kind: 'error', message: `Use ${command} <text>` };
+        return command === '/search' ? { kind: 'historySearch', query }
+            : { kind: 'sessionSearch', command: command, query };
+    }
+    if (/^\/think(?: |$)/.test(value))
+        return { kind: 'think', target: value.slice(6).trim() };
+    if (value === '/older')
+        return { kind: 'older' };
+    if (/^\/compact(?: |$)/.test(value)) {
+        if (value !== '/compact')
+            return { kind: 'error', message: 'Use /compact (no arguments)' };
+        return { kind: 'compact' };
+    }
+    if (/^\/handoff(?: |$)/.test(value)) {
+        if (value !== '/handoff')
+            return { kind: 'error', message: 'Use /handoff (no arguments)' };
+        return { kind: 'handoff' };
+    }
+    if (/^\/loop(?: |$)/.test(value))
+        return loopCommand(value);
+    if (value === '/cancel')
+        return { kind: 'cancel' };
+    if (value === '/allow')
+        return { kind: 'approval', allowed: true };
+    if (value === '/deny')
+        return { kind: 'approval', allowed: false };
+    if (/^\/(?:plan|goal|permission|feedback)(?:\s|$)/.test(value))
+        return { kind: 'hostCommand', line: value };
+    if (/^\/export(?:\s|$)/.test(value)) {
+        const destination = unquote(value.slice(7).trim());
+        return { kind: 'export', ...(destination ? { destination } : {}) };
+    }
+    if (/^\/export-html(?:\s|$)/.test(value)) {
+        const destination = unquote(value.slice(12).trim());
+        return { kind: 'exportHtml', ...(destination ? { destination } : {}) };
+    }
+    if (/^\/coredump(?:\s|$)/.test(value)) {
+        // A diagnostic of this client's own heap needs neither a session nor a connected host.
+        const tag = unquote(value.slice(9).trim());
+        return { kind: 'coredump', ...(tag ? { tag } : {}) };
+    }
+    if (value.startsWith('/'))
+        return unresolved(value);
+    return { kind: 'prompt', text: value };
+}
+/** First word of a trimmed draft, so arguments are never part of a command name. */
+function commandToken(value) {
+    const space = value.search(/\s/);
+    return space === -1 ? value : value.slice(0, space);
+}
+/** Resolve a uniquely-named command prefix to the command itself, keeping the arguments.
+ * @param value - Trimmed draft.
+ * @returns The draft with its command token resolved when it names exactly one command.
+ */
+function resolveToken(value) {
+    if (!value.startsWith('/'))
+        return value;
+    const token = commandToken(value);
+    const resolved = resolveCommand(token);
+    return resolved === undefined || resolved === token ? value : resolved + value.slice(token.length);
+}
+/** Report a leading token that names no single command, naming what it could mean.
+ * @param value - Trimmed draft that starts with `/`.
+ * @returns The error command.
+ */
+function unresolved(value) {
+    const matches = commandMatches(commandToken(value));
+    // Exactly one match here is an `exactOnly` command that refused prefix resolution.
+    if (matches.length === 1)
+        return { kind: 'error', message: `Type the full command: ${matches[0]}` };
+    // A short candidate list helps more than a generic message; a bare `/` matches every command.
+    if (matches.length > 1 && matches.length <= 6)
+        return { kind: 'error', message: `Ambiguous command. Matches: ${matches.join(' ')}` };
+    return { kind: 'error', message: 'Unknown command. Use /help.' };
+}

package/dist/slash/pipeline.d.ts

@@ -0,0 +1,140 @@
+/** The pipeline one submitted line travels: interpret → normalize → authorize.
+ *
+ * Parsing, completion and policy live here; effects never do. The three stages answer three different
+ * questions and must not be merged:
+ *
+ * * `interpret` reads **front-end facts only** (an open menu, copy mode, the path screen) and turns the
+ *   raw draft into a `Submission`. It is the last place a UI concept exists;
+ * * `normalize` reads **application facts** (is a question waiting?) and turns a submission into the
+ *   one `LineCommand` the application can execute. Both front ends share it;
+ * * `authorize` reads the command's own declared policy plus application facts and returns a verdict.
+ *
+ * This module is a pure leaf like the rest of `slash/`: it imports no application, feature or UI code,
+ * so every stage can be tested without mounting anything.
+ */
+import { type Command } from './parse.ts';
+/** A front-end action: a mode of the composer, never an application effect. */
+export type UiAction = {
+    kind: 'ignore';
+} | {
+    kind: 'reference';
+};
+/** A line the application can execute.
+ *
+ * `Command` is what the syntax layer produces; the two extra kinds are lines the front end only reads
+ * while it has context the syntax cannot see — a free-text answer to a waiting question, and a
+ * directory typed on the path screen. They travel the same `runCommand` path as every command so the
+ * application keeps one dispatch.
+ */
+export type LineCommand = Command | {
+    kind: 'answer';
+    text: string;
+} | {
+    kind: 'path';
+    value: string;
+};
+/** What the front end made of one draft, before any application semantics. */
+export type Submission = {
+    kind: 'mode';
+    action: UiAction;
+} | {
+    kind: 'line';
+    line: string;
+} | {
+    kind: 'path';
+    value: string;
+};
+/** A submission that still needs normalizing: a front-end mode is handled by the front end itself. */
+export type ExecutableSubmission = Extract<Submission, {
+    kind: 'line' | 'path';
+}>;
+/** Front-end facts `interpret` may read; nothing else is needed. */
+export interface InterpretFacts {
+    /** The draft exactly as submitted. */
+    line: string;
+    /** The `@` completion menu owns the draft while open. */
+    referenceOpen: boolean;
+    /** Copy mode freezes the display and ignores submissions. */
+    copyMode: boolean;
+    /** The screen the draft was typed on. The only UI concept the pipeline may touch. */
+    screen: 'workspaces' | 'sessions' | 'chat' | 'path';
+}
+/** Decide what the front end has, without any application semantics.
+ *
+ * On the path screen an absolute directory starts with `/`, which is also how a command starts, so the
+ * screen cannot simply claim every line: a line that names a known command (or a `!` shell line) still
+ * escapes the screen and is normalized as usual. Everything else there is the directory that was asked
+ * for. Without this rule `/srv/data` would be parsed as a command and refused as unknown.
+ * @param facts - Current front-end facts.
+ * @returns The submission the application will normalize.
+ */
+export declare function interpret(facts: InterpretFacts): Submission;
+/** Application facts `normalize` needs to classify free text. */
+export interface NormalizeFacts {
+    /** A conversation is selected, so free text has somewhere to go. */
+    sessionSelected: boolean;
+    /** A question of the selected session is waiting, so free text answers it. */
+    question: boolean;
+    /** An approval of the selected session is waiting, so free text is not accepted. */
+    pending: boolean;
+}
+/** Turn a submission into the one line the application can execute.
+ *
+ * The order is the precedence: a directory the screen asked for, then a `/` or `!` line, then the two
+ * meanings free text can have while an interaction waits, then a plain message.
+ * @param submission - What the front end made of the draft.
+ * @param facts - Current application facts.
+ * @returns The executable line.
+ */
+export declare function normalize(submission: ExecutableSubmission, facts: NormalizeFacts): LineCommand;
+/** Application facts `authorize` needs; all of them exist with or without a UI. */
+export interface AuthorizeFacts {
+    /** A conversation is selected, so a command that needs one may run. */
+    sessionSelected: boolean;
+    /** An interaction of that conversation is waiting. */
+    pending: boolean;
+    /** Another operation already owns the client's single foreground slot.
+     *
+     * A front end reads this from the controller, so "may this line run while something else is running"
+     * is answered here — with a reason — instead of by each front end dropping the line in silence.
+     */
+    foreground: boolean;
+    /** Whether the selected conversation has a turn or a loop in flight.
+     *
+     * A loop is reported as `loop` rather than as the turn it runs, because stopping the loop is what
+     * the operator has to do first, and that is the reason the refusal has to name.
+     */
+    during: 'idle' | 'turn' | 'loop';
+}
+/** Why a line the policy accepted is not running yet.
+ *
+ * The fact that has to clear: the foreground slot, a turn, or a whole loop. One fact, because a line is
+ * held behind the longest-lived of them and a front end only needs to know what to watch for.
+ */
+export type DeferReason = 'busy' | 'turn' | 'loop';
+/** Whether one command may run now, may run later, or may not run at all.
+ *
+ * A refusal is always the error line, never an arbitrary command.
+ */
+export type Verdict = {
+    allow: true;
+    command: LineCommand;
+    defer?: DeferReason;
+} | {
+    allow: false;
+    error: Extract<Command, {
+        kind: 'error';
+    }>;
+};
+/** Apply one command's declared policy to the current application facts.
+ *
+ * The policy is data on the command kind, so this function never enumerates commands. A kind with no
+ * entry has no constraint. The constraint names describe the fact, not the screen: `requiresSession`
+ * is refused in headless too (where a session always exists, so the check simply passes), and
+ * `requiresNoInteraction` is refused wherever an interaction waits, because a front end without an
+ * answer channel cannot satisfy it either.
+ * @param command - Line about to be executed.
+ * @param facts - Current application facts.
+ * @returns The verdict; on refusal, the error command the application should report.
+ */
+export declare function authorize(command: LineCommand, facts: AuthorizeFacts): Verdict;

package/dist/slash/pipeline.js

@@ -0,0 +1,115 @@
+/** The pipeline one submitted line travels: interpret → normalize → authorize.
+ *
+ * Parsing, completion and policy live here; effects never do. The three stages answer three different
+ * questions and must not be merged:
+ *
+ * * `interpret` reads **front-end facts only** (an open menu, copy mode, the path screen) and turns the
+ *   raw draft into a `Submission`. It is the last place a UI concept exists;
+ * * `normalize` reads **application facts** (is a question waiting?) and turns a submission into the
+ *   one `LineCommand` the application can execute. Both front ends share it;
+ * * `authorize` reads the command's own declared policy plus application facts and returns a verdict.
+ *
+ * This module is a pure leaf like the rest of `slash/`: it imports no application, feature or UI code,
+ * so every stage can be tested without mounting anything.
+ */
+import { parseCommand } from "./parse.js";
+import { COMMAND_POLICY, resolveCommand } from "./registry.js";
+/** Decide what the front end has, without any application semantics.
+ *
+ * On the path screen an absolute directory starts with `/`, which is also how a command starts, so the
+ * screen cannot simply claim every line: a line that names a known command (or a `!` shell line) still
+ * escapes the screen and is normalized as usual. Everything else there is the directory that was asked
+ * for. Without this rule `/srv/data` would be parsed as a command and refused as unknown.
+ * @param facts - Current front-end facts.
+ * @returns The submission the application will normalize.
+ */
+export function interpret(facts) {
+    if (facts.referenceOpen)
+        return { kind: 'mode', action: { kind: 'reference' } };
+    if (facts.copyMode)
+        return { kind: 'mode', action: { kind: 'ignore' } };
+    const value = facts.line.trim();
+    if (!value)
+        return { kind: 'mode', action: { kind: 'ignore' } };
+    if (facts.screen === 'path' && !namesCommand(value))
+        return { kind: 'path', value };
+    return { kind: 'line', line: facts.line };
+}
+/** Whether a line is meant as a command rather than as the directory the path screen asked for.
+ * @param value - Trimmed draft.
+ * @returns True for a `!` line or a line whose token names exactly one command.
+ */
+function namesCommand(value) {
+    if (value.startsWith('!'))
+        return true;
+    const token = value.split(/\s+/)[0] ?? '';
+    return token.startsWith('/') && resolveCommand(token) !== undefined;
+}
+/** Turn a submission into the one line the application can execute.
+ *
+ * The order is the precedence: a directory the screen asked for, then a `/` or `!` line, then the two
+ * meanings free text can have while an interaction waits, then a plain message.
+ * @param submission - What the front end made of the draft.
+ * @param facts - Current application facts.
+ * @returns The executable line.
+ */
+export function normalize(submission, facts) {
+    if (submission.kind === 'path')
+        return { kind: 'path', value: submission.value };
+    const value = submission.line.trim();
+    if (value.startsWith('/') || value.startsWith('!'))
+        return parseCommand(value);
+    // A question takes free text as its answer; an approval keeps every choice explicit.
+    if (facts.question)
+        return { kind: 'answer', text: value };
+    if (facts.pending)
+        return { kind: 'error', message: 'Answer the approval with /allow or /deny' };
+    // Free text without a conversation has nowhere to go; saying so beats sending it to no session.
+    if (!facts.sessionSelected)
+        return { kind: 'error', message: 'Choose a session or type /ws or /resume' };
+    return { kind: 'prompt', text: value };
+}
+/** Apply one command's declared policy to the current application facts.
+ *
+ * The policy is data on the command kind, so this function never enumerates commands. A kind with no
+ * entry has no constraint. The constraint names describe the fact, not the screen: `requiresSession`
+ * is refused in headless too (where a session always exists, so the check simply passes), and
+ * `requiresNoInteraction` is refused wherever an interaction waits, because a front end without an
+ * answer channel cannot satisfy it either.
+ * @param command - Line about to be executed.
+ * @param facts - Current application facts.
+ * @returns The verdict; on refusal, the error command the application should report.
+ */
+export function authorize(command, facts) {
+    // `answer` and `path` are lines, not catalog kinds, so the table lookup is by kind string.
+    const policy = COMMAND_POLICY[command.kind];
+    if (policy?.requiresSession === true && !facts.sessionSelected) {
+        return { allow: false, error: { kind: 'error', message: 'Select a session first' } };
+    }
+    if (policy?.requiresNoInteraction === true && facts.pending) {
+        return { allow: false, error: { kind: 'error', message: 'Answer the pending question or approval first' } };
+    }
+    // `during` is checked last: "answer what is waiting" is a more actionable reason than "something is
+    // running", and a pending interaction usually means a turn is running too.
+    const during = facts.during === 'loop' ? policy?.duringLoop : facts.during === 'turn' ? policy?.duringTurn : undefined;
+    const whileBusy = policy?.whileBusy ?? 'deny';
+    if (during === 'deny') {
+        return { allow: false, error: { kind: 'error',
+                message: facts.during === 'loop' ? 'Stop the running loop first' : 'Wait for the running turn to finish' } };
+    }
+    // A queue behind a turn or a loop is decided first: the line runs later anyway, so the slot being
+    // busy right now says nothing about whether it should. The held line waits for both facts.
+    if (during === 'queue')
+        return { allow: true, command, defer: facts.during === 'loop' ? 'loop' : 'turn' };
+    // Only the commands declared to answer the operator or the host are admitted while the client is
+    // busy (§3.4); everything else waits for a reason the operator can read, because running it now
+    // would interleave with the operation they are watching.
+    if (facts.foreground) {
+        if (whileBusy === 'deny') {
+            return { allow: false, error: { kind: 'error', message: 'Wait for the running operation to finish' } };
+        }
+        if (whileBusy === 'queue')
+            return { allow: true, command, defer: 'busy' };
+    }
+    return { allow: true, command };
+}

package/dist/slash/registry.d.ts

@@ -0,0 +1,88 @@
+/** Slash-command catalog shared by completion, `/help` and the submission router. */
+import type { Command } from './parse.ts';
+/** One slash command advertised by completion and `/help`. */
+export interface CommandHint {
+    /** Slash command as typed without arguments. */
+    command: string;
+    /** Argument hint shown after the command; absent when it takes none. */
+    usage?: string;
+    /** One-line action description shown by `/help`. */
+    description: string;
+    /** Must be typed in full: a unique prefix of it is completed, never executed on Enter. */
+    exactOnly?: boolean;
+}
+/** Command discovery catalog shared by Tab completion and the `/help` panel. */
+export declare const COMMAND_HINTS: readonly CommandHint[];
+/** Command names only, in catalog order. */
+export declare const COMMANDS: string[];
+/** Command column text per hint, aligned in the `/help` panel. */
+export declare const COMMAND_LABELS: string[];
+/** Widest command column, so descriptions start on one column. */
+export declare const COMMAND_LABEL_WIDTH: number;
+/** Commands whose name starts with one token, in catalog order.
+ * @param token - First word of a draft, such as `/pro`.
+ * @returns Matching command names, empty when the token names nothing.
+ */
+export declare function commandMatches(token: string): string[];
+/** Resolve one typed command token to the command it names.
+ *
+ * An exact command resolves to itself. A prefix that matches exactly one command resolves to that
+ * command too, so Enter can run it without typing the whole name; an unknown or ambiguous token,
+ * and any prefix of an `exactOnly` command, resolves to undefined so the draft stays as typed.
+ * @param token - First word of a draft, without its arguments.
+ * @returns The command name, or undefined when the token does not name one command.
+ */
+export declare function resolveCommand(token: string): string | undefined;
+/** What may happen to a command while the selected conversation is busy.
+ *
+ * `'queue'` means the line is accepted and held until the fact clears; the front end fulfils it (it
+ * owns the port and the view), and a scripted caller waits for the same fact before running the line.
+ */
+export type DuringExecution = 'run' | 'queue' | 'deny';
+/** Where one parsed command may run, and what it must wait for.
+ *
+ * The names describe the application fact, not the screen that happens to represent it: a command
+ * that needs a session is refused wherever no session is selected, and a front end cannot make that
+ * requirement disappear by not having screens. An absent `duringTurn`/`duringLoop` means "no
+ * constraint" — the many reads and local commands need no entry to keep running.
+ */
+export interface CommandPolicy {
+    /** Needs a selected conversation. */
+    requiresSession?: boolean;
+    /** Refused while an approval or a question of that conversation is waiting. */
+    requiresNoInteraction?: boolean;
+    /** Belongs to the control lane of the session write gate: it preempts waiting writes (§6.3.2). */
+    control?: boolean;
+    /** While another operation owns the foreground slot, which is what the operator is watching. */
+    whileBusy?: DuringExecution;
+    /** While a turn of the selected conversation runs. */
+    duringTurn?: DuringExecution;
+    /** While a client-driven loop runs, which is what the operator must deal with first. */
+    duringLoop?: DuringExecution;
+}
+export declare const COMMAND_POLICY: Readonly<Partial<Record<Command['kind'], CommandPolicy>>>;
+/** Longest common prefix of the candidate commands, so Tab can extend an ambiguous draft.
+ * @param values - Command candidates.
+ * @returns The shared leading prefix.
+ */
+export declare function commonPrefix(values: string[]): string;
+/** Complete the leading slash command; an ambiguous draft extends to the shared prefix.
+ * @param input - Current composer draft.
+ * @returns The completed draft, or undefined when nothing can be completed.
+ */
+export declare function completeCommand(input: string): string | undefined;
+/** Commands matching the current draft, shown under the composer.
+ * @param input - Current composer draft.
+ * @returns Candidate command names.
+ */
+export declare function suggestedCommands(input: string): string[];
+/** The catalog entry whose arguments the draft is currently typing.
+ *
+ * A usage line is only useful once the name is settled and arguments have begun, so this requires
+ * whitespace after a token that names one command: `/model ` hints the model command, while `/co `
+ * names none and `/think` is still completing a name. A unique prefix counts, because the same prefix
+ * already runs that command.
+ * @param input - Current composer draft.
+ * @returns The command's hint, or undefined when no arguments are being typed.
+ */
+export declare function argumentHint(input: string): CommandHint | undefined;