@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/cli/slashSuggest.d.ts

@@ -0,0 +1,32 @@
+import type readline from 'node:readline';
+import { type Theme } from './theme.js';
+export interface SlashCommand {
+    /** "/help", "/config", etc. — the literal token the user types. */
+    cmd: string;
+    /** One-line description shown after the em-dash. */
+    description: string;
+}
+export interface SlashSuggestController {
+    /** Call after every readline keypress to refresh the popup. */
+    onKey(): void;
+    /** Force-hide the popup (called on submit / cancel). */
+    hide(): void;
+    /** Returns true while the popup is visible. */
+    isVisible(): boolean;
+}
+export interface SlashSuggestOpts {
+    rl: readline.Interface;
+    commands: SlashCommand[];
+    theme?: Theme;
+}
+/**
+ * Two-tier rank for a single command against a query. Lower wins.
+ *
+ *   0  command starts with query (after the leading /)
+ *   1  command contains query
+ *   2  description contains query
+ *   3  no match
+ */
+export declare function scoreSlashCommand(cmd: SlashCommand, query: string): number;
+export declare function filterAndSort(commands: SlashCommand[], query: string): SlashCommand[];
+export declare function createSlashSuggest(opts: SlashSuggestOpts): SlashSuggestController;

package/dist/cli/slashSuggest.js

@@ -0,0 +1,146 @@
+import { buildTheme } from './theme.js';
+/**
+ * 0.3.7 — slash-command autosuggest popup.
+ *
+ * Renders a filtered list of slash commands BELOW the prompt as the
+ * user types. Hides automatically when the input no longer starts
+ * with `/`. Updates on every keystroke.
+ *
+ * Pattern lineage:
+ *   - Two-tier ranking (exact → prefix → includes, lower wins, stable
+ *     secondary sort by original index) lifted from
+ *     `openSrc/grok-cli/src/ui/slash-menu.ts:44-64`.
+ *   - Popup height cap (max ~6 visible) from
+ *     `openSrc/codex/codex-rs/tui/src/bottom_pane/popup_consts.rs`
+ *     and the Claude Code CHANGELOG note (line 378) explicitly
+ *     capping the popup at "3-5 visible commands instead of scaling
+ *     with terminal height."
+ *
+ * Render strategy (kept simple — no scroll-region tricks needed):
+ *
+ *   - On every keystroke we check `rl.line`. If it starts with `/`,
+ *     compute the filtered list and (re)render the popup BELOW the
+ *     current prompt line. The cursor is saved before the popup
+ *     write and restored after — readline's prompt position stays
+ *     untouched.
+ *   - If the popup was previously visible AND should now be hidden
+ *     (input no longer starts with `/`, or no matches), erase the
+ *     popup region with `\x1b[J` from the position one line below
+ *     the prompt.
+ *
+ * The function returns a controller you can wire into the REPL —
+ * call `controller.onKey()` after each readline keypress to refresh.
+ * Call `controller.hide()` on submit / cancel.
+ */
+const MAX_VISIBLE = 6;
+/**
+ * Two-tier rank for a single command against a query. Lower wins.
+ *
+ *   0  command starts with query (after the leading /)
+ *   1  command contains query
+ *   2  description contains query
+ *   3  no match
+ */
+export function scoreSlashCommand(cmd, query) {
+    if (!query)
+        return 0;
+    const q = query.toLowerCase();
+    const cmdBody = cmd.cmd.slice(1).toLowerCase(); // skip the leading /
+    if (cmdBody.startsWith(q))
+        return 0;
+    if (cmdBody.includes(q))
+        return 1;
+    if (cmd.description.toLowerCase().includes(q))
+        return 2;
+    return 3;
+}
+export function filterAndSort(commands, query) {
+    if (!query)
+        return commands.slice(0, MAX_VISIBLE);
+    const scored = commands
+        .map((c, i) => ({ c, i, s: scoreSlashCommand(c, query) }))
+        .filter((x) => x.s < 3);
+    scored.sort((a, b) => (a.s - b.s) || (a.i - b.i)); // stable by original index
+    return scored.slice(0, MAX_VISIBLE).map((x) => x.c);
+}
+export function createSlashSuggest(opts) {
+    const theme = opts.theme ?? buildTheme('dark');
+    const stdout = process.stdout;
+    let lastVisible = false;
+    let lastHeight = 0;
+    let lastQuery = '';
+    const readLine = () => {
+        const rl = opts.rl;
+        return rl.line ?? '';
+    };
+    const erase = () => {
+        if (!lastVisible)
+            return;
+        // Save cursor → move to col 0 of next line → erase from cursor to
+        // end of screen → restore cursor. `\x1b[s` and `\x1b[u` are the
+        // SCO sequences; widely supported.
+        stdout.write('\x1b7'); // DECSC — save cursor + attrs (more reliable than \x1b[s in xterm)
+        stdout.write('\n'); // move down one
+        stdout.write('\r'); // col 0
+        stdout.write('\x1b[J'); // erase from here to end of screen
+        stdout.write('\x1b8'); // DECRC — restore cursor
+        lastVisible = false;
+        lastHeight = 0;
+    };
+    const render = (matches) => {
+        // Pad command column for alignment.
+        const cmdWidth = Math.max(...matches.map((m) => m.cmd.length));
+        const lines = matches.map((m, idx) => {
+            const cmdPart = theme.heading(m.cmd.padEnd(cmdWidth, ' '));
+            const arrow = theme.dim('—');
+            const desc = theme.muted(m.description);
+            // First match gets a `›` marker; others a space.
+            const marker = idx === 0 ? theme.primary('›') : ' ';
+            return `  ${marker} ${cmdPart}  ${arrow}  ${desc}`;
+        });
+        // Hint line under the suggestions.
+        lines.push(theme.dim('    Tab to autocomplete  ·  Enter to submit  ·  type to filter'));
+        // First, erase any previous popup.
+        if (lastVisible) {
+            stdout.write('\x1b7');
+            stdout.write('\n\r\x1b[J');
+            stdout.write('\x1b8');
+        }
+        // Now draw the new popup below the prompt:
+        stdout.write('\x1b7');
+        stdout.write('\n'); // step down to a new line
+        stdout.write('\r');
+        for (let i = 0; i < lines.length; i++) {
+            stdout.write(lines[i]);
+            if (i < lines.length - 1)
+                stdout.write('\n\r');
+        }
+        stdout.write('\x1b8'); // restore cursor to the prompt input position
+        lastVisible = true;
+        lastHeight = lines.length;
+    };
+    return {
+        onKey: () => {
+            const line = readLine();
+            if (!line.startsWith('/')) {
+                if (lastVisible)
+                    erase();
+                lastQuery = '';
+                return;
+            }
+            const query = line.slice(1);
+            if (query === lastQuery && lastVisible)
+                return; // no-op
+            lastQuery = query;
+            const matches = filterAndSort(opts.commands, query);
+            if (matches.length === 0) {
+                if (lastVisible)
+                    erase();
+                return;
+            }
+            render(matches);
+        },
+        hide: () => { erase(); lastQuery = ''; },
+        isVisible: () => lastVisible,
+    };
+}

