@gaunt-sloth/agent 2.0.0-alpha.3 → 2.0.0-alpha.31

package/dist/modules/slashCommands.js

@@ -0,0 +1,995 @@
+/**
+ * Pure, React-free slash-command layer shared by BOTH interactive surfaces (GS2-8): the Ink
+ * TUI (`packages/app/src/tui/`, which re-exports this module) and the readline `--no-tui`
+ * session (`interactiveSessionModule.ts` in this package). One registry, one source of truth —
+ * a command added here appears in `/help` on both surfaces automatically.
+ *
+ * Mirrors how the TUI's `viewModel.ts` keeps its fold logic out of the components: the registry
+ * and the parse/dispatch helpers here are unit-testable in isolation, and each surface is the
+ * only place that turns the resulting {@link SlashCommandResult} into its own state / side
+ * effects (the TUI's `<App>` clears the transcript / pushes notices / quits; the readline loop
+ * prints notices and degrades TUI-only effects with a clear "needs the TUI" message).
+ *
+ * The registry is a plain array so later layers (e.g. extension-registered commands, EXT-5)
+ * can append more entries via {@link createCommandRegistry} without this module changing.
+ */
+import { APPROVAL_POSTURES, APPROVAL_PROTECTION_DOCS_LINES, APPROVAL_RUNG_DESCRIPTIONS, APPROVAL_RUNG_LABELS, APPROVAL_RUNGS, APPROVAL_WRITE_MODIFIER_HINT, isRatedRung, TOOL_ANNOTATION_HINTS, } from '@gaunt-sloth/core/config.js';
+import { describeApprovalEntry } from '@gaunt-sloth/core/core/approvals/matcher.js';
+import { MOUSE_SELECTION_HINT } from '@gaunt-sloth/core/config/mouse.js';
+/**
+ * Build the compact, read-only `/config` summary (GS2-1): a handful of the most orienting
+ * resolved-config fields, one per line, with a pointer to `gth config print` for the full view.
+ * Pure and secret-free — it only reads non-sensitive scalar fields (never API keys / the live
+ * llm instance). Used by the App to fill {@link SlashCommandContext.configSummary}.
+ *
+ * CFG-25 — `filesystem` is a precedence-picked per-command field (GS2-60), so the panel prints the
+ * EFFECTIVE value for the running `command`, read from `config.commands[command].filesystem` —
+ * where the GS2-60 resolution already baked the correct 4-layer precedence — falling back to the
+ * top-level value, exactly the read `getEffectiveConfig` performs (no precedence re-derived here).
+ * When the effective and top-level values differ, both are shown
+ * (`Filesystem: all (code; top-level: none)`) so the top-level default can never understate what
+ * the session can actually do. Of the other precedence-picked fields
+ * (`builtInTools`/`allowedTools`/`binaryFormats`), none are printed by this panel, so none can
+ * misreport the same way.
+ */
+export function formatConfigSummary(config, command) {
+    const fmt = (v) => typeof v === 'string' ? v : Array.isArray(v) ? JSON.stringify(v) : String(v);
+    const lines = [];
+    lines.push(`Model: ${config.modelDisplayName || 'unknown'}`);
+    lines.push(`Agent backend: ${config.agent?.backend ?? 'lean'}`);
+    const commandFilesystem = command
+        ? config.commands?.[command]?.filesystem
+        : undefined;
+    const effectiveFilesystem = commandFilesystem !== undefined ? commandFilesystem : config.filesystem;
+    if (effectiveFilesystem !== undefined) {
+        const differs = commandFilesystem !== undefined &&
+            config.filesystem !== undefined &&
+            fmt(commandFilesystem) !== fmt(config.filesystem);
+        lines.push(differs
+            ? `Filesystem: ${fmt(commandFilesystem)} (${command}; top-level: ${fmt(config.filesystem)})`
+            : `Filesystem: ${fmt(effectiveFilesystem)}`);
+    }
+    if (config.streamOutput !== undefined)
+        lines.push(`Stream output: ${config.streamOutput}`);
+    if (config.useColour !== undefined)
+        lines.push(`Colour: ${config.useColour}`);
+    const commandNames = config.commands ? Object.keys(config.commands) : [];
+    if (commandNames.length > 0)
+        lines.push(`Commands configured: ${commandNames.join(', ')}`);
+    lines.push('Run `gth config print` for the full resolved config (secrets redacted).');
+    return lines;
+}
+/**
+ * The `/config` notice, from the pre-rendered summary lines (or an unavailable fallback).
+ *
+ * TUI-C19 — when config-validation `warnings` are present (unknown keys / deprecated names), they
+ * are rendered FIRST, as the details the standing "config has problems" advisory line points at,
+ * then a blank spacer, then the resolved summary. A clean config (no warnings) reads exactly as
+ * before. Tone flips to `warn` (yellow) while there are warnings so the block reads as caution.
+ */
+export function configNotice(summary, warnings) {
+    const summaryLines = summary && summary.length > 0
+        ? summary
+        : ['Configuration details are not available in this session.'];
+    const hasWarnings = !!warnings && warnings.length > 0;
+    const lines = hasWarnings
+        ? [
+            `${warnings.length === 1 ? 'Config warning' : `Config warnings (${warnings.length})`}:`,
+            ...warnings.map((w) => `  • ${w}`),
+            '',
+            ...summaryLines,
+        ]
+        : summaryLines;
+    return {
+        title: 'Resolved configuration',
+        lines,
+        ...(hasWarnings ? { tone: 'warn' } : {}),
+    };
+}
+/** Shared "history is unavailable" body (history off / DB missing), reused by all three commands. */
+const HISTORY_UNAVAILABLE_LINES = [
+    'No local session history is available in this session.',
+    'Enable it with `history.enabled: true` in your gsloth config (local only, opt-in).',
+];
+/** The `/history` notice (GS2-7): recent recorded sessions, or an "unavailable" fallback. */
+export function historyNotice(summary) {
+    return {
+        title: 'Recent sessions',
+        lines: summary && summary.length > 0 ? summary : HISTORY_UNAVAILABLE_LINES,
+    };
+}
+/** The `/insights` notice (GS2-7): local analytics summary, or an "unavailable" fallback. */
+export function insightsNotice(summary) {
+    return {
+        title: 'Session insights (local only)',
+        lines: summary && summary.length > 0 ? summary : HISTORY_UNAVAILABLE_LINES,
+    };
+}
+/**
+ * The `/search` notice (GS2-7). With no query it prints usage; otherwise it runs the injected
+ * fail-soft {@link SlashCommandContext.historySearch} provider and renders its result lines. When
+ * no provider is bound (no store), it reports history as unavailable.
+ */
+export function searchNotice(args, search) {
+    const query = args.join(' ').trim();
+    if (!query) {
+        return {
+            title: 'Search session history',
+            lines: ['Usage: /search <terms> — full-text search across your recorded sessions.'],
+        };
+    }
+    if (!search) {
+        return { title: `Search: "${query}"`, lines: HISTORY_UNAVAILABLE_LINES };
+    }
+    return { title: `Search: "${query}"`, lines: search(query) };
+}
+/**
+ * Parse a raw input line into a slash command, or `null` if it is not one. A line is a slash
+ * command iff its first non-whitespace character is `/` AND no further `/` appears after the
+ * leading one (GS2-8, Mari's dogfood addendum): a pasted filesystem path like
+ * `/usr/home/bob/test.md` contains later slashes, so it falls through as ordinary prompt text
+ * instead of being swallowed as an unknown command. The name is lower-cased; remaining
+ * whitespace-separated tokens are the args.
+ */
+export function parseSlashCommand(input) {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith('/'))
+        return null;
+    // The `/`-vs-path heuristic: a real command has NO further `/` after the leading one.
+    if (trimmed.indexOf('/', 1) !== -1)
+        return null;
+    const tokens = trimmed.slice(1).split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return null; // a bare "/" is not a command
+    const [name, ...args] = tokens;
+    return { name: name.toLowerCase(), args };
+}
+/**
+ * TUI-C10 — the discovery-menu trigger test. The Ink `<PromptInput>` shows the slash-command menu
+ * while the user is typing a bare command: the raw input is a menu query iff its first character is
+ * `/` and it contains no whitespace yet (once a space is typed the user is entering args, so the
+ * menu closes and normal dispatch takes over). Returns the lower-cased query AFTER the slash (so a
+ * bare `/` yields `''` = "show everything"), or `null` when the input is not a menu trigger.
+ *
+ * Kept pure and next to the registry (like {@link parseSlashCommand}) so the menu's show/hide and
+ * filter logic is unit-testable without React.
+ *
+ * GS2-8 — mirrors {@link parseSlashCommand}'s `/`-vs-path heuristic: input with a later `/`
+ * (a pasted path like `/usr/bin`) is not a command, so it never triggers the menu either.
+ */
+export function slashMenuQuery(input) {
+    if (!/^\/\S*$/.test(input))
+        return null;
+    if (input.indexOf('/', 1) !== -1)
+        return null; // later `/` ⇒ a path, not a command query
+    return input.slice(1).toLowerCase();
+}
+/**
+ * TUI-C10 — filter the registry down to the commands that match a menu query, most-relevant first.
+ * Prefix matches (the name starts with the query) rank above looser substring matches; within each
+ * bucket the registry's own order is preserved (so extension-registered commands — appended to the
+ * array — naturally sort after the built-ins). An empty query returns the whole registry, so a bare
+ * `/` lists every command including any the extensions added (never a hardcoded list).
+ *
+ * Pure: takes the registry the caller already built via {@link createCommandRegistry}, so the menu
+ * automatically reflects extension commands without this layer knowing they exist.
+ */
+export function filterSlashCommands(registry, query) {
+    const q = query.toLowerCase();
+    if (!q)
+        return [...registry];
+    const prefix = registry.filter((c) => c.name.startsWith(q));
+    const substring = registry.filter((c) => !c.name.startsWith(q) && c.name.includes(q));
+    return [...prefix, ...substring];
+}
+/**
+ * The notice for the tool-detail toggle, given the RESULTING (post-toggle) state. Shared by the
+ * `/verbose` command (GS2-8 rename of `/tools`) and the Ctrl+T key handler so the copy
+ * is single-sourced (TUI-C14).
+ */
+export function toolsToggleNotice(expanded) {
+    return expanded
+        ? {
+            title: 'Tool details: on',
+            lines: [
+                'Tool calls now show their full inputs and results in the chat history.',
+                'Applies to the whole conversation on screen — run /verbose again to collapse them.',
+            ],
+        }
+        : {
+            title: 'Tool details: off',
+            lines: [
+                'Tool calls now show as a single summary line in the chat history.',
+                'Applies to the whole conversation on screen — run /verbose again to show the detail.',
+            ],
+        };
+}
+/**
+ * The notice for the debug-panel toggle, given the RESULTING (post-toggle) state. Shared so the
+ * command reports exactly the state the component will apply.
+ */
+export function debugToggleNotice(visible) {
+    return visible
+        ? {
+            title: 'Debug panel: shown',
+            lines: [
+                'Docked panel with the subagent tree and sent-to-model / raw-response views.',
+                'Run /debug again to hide it; Tab cycles its views.',
+            ],
+        }
+        : {
+            title: 'Debug panel: hidden',
+            lines: [
+                'The docked subagent + debug views are now closed.',
+                'Run /debug again to bring them back.',
+            ],
+        };
+}
+/**
+ * CFG-27 — the notice for a landed approvals RUNG, given the RESULTING (post-apply) posture.
+ * Shared so every surface reports exactly the state that was applied, and so the copy can never
+ * drift from what the gate actually does.
+ *
+ * The body of each notice is §10's description, **verbatim** — the one place the ladder is
+ * explained to the user, so it must not be paraphrased per surface. §10 rule 4 also fixes the
+ * label: the display spelling with spaces, never the kebab-case identifier.
+ *
+ * `bypass` is the only warn-toned one: it is the single rung with no gate at all. Note what is
+ * NOT here — the hardline floor. §8.1 forbids advertising it: descriptions name only protections
+ * the user can inspect and extend, which is the deny list.
+ */
+/**
+ * TUI-C37 — feedback for `/mouse`, describing the state the session has LANDED on.
+ *
+ * The selection hint is repeated on every "on" notice rather than shown once at launch, because the
+ * moment a user reaches for `/mouse` is exactly the moment they are trying to copy something and
+ * finding that dragging no longer selects. Telling them there and then is the difference between a
+ * fixed problem and a filed bug.
+ */
+export function mouseToggleNotice(enabled) {
+    return {
+        title: enabled ? 'Mouse on' : 'Mouse off',
+        lines: enabled
+            ? [
+                'Clickable parts of the interface respond to the mouse, and the wheel scrolls the conversation.',
+                // Qualified rather than promised: the binding is correct, but a terminal that never sets
+                // the Shift bit on a wheel report (Konsole is one) delivers a plain notch, so the page
+                // never happens there. Naming a key that silently does nothing is the defect TUI-C11 had
+                // to correct once already.
+                'Shift and the wheel together move a page, in terminals that forward Shift with the wheel.',
+                MOUSE_SELECTION_HINT,
+                'Turn it off for this session with /mouse off, or always with useMouse false in your config.',
+            ]
+            : [
+                'Mouse reporting is off; text selection and copying work exactly as your terminal normally does.',
+                'Turn it back on with /mouse on.',
+            ],
+    };
+}
+/** TUI-C37 — `/mouse` on a surface with no mouse layer (the plain readline session, the fixture). */
+export function mouseUnavailableNotice() {
+    return {
+        title: 'Mouse unavailable',
+        lines: [
+            'This session has no mouse layer, so there is nothing to turn on or off.',
+            'Mouse input needs an interactive terminal running the TUI.',
+        ],
+        tone: 'warn',
+    };
+}
+/**
+ * TUI-C37 — parse `/mouse [on|off]`. No argument means "toggle", which is what a bare command name
+ * usually means; `null` marks an argument that is neither, so the caller can say so rather than
+ * guess. `resolve` needs the current state only for the toggle case.
+ */
+export function parseMouseArg(args, current) {
+    if (args.length === 0)
+        return !current;
+    const arg = args[0].toLowerCase();
+    if (arg === 'on')
+        return true;
+    if (arg === 'off')
+        return false;
+    return null;
+}
+export function approvalsRungNotice(approvals) {
+    const lines = [APPROVAL_RUNG_DESCRIPTIONS[approvals.rung]];
+    if (isRatedRung(approvals.rung) && approvals.rater) {
+        lines.push(`The auto-rater runs under the "${approvals.rater}" identity profile.`);
+    }
+    lines.push('Session-scoped only (not saved); run /approvals to see or change it.');
+    // The moment a user changes posture is the moment the reasoning behind the postures is worth
+    // reading, and two sentences cannot hold it.
+    lines.push(...APPROVAL_PROTECTION_DOCS_LINES);
+    return {
+        title: `Approvals: ${APPROVAL_RUNG_LABELS[approvals.rung]}`,
+        lines,
+        tone: approvals.rung === 'bypass' ? 'warn' : 'info',
+    };
+}
+/**
+ * The first sentence of a mode's description, for the one-line forms (the picker rows and the usage
+ * hint). Cut at the sentence boundary rather than truncated, so a row never ends mid-clause.
+ *
+ * **A sentence ends at `.`, `?` or `!`.** The copy this shortens is ordinary prose, and a helper
+ * that knows only the period renders a question as `Really?.` and hands back BOTH sentences of
+ * `Ready? Then go.` — the whole description in a row sized for one line.
+ *
+ * A terminator only ends the sentence when a space follows it and no dot precedes it, so an
+ * ellipsis reads as the pause it is instead of three sentence boundaries.
+ *
+ * **A description that is already one sentence keeps its own terminator rather than gaining a
+ * second.** Nothing was consumed, so it arrives already terminated and appending unconditionally
+ * would render `No gate..`. Every surface showing one line of a mode's copy goes through here, so
+ * this is the only place that has to know any of it.
+ */
+export function firstSentence(description) {
+    const boundary = /(?<!\.)[.?!](?=\s)/.exec(description);
+    const head = boundary ? description.slice(0, boundary.index + 1) : description;
+    return /[.?!]$/.test(head) ? head : `${head}.`;
+}
+/**
+ * CFG-39 — **the picker's rows**: the four postures, in ladder order, each carrying its own copy.
+ *
+ * **The strings come from {@link APPROVAL_RUNG_DESCRIPTIONS}, never from the menu.** Six surfaces
+ * describe these modes; a picker that authored its own text would become the seventh and the one
+ * that contradicts the rest. Whoever owns that constant owns this copy too, with no second edit.
+ *
+ * `write` has no row — it is a modifier of Manual rather than a fifth posture — but it stays
+ * settable via `/approvals write`. When the session IS on `write`, no row is marked `current`,
+ * which is correct: the caller reports the live mode from its own title rather than letting a
+ * picker row claim the session is on Manual when it is not.
+ */
+export function approvalPostureChoices(current) {
+    return APPROVAL_POSTURES.map((rung) => ({
+        rung,
+        label: APPROVAL_RUNG_LABELS[rung],
+        description: APPROVAL_RUNG_DESCRIPTIONS[rung],
+        current: rung === current,
+    }));
+}
+/**
+ * CFG-39 — the picker as TEXT: the selectable list every non-TTY surface (ACP, AG-UI, the readline
+ * `--no-tui` session, a piped stdout) prints in place of the interactive rows.
+ *
+ * The same {@link approvalPostureChoices} the TTY picker renders, so the two cannot list different
+ * modes or describe them differently — the text fallback is a rendering of the picker, not a
+ * second implementation of it.
+ */
+export function approvalPostureLines(current) {
+    return approvalPostureChoices(current).map((choice) => `${choice.current ? '●' : '○'} ${choice.label} — ${firstSentence(choice.description)}`);
+}
+/**
+ * CFG-27 — the `/approvals` DISPLAY: the mode and its description, the rater profile in the two
+ * rated modes, and the allow/deny list sizes. Pure: the surface reads the live posture from the
+ * runner and hands it in.
+ *
+ * CFG-39 — it also carries the selectable list, so `/approvals` with no argument answers "which
+ * mode am I on?" and "what else could I be on?" in one place on EVERY surface. On a TTY the TUI
+ * renders {@link approvalPostureChoices} as an interactive picker instead; this is what everything
+ * else shows.
+ *
+ * `always: undefined` means the persisted store has not been loaded, and is rendered `—` rather
+ * than a misleading `0` — a display must not create the store in order to count it.
+ */
+export function approvalsStatusNotice(approvals, allowlist, deny = [], grants = [], trust, options = {}) {
+    const rater = isRatedRung(approvals.rung)
+        ? (approvals.rater ?? 'main model')
+        : 'not used in this mode';
+    return {
+        title: `Approvals: ${APPROVAL_RUNG_LABELS[approvals.rung]}`,
+        lines: [
+            APPROVAL_RUNG_DESCRIPTIONS[approvals.rung],
+            `Auto-rater: ${rater}`,
+            `Allowed: ${allowlist.session} this session · ${allowlist.always ?? '—'} remembered · Denied: ${deny.length}`,
+            ...describeGrants(grants),
+            ...(trust ? [describeMcpTrust(trust)] : []),
+            // The docs pointer rides with the mode list, and is absent for the same reason the list is
+            // when a picker is coming: **it is not free to print a URL.** It cannot be shortened without
+            // breaking it, so it wraps, and here it would push the head of an already-long notice off a
+            // short pane — which costs the reader the mode they asked about. A surface that renders the
+            // picker prints this pointer a keystroke later instead, from `approvalsRungNotice`, where the
+            // user has actually chosen something.
+            ...(options.interactive
+                ? []
+                : [
+                    'Choose a mode with /approvals <name>:',
+                    ...approvalPostureLines(approvals.rung),
+                    APPROVAL_WRITE_MODIFIER_HINT,
+                    ...APPROVAL_PROTECTION_DOCS_LINES,
+                ]),
+            TRUST_USAGE_LINE,
+        ],
+        tone: approvals.rung === 'bypass' ? 'warn' : 'info',
+    };
+}
+/** How many grants `/approvals` lists before it summarizes the rest. */
+const GRANT_DISPLAY_LIMIT = 10;
+/**
+ * §3/§4.7.4 — the granted lines of the `/approvals` display: **what** was granted, **when**, and
+ * **under which effective annotations**.
+ *
+ * The annotations are the half that only a tool grant has, and the half §4.7.4 exists for: a grant
+ * is an approval of a tool *as annotated*, so a user asked to believe that has to be able to see
+ * what they believed. Each entry is rendered by `describeApprovalEntry` — the same one-liner the
+ * escalation menu names the grant with and the withdrawal notice names it with.
+ *
+ * **The heading claims no scope**, because the list spans both: `getGrants` reports the persisted
+ * store's `always` grants alongside this session's, and an `always` grant was made in whatever
+ * session the user made it in — often not this one. Each line carries its own scope and the instant
+ * it was granted, which is where that question is answered.
+ */
+function describeGrants(grants) {
+    if (grants.length === 0)
+        return [];
+    const shown = grants.slice(0, GRANT_DISPLAY_LIMIT).map((grant) => {
+        const annotations = grant.annotations
+            ? `, approved as ${TOOL_ANNOTATION_HINTS.map((hint) => `${hint}=${grant.annotations?.[hint]}`).join(' ')}`
+            : '';
+        return `  ${describeApprovalEntry(grant.entry)} — ${grant.scope}, granted ${grant.grantedAt}${annotations}`;
+    });
+    const rest = grants.length - shown.length;
+    return [`Granted approvals:`, ...shown, ...(rest > 0 ? [`  …and ${rest} more.`] : [])];
+}
+/**
+ * §4.7.1 — the one line saying which of each server's annotation hints this session believes.
+ *
+ * A server is listed even when it believes nothing, because "believes nothing" is the default and
+ * the user needs to be able to tell it apart from "this server is not here at all" — the two look
+ * identical when only trusted servers are listed, and the second is what a typo produces.
+ */
+function describeMcpTrust(trust) {
+    const parts = [
+        `defaults — ${trust.defaults.length > 0 ? trust.defaults.join(' ') : 'nothing'}`,
+        ...trust.servers.map((entry) => `${entry.server} — ${entry.trusted.length > 0 ? entry.trusted.join(' ') : 'nothing'}`),
+    ];
+    return `MCP annotations believed: ${parts.join(' · ')}`;
+}
+/** The `/approvals trust` half of the usage copy, shown wherever the rung half is. */
+const TRUST_USAGE_LINE = 'Believe an MCP server’s annotation hints with /approvals trust <server> <hint…>, ' +
+    'and stop believing them with /approvals untrust <server> <hint…>.';
+/**
+ * CFG-27/EXT-70 — parse the `/approvals` argument: no arg SHOWS the current posture; any of the
+ * five mode names switches to it; `trust` / `untrust` move which of a server's annotation hints are
+ * believed (§4.7.1). Returns `null` for an unrecognized first argument so the command renders a
+ * usage hint instead of guessing.
+ *
+ * **All five names are accepted, not the four the picker offers.** `write` is a modifier of
+ * `manual` rather than a posture of its own, so it leaves quick access — but it stays fully
+ * settable here and in config, which is the whole of what "demoted" means.
+ *
+ * The retired `read-only` / `auto-safe` / `full-auto` / `ask` spellings are NOT accepted as
+ * aliases — this is still alpha, and a silent alias would leave the user believing in a vocabulary
+ * the gate no longer has. They are named, with their replacements, by the config-layer error in
+ * `RETIRED_APPROVAL_MODES`.
+ *
+ * **Only the subcommand token is lower-cased.** A server key is the user's own `mcpServers` key
+ * (§4.7.5) and is case-sensitive, so folding it would name a different server — one that believes
+ * nothing, silently, while the notice reported success. A hint is matched case-insensitively
+ * against the fixed vocabulary and echoed back in its **canonical** spelling, so `readonlyhint`
+ * resolves rather than vanishing, and what lands in the policy is the name the derivation reads.
+ */
+export function parseApprovalsArg(args) {
+    if (args.length === 0)
+        return { show: true };
+    const verb = args[0].toLowerCase();
+    const rung = APPROVAL_RUNGS.find((r) => r === verb);
+    if (rung)
+        return { rung };
+    if (verb !== 'trust' && verb !== 'untrust')
+        return null;
+    const believe = verb === 'trust';
+    const server = args[1];
+    if (!server)
+        return { usage: { kind: 'trust-missing-server', believe } };
+    const tokens = args.slice(2);
+    if (tokens.length === 0)
+        return { usage: { kind: 'trust-missing-hints', believe, server } };
+    const hints = [];
+    for (const token of tokens) {
+        const hint = TOOL_ANNOTATION_HINTS.find((h) => h.toLowerCase() === token.toLowerCase());
+        if (!hint)
+            return { usage: { kind: 'unknown-hint', believe, token } };
+        if (!hints.includes(hint))
+            hints.push(hint);
+    }
+    return { trust: { server, hints, believe } };
+}
+/** The verb a notice names an invocation by, so copy never has to branch twice on the same flag. */
+const trustVerb = (believe) => (believe ? 'trust' : 'untrust');
+/**
+ * EXT-70 §4.7.1 — usage copy for a `/approvals trust` invocation that named no server, no hint, or
+ * a hint that is not one of the four. Each says what is missing and shows the vocabulary, because
+ * the hint names are camelCase MCP identifiers nobody guesses.
+ */
+export function approvalsTrustUsageNotice(problem) {
+    const usage = `Usage: /approvals ${trustVerb(problem.believe)} <server> <hint…> — hints are ${TOOL_ANNOTATION_HINTS.join(', ')}.`;
+    const perHint = 'Trust is per hint and per server: you may believe a server’s readOnlyHint while disbelieving ' +
+        'its openWorldHint.';
+    if (problem.kind === 'trust-missing-server') {
+        return {
+            title: `Which server should this ${trustVerb(problem.believe)}?`,
+            lines: [
+                'Name the server by the key you gave it under mcpServers in your config — that is the only ' +
+                    'identity a server has here.',
+                usage,
+                perHint,
+            ],
+            tone: 'warn',
+        };
+    }
+    if (problem.kind === 'trust-missing-hints') {
+        return {
+            title: `Which hints should this ${trustVerb(problem.believe)} for ${problem.server}?`,
+            lines: [`Name at least one hint. Nothing was changed for ${problem.server}.`, usage, perHint],
+            tone: 'warn',
+        };
+    }
+    return {
+        title: `Not an annotation hint: ${problem.token}`,
+        lines: [`Nothing was changed.`, usage, perHint],
+        tone: 'warn',
+    };
+}
+/**
+ * EXT-70 §4.7.1/§4.7.4 — the notice for a landed `/approvals trust` or `/approvals untrust`, built
+ * from what the runner RETURNS rather than from what was asked for, so the copy can only describe
+ * the trust actually in force.
+ *
+ * **The withdrawal half states the consequence where the withdrawal happens.** Ceasing to believe a
+ * hint pushes it back to the MCP fail-closed default, and for `readOnlyHint`, `openWorldHint` and
+ * `destructiveHint` that is a *weakening* — so §4.7.4 will withdraw that server's saved approvals at
+ * the next call, with its own notice. That is the correct direction and is not suppressed; what
+ * would be wrong is for the user to meet it as a surprise three turns later. `idempotentHint` is the
+ * one hint no weakening move names, so withdrawing it invalidates nothing and the line is absent —
+ * which is why the line is driven by the runner's `weakening` list rather than by "was anything
+ * withdrawn".
+ */
+export function approvalsTrustNotice(change) {
+    const believed = change.trusted.length > 0
+        ? `Believed from ${change.server}: ${change.trusted.join(', ')}.`
+        : `Nothing is believed from ${change.server}; every hint takes its fail-closed default.`;
+    const lines = [];
+    if (change.added.length > 0) {
+        lines.push(`Now believing from ${change.server}: ${change.added.join(', ')}.`);
+    }
+    if (change.removed.length > 0) {
+        lines.push(`No longer believing from ${change.server}: ${change.removed.join(', ')}.`);
+    }
+    if (change.added.length === 0 && change.removed.length === 0) {
+        lines.push(`Nothing changed — ${change.server} was already believed on exactly those hints.`);
+    }
+    lines.push(believed);
+    if (change.weakening.length > 0) {
+        const withdrawn = change.weakening.join(', ');
+        // Precise where it can be, a rule where it cannot. Naming the grants is only honest for the
+        // ones this session can actually see weakened right now; for everything else the rule is
+        // stated, because promising a specific withdrawal that then does not happen teaches the user
+        // to disbelieve the notice.
+        lines.push(change.invalidates.length > 0
+            ? `Because ${withdrawn} is no longer believed, ${change.server}'s tools describe themselves ` +
+                'as more dangerous than when you approved them. These saved approvals will be ' +
+                `withdrawn the next time that tool is called, and you will be asked again: ` +
+                `${change.invalidates.join('; ')}.`
+            : `Withdrawing ${withdrawn} can make ${change.server}'s tools describe themselves as more ` +
+                `dangerous than when you approved them, so any saved approval for ${change.server} ` +
+                'made while it was believed is withdrawn the next time that tool is called, and you ' +
+                'are asked again.');
+    }
+    if (!change.configured) {
+        lines.push(`Note: no server is configured under the key "${change.server}". A server is identified by ` +
+            'your own mcpServers key, so check the spelling — policy written for a key nothing uses ' +
+            'has no effect.');
+    }
+    lines.push('A believed hint never grants a server more than the same hint grants a built-in tool.', 'Session-scoped only (not saved); run /approvals to see it.');
+    return {
+        title: `MCP annotations believed: ${change.server}`,
+        lines,
+        tone: change.weakening.length > 0 ? 'warn' : 'info',
+    };
+}
+/**
+ * TUI-C18 — resolve a `/reasoning` invocation against the committed turns' reasoning (in transcript
+ * order, index 0 = turn 1). Pure, so the whole selection + friendly-notice logic is unit-testable
+ * without React:
+ *
+ * - **no arg** → the most recent turn that actually recorded thinking; if none exists, a friendly
+ *   info notice (nothing to show).
+ * - **`<n>`** → turn `n` (1-based). A non-positive / non-integer / out-of-range `n` → a warn notice;
+ *   a valid turn that recorded no thinking → an info notice. Otherwise a `reprintReasoning` request.
+ *
+ * The App renders a `reprintReasoning` result as a fresh reasoning block (reusing the TUI-C15
+ * styling) and a `notice` result via the shared `CommandNotice`.
+ */
+export function resolveReasoning(reasonings, args) {
+    const count = reasonings.length;
+    const has = (i) => (reasonings[i] ?? '').trim().length > 0;
+    if (args.length > 0) {
+        // `Number(...)` (not parseInt) so "2x"/"1.5"/"" don't silently coerce to a valid index.
+        const raw = args[0];
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n < 1 || n > count) {
+            return {
+                notice: {
+                    title: `No turn ${raw}`,
+                    lines: count === 0
+                        ? [
+                            'This session has no committed turns yet.',
+                            'Ask something first, then run /reasoning.',
+                        ]
+                        : [
+                            `Pick a turn between 1 and ${count} (this session has ${count} so far).`,
+                            'Run /reasoning with no number for the most recent turn that recorded thinking.',
+                        ],
+                    tone: 'warn',
+                },
+            };
+        }
+        const idx = n - 1;
+        if (!has(idx)) {
+            return {
+                notice: {
+                    title: `Turn ${n} has no thinking`,
+                    lines: [
+                        `Turn ${n} didn't record a thinking layer (only some models stream one).`,
+                        'Run /reasoning (no number) to jump to the most recent turn that did.',
+                    ],
+                },
+            };
+        }
+        return { reprintReasoning: { reasoning: reasonings[idx], turnNumber: n } };
+    }
+    // No arg: walk back to the most recent turn that recorded thinking.
+    for (let i = count - 1; i >= 0; i--) {
+        if (has(i))
+            return { reprintReasoning: { reasoning: reasonings[i], turnNumber: i + 1 } };
+    }
+    return {
+        notice: {
+            title: 'No thinking to show',
+            lines: [
+                'No turn in this session has recorded a thinking layer yet.',
+                'Reasoning appears for models that stream a thinking / chain-of-thought layer.',
+            ],
+        },
+    };
+}
+/**
+ * `/debug-dump` when no `dumpDebugSession` writer is injected — the fixture agent, or the readline
+ * (`--no-tui`) session, which shares this registry (GS2-8) but has no session archive writer.
+ */
+const DEBUG_DUMP_UNAVAILABLE_LINES = [
+    'No debug-dump writer is available in this session.',
+    'This is only available in a real TUI session (not the fixture agent or the --no-tui fallback).',
+];
+/**
+ * GS2-47 — resolve whether the `/debug-dump` archive should be redacted. ON by default; opt out via
+ * the config (`debugDump.redact: false`) OR the `--unsafe-no-redact` command flag. Any uncertainty
+ * (no/non-object config) defaults to redacting — fail safe. `resolvedConfig` is opaque here, so this
+ * reads the flag structurally without depending on the `GthConfig` type.
+ */
+export function resolveDebugDumpRedact(resolvedConfig, args) {
+    if (args.some((a) => a === '--unsafe-no-redact' || a === '--no-redact'))
+        return false;
+    const debugDump = resolvedConfig?.debugDump;
+    if (debugDump &&
+        typeof debugDump === 'object' &&
+        debugDump.redact === false) {
+        return false;
+    }
+    return true;
+}
+/**
+ * The `/debug-dump` success notice (a standard 3-line CommandNotice — DL-1: no command reads as
+ * "does nothing"). GS2-47 flips the default to REDACTED: when redaction ran (the default) the note
+ * is softened ("secrets redacted; review before sharing") and points at the opt-out. When the user
+ * opted OUT (raw archive) it is the loud, impossible-to-miss UNSANITIZED warning. Colour follows
+ * DL-8 / the tone rule in maintenance/ux-guidelines.md: the safe, redacted default is normal
+ * feedback (no `tone` ⇒ info), while the raw opt-out is caution and so `tone: 'warn'` (yellow) —
+ * mirroring how `approvalsModeNotice` reserves yellow for the dangerous (gate-off) state. Redaction is
+ * best-effort pattern-based, so even the softened note still says review-before-sharing.
+ */
+export function debugDumpNotice(archiveDir, redacted) {
+    if (redacted) {
+        return {
+            title: 'Debug dump written — secrets redacted',
+            lines: [
+                `Archive: ${archiveDir}`,
+                '',
+                'Secrets were redacted (API keys, tokens and auth headers replaced with <redacted>).',
+                'Redaction is best-effort and pattern-based — review before sharing.',
+                '',
+                'To write a raw, unredacted archive: set `debugDump.redact: false` in your gsloth config,',
+                'or run `/debug-dump --unsafe-no-redact`.',
+            ],
+        };
+    }
+    return {
+        title: '⚠️  Debug dump written — UNSANITIZED, review before sharing',
+        lines: [
+            `Archive: ${archiveDir}`,
+            '',
+            'This archive contains the full transcript, resolved config, env info, debug log and git',
+            'state AS-IS — it may include secrets: API keys, tokens, file contents, env vars.',
+            'Review it carefully before sending it anywhere.',
+        ],
+        tone: 'warn',
+    };
+}
+/**
+ * Build the default command registry. Returns a fresh array each call so callers may push
+ * extension commands onto it (EXT-5) without sharing mutable module state.
+ */
+export function createCommandRegistry() {
+    return [
+        {
+            name: 'help',
+            description: 'List available slash commands',
+            // The help body needs the whole registry, so dispatch special-cases `/help` and
+            // calls formatHelp; this stub keeps `/help` listed and self-described.
+            run: () => ({ message: 'Available commands (see /help).' }),
+        },
+        {
+            name: 'clear',
+            description: 'Clear the transcript',
+            // The visible feedback is the <ClearBanner>, which survives the transcript wipe because it
+            // is not a transcript item, so no committed notice here.
+            run: () => ({ clearTranscript: true }),
+        },
+        {
+            name: 'debug',
+            description: 'Toggle the docked subagents + debug panel',
+            availableDuringRun: true,
+            // State-aware: report the notice for the state the toggle will land on (the inverse of now).
+            run: (ctx) => ({ toggleDebug: true, notice: debugToggleNotice(!ctx.debugVisible) }),
+        },
+        {
+            name: 'verbose',
+            description: 'Toggle tool-call detail (collapsed summary ⇄ expanded args/result)',
+            availableDuringRun: true,
+            // State-aware: report the notice for the state the toggle will land on (the inverse of now).
+            run: (ctx) => ({ toggleTools: true, notice: toolsToggleNotice(!ctx.toolsExpanded) }),
+        },
+        {
+            name: 'mouse',
+            // The `/help` line carries the selection hint too, not just the `/mouse` feedback: someone
+            // scanning `/help` because dragging stopped selecting needs the answer where they are looking.
+            description: 'Turn terminal mouse reporting on or off (/mouse on|off; no arg toggles). ' +
+                'While on, hold Shift (Option in some macOS terminals) to select text',
+            availableDuringRun: true,
+            // Available mid-turn deliberately: the reason to reach for this is usually wanting to copy
+            // something off the screen, and that urge does not wait for the run to finish.
+            run: (ctx, args) => {
+                if (ctx.mouseEnabled === undefined)
+                    return { notice: mouseUnavailableNotice() };
+                const target = parseMouseArg(args, ctx.mouseEnabled);
+                if (target === null) {
+                    return {
+                        notice: {
+                            title: `Unknown option: ${args[0]}`,
+                            lines: ['Usage: /mouse [on|off] — with no argument it toggles.'],
+                            tone: 'warn',
+                        },
+                    };
+                }
+                return { setMouse: target, notice: mouseToggleNotice(target) };
+            },
+        },
+        {
+            name: 'approvals',
+            description: 'Show or switch the approvals mode ' +
+                `(/approvals ${APPROVAL_RUNGS.join('|')}; no arg shows it and offers a picker), ` +
+                'or believe an MCP server’s annotation hints (/approvals trust|untrust <server> <hint…>)',
+            // Available mid-turn so the user can change how the run's REMAINING tool calls are handled
+            // (EXT-12's reason, generalized to the rung). The surface owns the runner posture, so it
+            // applies the change and commits the notice for the landed state.
+            //
+            // CFG-27 retired `/auto-approve` and `/bypass-approve` with the three-mode vocabulary they
+            // named. Neither maps onto the ladder honestly — "auto-approve off" had to mean one of two
+            // different rungs — and `/approvals <rung>` says exactly what it will do.
+            availableDuringRun: true,
+            run: (_ctx, args) => {
+                const action = parseApprovalsArg(args);
+                if (action === null) {
+                    return {
+                        notice: {
+                            title: `Unknown option: ${args[0]}`,
+                            lines: [
+                                `Usage: /approvals [${APPROVAL_RUNGS.join('|')}] — with no argument it shows the current mode.`,
+                                ...APPROVAL_RUNGS.map((rung) => `${rung} — ${firstSentence(APPROVAL_RUNG_DESCRIPTIONS[rung])}`),
+                                TRUST_USAGE_LINE,
+                            ],
+                            tone: 'warn',
+                        },
+                    };
+                }
+                // A malformed `trust`/`untrust` is explained rather than applied: nothing is changed, so
+                // the surface has nothing to do and the command answers on its own.
+                if ('usage' in action)
+                    return { notice: approvalsTrustUsageNotice(action.usage) };
+                return { approvals: action };
+            },
+        },
+        {
+            name: 'exit',
+            description: 'Quit the session',
+            run: () => ({ exit: true }),
+        },
+        {
+            name: 'quit',
+            description: 'Quit the session (alias of /exit)',
+            // GS2-8 — an equal-citizen alias, no deprecation: both names quit.
+            run: () => ({ exit: true }),
+        },
+        {
+            name: 'status',
+            description: 'Show session status (mode, model, turns)',
+            availableDuringRun: true,
+            // GS2-8 — absorbs the old `/mode` command: the mode line (and how to change it) now reads
+            // as part of one status block alongside the model and turn count already in context.
+            run: (ctx) => ({
+                notice: {
+                    title: 'Session status',
+                    lines: [
+                        `Mode: ${ctx.mode} — how the agent handles your messages this session.`,
+                        `Model: ${ctx.modelDisplayName || 'unknown'}`,
+                        `Turns so far: ${ctx.turnCount}`,
+                        'Restart with a different subcommand to change the mode (e.g. `gth chat`).',
+                    ],
+                },
+            }),
+        },
+        {
+            name: 'config',
+            description: 'Show the resolved configuration (read-only)',
+            availableDuringRun: true,
+            // Read-only discovery: surface the pre-rendered, secret-free summary the App computed from
+            // the resolved config, prefixed with any load-time validation warnings (TUI-C19 — the
+            // details the standing advisory line points at). Editing lives in `gth init` / the config
+            // file, not here (GS2-1).
+            run: (ctx) => ({ notice: configNotice(ctx.configSummary, ctx.configWarnings) }),
+        },
+        {
+            name: 'history',
+            description: 'Show recent recorded sessions (local, opt-in history)',
+            availableDuringRun: true,
+            // Read-only discovery, mirroring /config: render the App's fail-soft, pre-built summary.
+            run: (ctx) => ({ notice: historyNotice(ctx.historySummary) }),
+        },
+        {
+            name: 'search',
+            description: 'Search recorded session history (/search <terms>)',
+            availableDuringRun: true,
+            // Dynamic query, so it calls the App-injected fail-soft search provider (stubbable in tests).
+            run: (ctx, args) => ({ notice: searchNotice(args, ctx.historySearch) }),
+        },
+        {
+            name: 'insights',
+            description: 'Show local analytics over recorded sessions (tokens, cost, top tools)',
+            availableDuringRun: true,
+            run: (ctx) => ({ notice: insightsNotice(ctx.insightsSummary) }),
+        },
+        {
+            name: 'model',
+            description: 'Show the current model / provider',
+            availableDuringRun: true,
+            run: (ctx) => ({
+                notice: {
+                    title: `Model: ${ctx.modelDisplayName || 'unknown'}`,
+                    lines: [
+                        'This is the model answering your messages this session.',
+                        'Change the default via `gth init` or your gsloth config.',
+                    ],
+                },
+            }),
+        },
+        {
+            name: 'reasoning',
+            description: "Reprint a turn's thinking (/reasoning [n]; no number = latest with thinking)",
+            // Read-only recall of a past turn's thinking — safe to run mid-turn, like /history and /config.
+            availableDuringRun: true,
+            // Pure: resolve the target from the App-provided committed reasonings; the App renders the
+            // reprint (reusing TUI-C15 styling) or the friendly notice.
+            run: (ctx, args) => resolveReasoning(ctx.turnReasonings ?? [], args),
+        },
+        {
+            name: 'debug-dump',
+            description: 'Dump transcript + config + env + debug log to ~/.gsloth/debug-dumps (secrets redacted; --unsafe-no-redact keeps raw)',
+            // Read-only from the transcript/thread's perspective (it only writes a diagnostic archive,
+            // never mutates session state), so it's useful precisely when something is going wrong
+            // mid-turn — mirrors /history, /config, /debug being availableDuringRun.
+            availableDuringRun: true,
+            run: (ctx, args) => {
+                if (!ctx.dumpDebugSession) {
+                    return {
+                        notice: {
+                            title: 'Debug dump unavailable',
+                            lines: DEBUG_DUMP_UNAVAILABLE_LINES,
+                            tone: 'warn',
+                        },
+                    };
+                }
+                // GS2-47 — redact by default; opt out via config `debugDump.redact: false` or the
+                // `--unsafe-no-redact` flag. The resolved flag is threaded into the writer AND picks the
+                // notice (softened when redacted, loud "unsanitized" warning when raw).
+                const redact = resolveDebugDumpRedact(ctx.resolvedConfig, args);
+                const { archiveDir } = ctx.dumpDebugSession({
+                    transcript: ctx.transcript ?? [],
+                    config: ctx.resolvedConfig,
+                    modelDisplayName: ctx.modelDisplayName,
+                    redact,
+                });
+                return { notice: debugDumpNotice(archiveDir, redact) };
+            },
+        },
+    ];
+}
+/**
+ * Build the `/help` notice from a registry: one body line per command (`/name — description`),
+ * followed by the calling surface's own key bindings when it supplies any (TUI-C63).
+ *
+ * The bindings are a PARAMETER, never a constant in this module: `/help` is the reference for the
+ * surface the reader is looking at, and a key that surface does not have is worse than no entry at
+ * all. A surface that passes nothing gets exactly the command list, byte for byte.
+ */
+export function formatHelp(registry, keyBindings = []) {
+    const lines = registry.map((c) => `/${c.name} — ${c.description}`);
+    // One separator row where the commands end and the keys begin. A SPACE, not the empty string: a
+    // sibling <Text> holding '' collapses to nothing in Ink's column, so an empty line here would be
+    // code that claims a gap the screen never draws. Groups below need none — an unindented title
+    // above indented bindings already reads as a group, and this block is long enough already.
+    if (keyBindings.length > 0)
+        lines.push(' ');
+    for (const group of keyBindings) {
+        lines.push(group.title);
+        for (const binding of group.bindings)
+            lines.push(`  ${binding.keys} — ${binding.description}`);
+    }
+    return {
+        // The title states what the block actually contains, so it cannot promise keys to a surface
+        // that has none.
+        title: keyBindings.length > 0 ? 'Slash commands and keys' : 'Slash commands',
+        lines,
+    };
+}
+/**
+ * Dispatch a parsed command against a registry. Unknown commands return a friendly hint
+ * rather than throwing, so the component can render it as a system line and never forward
+ * the text to the model.
+ *
+ * EXT-12 — when `options.duringRun` is set (a turn is streaming), commands that are not marked
+ * {@link SlashCommand.availableDuringRun} are refused with a friendly notice rather than run,
+ * so mid-turn input can only reach the safe, non-mutating commands (`/approvals`, `/verbose`,
+ * `/debug`, …). `/help` is always allowed.
+ */
+export function dispatchSlashCommand(parsed, registry, ctx, options = {}) {
+    if (parsed.name === 'help') {
+        // TUI-C63 — the bindings section comes from the context, so each surface advertises its own
+        // keyboard and only its own.
+        return { notice: formatHelp(registry, ctx.keyBindings) };
+    }
+    const command = registry.find((c) => c.name === parsed.name);
+    if (!command) {
+        return {
+            notice: {
+                title: `Unknown command: /${parsed.name}`,
+                lines: ["That isn't a recognized slash command.", 'Run /help to see everything available.'],
+                tone: 'warn',
+            },
+        };
+    }
+    if (options.duringRun && !command.availableDuringRun) {
+        return {
+            notice: {
+                title: `/${command.name} is not available while the agent is working`,
+                lines: [
+                    'Wait for the current turn to finish, then run it again.',
+                    'Commands like /approvals, /verbose and /debug do work mid-turn.',
+                ],
+                tone: 'warn',
+            },
+        };
+    }
+    return command.run(ctx, parsed.args);
+}
+//# sourceMappingURL=slashCommands.js.map