package/dist/cli/spinner.d.ts

@@ -0,0 +1,34 @@
+import { type Options, type Ora } from 'ora';
+/**
+ * Project-wide spinner factory. **Never** use `ora()` directly — always go
+ * through this.
+ *
+ * `ora`'s default is `discardStdin: true`, which on every `.start()` invokes
+ * the `stdin-discarder` dep (`process.stdin.setRawMode(true)` + add a noop
+ * `data` listener + `process.stdin.resume()`), and on every `.stop()` /
+ * `.succeed()` / `.fail()` does the inverse (`off` listener +
+ * `process.stdin.pause()` + `process.stdin.setRawMode(false)`).
+ *
+ * The pause + raw-mode-false on stop is the load-bearing problem: the
+ * brainrouter REPL's readline interface inherits that state, so after a
+ * slash command that used a spinner (`/working`, `/handover`, `/explain`,
+ * `/diagnostics`, `/forget`, `/persona`, `/skill-hints`, etc.) the prompt
+ * looks alive but stdin is paused + cooked. Symptoms: Backspace echoes
+ * `^?`, arrow keys echo `^[[A`, ENTER doesn't submit. Same class of bug
+ * as the latent setRawMode(false) PR #30 removed at REPL startup, just
+ * triggered per-spinner-stop instead of per-process-start.
+ *
+ * The agent turn (`runAgentTurn`) hides the symptom for most paths because
+ * it brackets the whole turn in `rl.pause()` / `rl.resume()` — `rl.resume()`
+ * re-engages raw mode via readline's internal `input._setRawMode(true)`.
+ * Slash commands run outside that bracket, so the breakage surfaces there.
+ * `ask_user_choice` pickers also show it after the picker cleanup hands
+ * back to subsequent ora events that pause stdin again before the parent
+ * turn's resume runs.
+ *
+ * `discardStdin: false` skips the entire stdin-discarder dance. The spinner
+ * still renders identically; only the side effects are gone. No readline
+ * plumbing changes, no `rl.pause()` / `rl.resume()` bracket needed at the
+ * call sites — this is the right place to fix it.
+ */
+export declare function spinner(text: string, options?: Omit<Options, 'text' | 'discardStdin'>): Ora;

package/dist/cli/spinner.js

@@ -0,0 +1,36 @@
+import ora from 'ora';
+/**
+ * Project-wide spinner factory. **Never** use `ora()` directly — always go
+ * through this.
+ *
+ * `ora`'s default is `discardStdin: true`, which on every `.start()` invokes
+ * the `stdin-discarder` dep (`process.stdin.setRawMode(true)` + add a noop
+ * `data` listener + `process.stdin.resume()`), and on every `.stop()` /
+ * `.succeed()` / `.fail()` does the inverse (`off` listener +
+ * `process.stdin.pause()` + `process.stdin.setRawMode(false)`).
+ *
+ * The pause + raw-mode-false on stop is the load-bearing problem: the
+ * brainrouter REPL's readline interface inherits that state, so after a
+ * slash command that used a spinner (`/working`, `/handover`, `/explain`,
+ * `/diagnostics`, `/forget`, `/persona`, `/skill-hints`, etc.) the prompt
+ * looks alive but stdin is paused + cooked. Symptoms: Backspace echoes
+ * `^?`, arrow keys echo `^[[A`, ENTER doesn't submit. Same class of bug
+ * as the latent setRawMode(false) PR #30 removed at REPL startup, just
+ * triggered per-spinner-stop instead of per-process-start.
+ *
+ * The agent turn (`runAgentTurn`) hides the symptom for most paths because
+ * it brackets the whole turn in `rl.pause()` / `rl.resume()` — `rl.resume()`
+ * re-engages raw mode via readline's internal `input._setRawMode(true)`.
+ * Slash commands run outside that bracket, so the breakage surfaces there.
+ * `ask_user_choice` pickers also show it after the picker cleanup hands
+ * back to subsequent ora events that pause stdin again before the parent
+ * turn's resume runs.
+ *
+ * `discardStdin: false` skips the entire stdin-discarder dance. The spinner
+ * still renders identically; only the side effects are gone. No readline
+ * plumbing changes, no `rl.pause()` / `rl.resume()` bracket needed at the
+ * call sites — this is the right place to fix it.
+ */
+export function spinner(text, options = {}) {
+    return ora({ ...options, text, discardStdin: false });
+}

package/dist/cli/statusline.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Status-line segment renderers. Each segment is a pure-ish function from
+ * (Inputs) → string|undefined; the prompt builder joins the non-empty
+ * results with " · " and wraps them in the access-mode color.
+ *
+ * Why split this out from repl.ts? The 0.3.6 redesign adds workflow / goal /
+ * plan / pr segments, so the inline switch in repl.ts was about to grow
+ * past readable. Putting one function per segment keeps each rule small
+ * AND makes the segment set unit-testable without booting a REPL.
+ *
+ * Segments deliberately stay narrow:
+ *   - `mode`     — access mode (read/write/shell)
+ *   - `exec`     — execution mode (fast); hidden when planning (the default)
+ *   - `effort`   — reasoning depth (low / high); hidden when medium (the default)
+ *   - `model`    — chat-LLM model name
+ *   - `tokens`   — last turn's input/output tokens, only when calls > 0
+ *   - `session`  — first ~22 chars of the sessionKey
+ *   - `branch`   — git branch, only when in a git repo
+ *   - `dirty`    — `*` when the working tree has uncommitted changes
+ *   - `pr`       — github PR identifier (cached upstream of this helper)
+ *   - `workflow` — current workflow slug if any
+ *   - `goal`     — goal status + budget usage if any
+ *   - `plan`     — completed/total plan items if a plan exists
+ *
+ * Note on segment naming: `mode` is the existing access-mode segment
+ * (read/write/shell), kept under that name so user preference files like
+ * `statusline: "mode,model"` keep working. The new execution-mode segment
+ * is `exec` (fast / hidden-when-planning) to avoid colliding with `mode`
+ * — `/mode` the command and `mode` the segment are deliberately decoupled.
+ */
+export declare const SEGMENT_NAMES: readonly ["mode", "exec", "effort", "model", "tokens", "session", "branch", "dirty", "pr", "workflow", "goal", "plan", "brain"];
+export type SegmentName = typeof SEGMENT_NAMES[number];
+export interface SegmentInputs {
+    workspaceRoot: string;
+    sessionKey: string;
+    accessMode: string;
+    model: string;
+    lastTurnUsage: {
+        calls: number;
+        promptTokens: number;
+        completionTokens: number;
+    };
+    /** Optional GitHub PR identifier (e.g. "#42"). REPL caches the gh shell-out, so this is precomputed. */
+    prDetector?: () => string | null;
+    /**
+     * 10c: brain-status detector (renders `brain` segment). REPL wires this
+     * up by closing over the live `mcpClient.isConnected()` +
+     * `mcpClient.getIdentity()` calls. Returns `'online'` / `'offline'` /
+     * `'degraded'` when the active MCP is the BrainRouter brain, and
+     * `undefined` otherwise so the segment hides for third-party MCPs.
+     */
+    brainStatus?: () => 'online' | 'offline' | 'degraded' | undefined;
+}
+export declare function isKnownSegment(name: string): name is SegmentName;
+/**
+ * Render a single segment. Returns undefined when the segment has nothing
+ * worth showing (e.g. `tokens` before the first turn, `branch` outside a
+ * git repo, `goal` with no goal set). Callers should filter undefined out
+ * before joining with separators.
+ */
+export declare function renderSegment(name: SegmentName, inputs: SegmentInputs): string | undefined;
+/**
+ * Render an ordered list of segments, dropping the ones that have nothing
+ * to show. Returns a flat array of strings the caller joins with its own
+ * separator + color treatment.
+ */
+export declare function renderSegments(names: readonly SegmentName[], inputs: SegmentInputs): string[];

package/dist/cli/statusline.js

@@ -0,0 +1,204 @@
+import { execSync } from 'node:child_process';
+import { formatBudget, readGoal } from '../state/goalStore.js';
+import { readPlan } from '../state/taskStore.js';
+import { getCurrentWorkflow } from '../state/workflowArtifacts.js';
+import { readPreferences, resolveEffort } from '../state/preferencesStore.js';
+/**
+ * Status-line segment renderers. Each segment is a pure-ish function from
+ * (Inputs) → string|undefined; the prompt builder joins the non-empty
+ * results with " · " and wraps them in the access-mode color.
+ *
+ * Why split this out from repl.ts? The 0.3.6 redesign adds workflow / goal /
+ * plan / pr segments, so the inline switch in repl.ts was about to grow
+ * past readable. Putting one function per segment keeps each rule small
+ * AND makes the segment set unit-testable without booting a REPL.
+ *
+ * Segments deliberately stay narrow:
+ *   - `mode`     — access mode (read/write/shell)
+ *   - `exec`     — execution mode (fast); hidden when planning (the default)
+ *   - `effort`   — reasoning depth (low / high); hidden when medium (the default)
+ *   - `model`    — chat-LLM model name
+ *   - `tokens`   — last turn's input/output tokens, only when calls > 0
+ *   - `session`  — first ~22 chars of the sessionKey
+ *   - `branch`   — git branch, only when in a git repo
+ *   - `dirty`    — `*` when the working tree has uncommitted changes
+ *   - `pr`       — github PR identifier (cached upstream of this helper)
+ *   - `workflow` — current workflow slug if any
+ *   - `goal`     — goal status + budget usage if any
+ *   - `plan`     — completed/total plan items if a plan exists
+ *
+ * Note on segment naming: `mode` is the existing access-mode segment
+ * (read/write/shell), kept under that name so user preference files like
+ * `statusline: "mode,model"` keep working. The new execution-mode segment
+ * is `exec` (fast / hidden-when-planning) to avoid colliding with `mode`
+ * — `/mode` the command and `mode` the segment are deliberately decoupled.
+ */
+export const SEGMENT_NAMES = [
+    'mode',
+    'exec',
+    'effort',
+    'model',
+    'tokens',
+    'session',
+    'branch',
+    'dirty',
+    'pr',
+    'workflow',
+    'goal',
+    'plan',
+    'brain',
+];
+export function isKnownSegment(name) {
+    return SEGMENT_NAMES.includes(name);
+}
+/**
+ * Render a single segment. Returns undefined when the segment has nothing
+ * worth showing (e.g. `tokens` before the first turn, `branch` outside a
+ * git repo, `goal` with no goal set). Callers should filter undefined out
+ * before joining with separators.
+ */
+export function renderSegment(name, inputs) {
+    switch (name) {
+        case 'mode':
+            return inputs.accessMode;
+        case 'exec': {
+            // Show `fast` only — `planning` is the default, and surfacing it would
+            // add chrome on every prompt for users who never touched /mode.
+            try {
+                const { executionMode } = readPreferences(inputs.workspaceRoot);
+                return executionMode === 'fast' ? 'fast' : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        case 'effort': {
+            // Mirror the `exec` "show only when non-default" rule. `medium` is the
+            // default and would just add chrome on every prompt for users who never
+            // touched /effort.
+            try {
+                const resolved = resolveEffort(inputs.workspaceRoot);
+                if (resolved.effort === 'medium')
+                    return undefined;
+                return `effort:${resolved.effort}`;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        case 'model':
+            return inputs.model;
+        case 'tokens': {
+            const u = inputs.lastTurnUsage;
+            if (u.calls <= 0)
+                return undefined;
+            return `${u.promptTokens}↑${u.completionTokens}↓`;
+        }
+        case 'session': {
+            const k = inputs.sessionKey;
+            return k.length > 22 ? `${k.slice(0, 22)}…` : k;
+        }
+        case 'branch':
+        case 'dirty': {
+            try {
+                const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+                    cwd: inputs.workspaceRoot,
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                }).toString().trim();
+                if (name === 'branch')
+                    return branch;
+                // dirty: only emit "*" when changes are present; quiet otherwise.
+                const dirty = execSync('git status --porcelain', {
+                    cwd: inputs.workspaceRoot,
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                }).toString().trim() !== '';
+                return dirty ? '*' : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        case 'pr':
+            return inputs.prDetector?.() ?? undefined;
+        case 'workflow': {
+            // The workflow segment is a pure navigation indicator: "which
+            // workflow folder is this session writing artifacts to right now?"
+            // Post-goal/workflow-decoupling (0.3.6) it does NOT carry a goal
+            // status suffix — goals live at session scope (the `goal` segment),
+            // workflows live at folder scope. Two orthogonal concerns.
+            try {
+                const slug = getCurrentWorkflow(inputs.workspaceRoot, inputs.sessionKey);
+                if (!slug)
+                    return undefined;
+                return `wf:${slug}`;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        case 'goal': {
+            try {
+                const goal = readGoal(inputs.workspaceRoot, inputs.sessionKey);
+                if (!goal)
+                    return undefined;
+                const cap = formatBudget(goal.budget.maxIterations);
+                const used = goal.budget.iterationsUsed;
+                const statusLabel = goal.status === 'usage_limited' ? 'limited' : goal.status;
+                // Active goals get the iteration ratio; terminal states stay terse.
+                if (goal.status === 'active')
+                    return `goal:${statusLabel} ${used}/${cap}`;
+                return `goal:${statusLabel}`;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        case 'plan': {
+            try {
+                const plan = readPlan(inputs.workspaceRoot, inputs.sessionKey);
+                if (!plan.items.length)
+                    return undefined;
+                const done = plan.items.filter((i) => i.status === 'completed').length;
+                return `plan:${done}/${plan.items.length}`;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        case 'brain': {
+            // 10c: only render when the active MCP is identified as BrainRouter
+            // AND its state is non-default. The `brainStatus` detector returns
+            // `undefined` for third-party MCPs (no brain to surface) and for
+            // BrainRouter-online (default state — hide-when-default mirrors the
+            // `exec` + `effort` pattern). Visible states: `offline` (red signal),
+            // `degraded` (yellow signal — 10d local-only fallback).
+            try {
+                const state = inputs.brainStatus?.();
+                if (!state || state === 'online')
+                    return undefined;
+                if (state === 'offline')
+                    return 'brain:🔴';
+                if (state === 'degraded')
+                    return 'brain:🟡';
+                return undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+}
+/**
+ * Render an ordered list of segments, dropping the ones that have nothing
+ * to show. Returns a flat array of strings the caller joins with its own
+ * separator + color treatment.
+ */
+export function renderSegments(names, inputs) {
+    const out = [];
+    for (const name of names) {
+        const rendered = renderSegment(name, inputs);
+        if (rendered)
+            out.push(rendered);
+    }
+    return out;
+}

package/dist/cli/theme.d.ts

@@ -0,0 +1,79 @@
+import { type ChalkInstance } from 'chalk';
+/**
+ * Consolidated terminal theme tokens.
+ *
+ * Before this module, chalk hex/named colors were sprinkled across every
+ * command file — `chalk.hex('#CC9166')` here, `chalk.green` there. Two
+ * problems with that: (1) the orange that worked beautifully on a black
+ * terminal washed out on a light terminal so users on solarized-light
+ * couldn't read the prompt at all; (2) any "let's tone down the chrome"
+ * pass required grepping the entire CLI for chalk calls.
+ *
+ * The fix is a single source of truth. Every visible surface that needs
+ * color reaches for a SEMANTIC token (primary, success, danger, …) instead
+ * of a raw chalk call. Three palettes ship in-tree:
+ *
+ *   - `dark`  — original Midnight Ledger / Obsidian Surface (matches what
+ *               the CLI has rendered since 0.3.x). Default.
+ *   - `light` — darker accents + bolder weights so the palette stays
+ *               legible on white terminals (solarized-light, GitHub light,
+ *               Apple Terminal "Basic").
+ *   - `mono`  — pure identity functions; no ANSI color, just text. For
+ *               screenshot grabs, CI logs, and pipe-to-less.
+ *
+ * Selection order: `BRAINROUTER_THEME` env var > workspace preferences
+ * (`preferences.theme`) > `dark`. `auto` falls back to `dark` for now —
+ * autodetecting light terminals from TTY hints is unreliable enough that
+ * we leave it to the user to be explicit.
+ *
+ * Inspired by DeepSeek-TUI's `palette.rs` (see openSrc/DeepSeek-TUI/crates/tui/src/palette.rs),
+ * which centralizes its terminal color tokens for the same reason.
+ */
+export type ThemeMode = 'dark' | 'light' | 'mono';
+export interface Theme {
+    readonly mode: ThemeMode;
+    /** Brand accent — used for the banner header, "brainrouter>" prompt, key callouts. */
+    readonly primary: ChalkInstance;
+    /** Secondary accent — supporting brand color (e.g. agent role tags). */
+    readonly secondary: ChalkInstance;
+    /** Successful operation (✓ tool completed, ✔ saved). */
+    readonly success: ChalkInstance;
+    /** Recoverable warning (offline mode, missing config). */
+    readonly warning: ChalkInstance;
+    /** Failure or destructive action (✗ tool failed, dangerous shell). */
+    readonly danger: ChalkInstance;
+    /** Neutral informational hint (cyan-ish in the dark palette). */
+    readonly info: ChalkInstance;
+    /** De-emphasized body text — most chrome lives here. */
+    readonly muted: ChalkInstance;
+    /** Maximally de-emphasized — borders, separators, "less important than muted". */
+    readonly dim: ChalkInstance;
+    /** Bold heading text (banner title, /help category headers). */
+    readonly heading: ChalkInstance;
+    /** Identity — no styling. Used for verbatim payloads where ANSI would corrupt copy/paste. */
+    readonly plain: ChalkInstance;
+}
+export declare function buildTheme(mode: ThemeMode): Theme;
+/**
+ * Resolve the active theme using env-var > preference > default precedence.
+ * Pass `workspaceRoot` to honor a per-workspace `/theme` setting; omit to
+ * resolve from env only (useful in test helpers where preferences storage
+ * might not be initialized).
+ */
+export declare function resolveTheme(workspaceRoot?: string): Theme;
+/**
+ * Box-drawing characters for the startup banner and /where view. Centralized
+ * so a future ASCII-only fallback (for terminals that mangle UTF-8 box chars)
+ * is one switch instead of a sweep through render code.
+ */
+export declare const BOX: {
+    readonly topLeft: "╭";
+    readonly topRight: "╮";
+    readonly bottomLeft: "╰";
+    readonly bottomRight: "╯";
+    readonly horizontal: "─";
+    readonly vertical: "│";
+    readonly midLeft: "├";
+    readonly midRight: "┤";
+    readonly cross: "┼";
+};