@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/cli/cliPrompt.js

@@ -1,3 +1,4 @@
+import readline from 'node:readline';
 /**
  * Shared bridge between the REPL's readline interface and modules outside
  * repl.ts that need to (a) write above the prompt without scrambling input,
@@ -19,6 +20,13 @@ export function setActiveReadline(rl) {
 export function getActiveReadline() {
     return activeReadline;
 }
+/**
+ * True while `askChoice` is rendering its raw-mode picker. The REPL's own
+ * keypress handler (shift+tab access-mode cycle) checks this and yields,
+ * so the picker has uncontested control of stdin while it's active.
+ */
+let pickerActive = false;
+export function isPickerActive() { return pickerActive; }
 /**
  * One-shot yes/no question. Returns true only when the user types y/yes
  * (case-insensitive). Returns the supplied default when stdin isn't a TTY
@@ -41,6 +49,312 @@ export function askYesNo(question, defaultValue = false) {
         });
     });
 }
+/**
+ * Surfaced when `askChoice` is called outside an interactive TTY. The tool
+ * wrapper turns this into a tool-call error so the LLM falls back to deciding
+ * itself — silently picking option 1 for the agent in CI / piped runs would
+ * make a load-bearing decision the user never saw.
+ */
+export class NoTTYError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NoTTYError';
+    }
+}
+/**
+ * Surfaced when the user pressed Esc / q / Ctrl+C inside the picker.
+ * The tool wrapper converts this into a tool-call error so the LLM knows
+ * the user declined to commit and can re-plan instead of guessing.
+ */
+export class CancelledChoiceError extends Error {
+    constructor(message = 'ask_user_choice was cancelled by the user before they picked an option.') {
+        super(message);
+        this.name = 'CancelledChoiceError';
+    }
+}
+// --- Pure picker state machine -------------------------------------------
+// Split out as exported pure functions so they're trivial to unit-test
+// without faking a TTY or piping through keypress events. The orchestrator
+// (`askChoice`) only owns the side-effecting bits: wiring stdin keypress
+// events into the reducer and re-rendering the screen.
+/** Synthetic always-on "Other" option appended to every picker. */
+const OTHER_LABEL = 'Other';
+const OTHER_DESCRIPTION = 'Type a free-form answer not listed above';
+export function initPickerState(options, multiSelect, init = {}) {
+    const augmented = [...options, { label: OTHER_LABEL, description: OTHER_DESCRIPTION }];
+    const otherText = init.prefilledOther ?? '';
+    const awaitingOther = otherText.length > 0;
+    // When pre-filled "Other" is requested, position the cursor on the
+    // Other row so a subsequent Esc → re-render lands the user there
+    // (otherwise they'd snap back to row 0 with no explanation).
+    const cursor = awaitingOther
+        ? augmented.length - 1
+        : Math.max(0, Math.min(init.initialCursor ?? 0, augmented.length - 1));
+    return {
+        options: augmented,
+        cursor,
+        multiSelect,
+        selected: new Set(),
+        awaitingOther,
+        otherText,
+        done: false,
+        cancelled: false,
+        result: null,
+    };
+}
+function finalizeWithOther(state, text) {
+    if (state.multiSelect) {
+        const otherIdx = state.options.length - 1;
+        const indices = Array.from(state.selected).sort((a, b) => a - b);
+        const labels = indices.map((i) => (i === otherIdx ? text : state.options[i].label));
+        return { ...state, done: true, result: labels, otherText: text };
+    }
+    return { ...state, done: true, result: text, otherText: text };
+}
+export function reducePicker(state, key) {
+    if (state.done)
+        return state;
+    // Ctrl+C always cancels, in any phase. Don't gate on `key.name === 'c'`
+    // alone — some terminals send the sequence without a named binding.
+    if (key.ctrl && (key.name === 'c' || key.sequence === '')) {
+        return { ...state, done: true, cancelled: true };
+    }
+    // --- Free-text "Other" phase ------------------------------------------
+    if (state.awaitingOther) {
+        if (key.name === 'return' || key.sequence === '\r' || key.sequence === '\n') {
+            const text = state.otherText.trim();
+            if (!text)
+                return state; // empty ENTER is a no-op so the user can retry
+            return finalizeWithOther(state, text);
+        }
+        if (key.name === 'backspace') {
+            return { ...state, otherText: state.otherText.slice(0, -1) };
+        }
+        if (key.name === 'escape') {
+            // Bail back to the picker so a stray ENTER on Other isn't a one-way trip.
+            return { ...state, awaitingOther: false, otherText: '' };
+        }
+        if (key.char && key.char.length === 1) {
+            return { ...state, otherText: state.otherText + key.char };
+        }
+        return state;
+    }
+    // --- Picker phase -----------------------------------------------------
+    switch (key.name) {
+        case 'up':
+            return { ...state, cursor: (state.cursor - 1 + state.options.length) % state.options.length };
+        case 'down':
+            return { ...state, cursor: (state.cursor + 1) % state.options.length };
+        case 'space': {
+            if (!state.multiSelect)
+                return state;
+            const next = new Set(state.selected);
+            if (next.has(state.cursor))
+                next.delete(state.cursor);
+            else
+                next.add(state.cursor);
+            return { ...state, selected: next };
+        }
+        case 'return': {
+            const otherIdx = state.options.length - 1;
+            if (state.multiSelect) {
+                // Confirming with nothing selected is a no-op — the user must SPACE
+                // at least one row first. Bailing here keeps "I pressed ENTER too
+                // soon" from silently committing to an empty array.
+                if (state.selected.size === 0)
+                    return state;
+                if (state.selected.has(otherIdx)) {
+                    return { ...state, awaitingOther: true };
+                }
+                const indices = Array.from(state.selected).sort((a, b) => a - b);
+                return { ...state, done: true, result: indices.map((i) => state.options[i].label) };
+            }
+            if (state.cursor === otherIdx) {
+                return { ...state, awaitingOther: true };
+            }
+            return { ...state, done: true, result: state.options[state.cursor].label };
+        }
+        case 'escape':
+        case 'q':
+            return { ...state, done: true, cancelled: true };
+    }
+    return state;
+}
+export function renderPicker(state, question, header) {
+    const lines = [];
+    if (header)
+        lines.push(`[${header}]`);
+    lines.push(question);
+    lines.push('');
+    for (let i = 0; i < state.options.length; i++) {
+        const opt = state.options[i];
+        const cursor = i === state.cursor ? '▶' : ' ';
+        const mark = state.multiSelect ? (state.selected.has(i) ? '☑ ' : '☐ ') : '';
+        lines.push(`  ${cursor} ${mark}${opt.label}  —  ${opt.description}`);
+    }
+    lines.push('');
+    if (state.awaitingOther) {
+        lines.push('[Other] Type your answer and press ENTER  ·  Backspace to edit  ·  Esc to go back');
+        lines.push(`> ${state.otherText}_`);
+    }
+    else if (state.multiSelect) {
+        lines.push('↑/↓ navigate  ·  SPACE toggle  ·  ENTER confirm  ·  q to cancel');
+    }
+    else {
+        lines.push('↑/↓ navigate  ·  ENTER confirm  ·  q to cancel');
+    }
+    return lines.join('\n');
+}
+export function askChoice(question, options, opts = {}) {
+    // Input-shape validation first — bad shape is a caller bug regardless of
+    // TTY availability, and surfacing it as "no TTY" would misdirect the agent
+    // toward "decide yourself" when the real fix is "re-emit the call with a
+    // valid options array".
+    if (!Array.isArray(options) || options.length < 2 || options.length > 4) {
+        const count = Array.isArray(options) ? options.length : 'invalid';
+        return Promise.reject(new Error(`ask_user_choice requires 2–4 options; received ${count}.`));
+    }
+    // Reject duplicate labels (case-insensitive). The picker shows labels as
+    // the human-readable identifier and returns them as the result, so two
+    // options with the same label make the return value ambiguous and downstream
+    // branching unreliable. Catch it here, not after the picker is half-drawn.
+    // The synthetic "Other" option also collides with a user-supplied "other",
+    // so reject that too.
+    const seen = new Set();
+    for (const o of options) {
+        const key = (o?.label ?? '').toLowerCase();
+        if (key === OTHER_LABEL.toLowerCase()) {
+            return Promise.reject(new Error(`ask_user_choice cannot use "${o.label}" as a label — "${OTHER_LABEL}" is reserved for the always-on free-text fallback.`));
+        }
+        if (seen.has(key)) {
+            return Promise.reject(new Error(`ask_user_choice options must have unique labels; "${o.label}" appears more than once (case-insensitive).`));
+        }
+        seen.add(key);
+    }
+    if (!activeReadline || !process.stdin.isTTY) {
+        return Promise.reject(new NoTTYError('ask_user_choice requires an interactive TTY (no readline interface is active or stdin is not a TTY). ' +
+            'Fall back to deciding yourself based on the available context, and state which option you picked and why in your reply.'));
+    }
+    return runPicker(question, options, opts);
+}
+function runPicker(question, options, opts) {
+    return new Promise((resolve, reject) => {
+        const rl = activeReadline;
+        const stdout = process.stdout;
+        let state = initPickerState(options, !!opts.multiSelect, {
+            prefilledOther: opts.prefilledOther,
+            initialCursor: opts.initialCursor,
+        });
+        let renderedNewlines = 0;
+        let renderedAtLeastOnce = false;
+        // Pause the parent rl so its `line` handler doesn't fire on our ENTER
+        // press. We restore on cleanup.
+        rl.pause();
+        // readline.createInterface already calls emitKeypressEvents and sets raw
+        // mode for a TTY input; this is belt-and-suspenders for cases where the
+        // parent code disabled raw mode somewhere along the way.
+        readline.emitKeypressEvents(process.stdin);
+        try {
+            process.stdin.setRawMode?.(true);
+        }
+        catch { /* not a real TTY */ }
+        process.stdin.resume();
+        // Hide cursor while the picker is on screen — keeps the rendering tight.
+        stdout.write('\x1b[?25l');
+        pickerActive = true;
+        const clear = () => {
+            if (renderedNewlines > 0) {
+                // `\x1b[<n>F` = cursor up n lines AND col 1 (atomic). For an
+                // M-line frame containing M-1 newlines, the cursor sits at
+                // the END of line M after the write (we don't write a
+                // trailing newline). Going up `renderedNewlines` (= M-1)
+                // lines lands EXACTLY at the start of line 1 — no off-by-one.
+                stdout.write(`\x1b[${renderedNewlines}F\x1b[J`);
+            }
+            else if (renderedNewlines === 0 && renderedAtLeastOnce) {
+                // Single-line frame edge case: nothing to scroll up; just
+                // wipe the current line.
+                stdout.write('\r\x1b[K');
+            }
+        };
+        const render = () => {
+            clear();
+            const text = renderPicker(state, question, opts.header);
+            stdout.write(text);
+            // Track newlines (NOT lines). For "a\nb\nc" that's 2 — which
+            // is exactly the cursor-up count we need for the next clear().
+            renderedNewlines = (text.match(/\n/g) ?? []).length;
+            renderedAtLeastOnce = true;
+        };
+        const cleanup = () => {
+            process.stdin.removeListener('keypress', onKeypress);
+            // Restore cursor visibility. Leave raw mode TRUE — the REPL expects it
+            // on (Backspace + arrow keys + readline's editing all rely on raw mode)
+            // and a previous version that restored a captured `wasRaw` flipped raw
+            // mode back to false in terminals where readline's auto-init never
+            // fully engaged, which manifested as Backspace echoing `^?` after the
+            // picker exited. Picker is the one component that's GUARANTEED to know
+            // raw mode is needed, so it's the right place to assert the invariant.
+            stdout.write('\x1b[?25h');
+            try {
+                process.stdin.setRawMode?.(true);
+            }
+            catch { /* noop */ }
+            pickerActive = false;
+            // Don't auto-resume the parent rl — runAgentTurn paused it intentionally
+            // and will resume on its own schedule.
+        };
+        const onKeypress = (str, key) => {
+            const named = key?.name;
+            const isPrintable = typeof str === 'string'
+                && str.length === 1
+                && !key?.ctrl
+                && named !== 'return'
+                && named !== 'escape'
+                && named !== 'backspace'
+                && named !== 'tab';
+            const pk = {
+                name: named,
+                ctrl: !!key?.ctrl,
+                sequence: key?.sequence,
+                char: isPrintable ? str : undefined,
+            };
+            const prevCursor = state.cursor;
+            const wasAwaitingOther = state.awaitingOther;
+            const nextState = reducePicker(state, pk);
+            if (nextState === state)
+                return;
+            state = nextState;
+            // Live-preview hook (0.3.7): fire on a genuine cursor move in the
+            // picker phase only. Don't fire while collecting free-text in the
+            // "Other" phase — that would spam the callback on every keystroke
+            // for no useful signal. Settling back into picker phase from Other
+            // (Esc) doesn't fire either (the cursor "stayed" on Other).
+            if (opts.onCursorChange
+                && !state.done
+                && !state.awaitingOther
+                && !wasAwaitingOther
+                && state.cursor !== prevCursor) {
+                try {
+                    opts.onCursorChange(state.cursor);
+                }
+                catch { /* preview callbacks must never crash the picker */ }
+            }
+            render();
+            if (state.done) {
+                cleanup();
+                if (state.cancelled) {
+                    reject(new CancelledChoiceError());
+                }
+                else {
+                    resolve(state.result);
+                }
+            }
+        };
+        process.stdin.on('keypress', onKeypress);
+        render();
+    });
+}
 /**
  * Print a line of output while the prompt is showing, then redraw the prompt
  * with whatever the user was mid-typing. Used by callbacks that fire while the

package/dist/cli/commands/_context.d.ts

@@ -13,7 +13,7 @@
  */
 import type readline from 'node:readline';
 import type { Agent } from '../../agent/agent.js';
-import type { McpClientWrapper } from '../../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../../runtime/mcpPool.js';
 import type { Config } from '../../config/config.js';
 /**
  * Lifecycle / REPL-scoped state that command handlers can read or mutate.
@@ -24,6 +24,8 @@ import type { Config } from '../../config/config.js';
 export interface ReplContext {
     /** Refresh the readline prompt (color reflects access mode + status segments). */
     refreshPromptForMode: () => void;
+    /** Replace the startup banner in the active chat scrollback, if the UI supports it. */
+    replaceBanner?: (text: string) => void;
     /** True while the REPL is mid-turn; loop ticks should defer when set. */
     isProcessing: () => boolean;
     /** Programmatically run an agent turn (used by /continue and friends). */

package/dist/cli/commands/_helpers.d.ts

@@ -8,7 +8,7 @@
  * wrapper.
  */
 import type { Agent } from '../../agent/agent.js';
-import type { McpClientWrapper } from '../../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../../runtime/mcpPool.js';
 /**
  * Memory-aware variant of printMcpCall. Calls the tool, extracts the flat
  * record list from whatever shape it returns, and renders compact cards

package/dist/cli/commands/_helpers.js

@@ -8,7 +8,7 @@
  * wrapper.
  */
 import chalk from 'chalk';
-import ora from 'ora';
+import { spinner } from '../spinner.js';
 import { callMcpTool } from '../../runtime/mcpUtils.js';
 import { clampPayload, extractMemories, renderMemoryCards } from '../../memory/formatters.js';
 import { buildSkillPrompt, resolveSkill, SLASH_TO_SKILL } from '../../prompt/skillRunner.js';
@@ -19,9 +19,9 @@ import { buildSkillPrompt, resolveSkill, SLASH_TO_SKILL } from '../../prompt/ski
  * raw output only when no records can be parsed.
  */
 export async function printMemoryCards(mcpClient, toolName, args, heading) {
-    const spinner = ora(chalk.gray(`${toolName}…`)).start();
+    const s = spinner(chalk.gray(`${toolName}…`)).start();
     const res = await callMcpTool(mcpClient, toolName, args);
-    spinner.stop();
+    s.stop();
     console.log();
     if (res.isError) {
         console.log(chalk.red(`${heading}: tool error — ${res.text || '(no message)'}`));
@@ -44,9 +44,9 @@ export async function printMemoryCards(mcpClient, toolName, args, heading) {
  * the tool's text output under a heading.
  */
 export async function printMcpCall(mcpClient, toolName, args, heading) {
-    const spinner = ora(chalk.gray(`${toolName}…`)).start();
+    const s = spinner(chalk.gray(`${toolName}…`)).start();
     const res = await callMcpTool(mcpClient, toolName, args);
-    spinner.stop();
+    s.stop();
     console.log(chalk.bold(`\n${heading}`));
     if (res.isError) {
         console.log(chalk.red(`  Tool error: ${res.text || '(no message)'}`));
@@ -113,7 +113,7 @@ export async function runSkillCommand(agent, mcpClient, slashCommand, userInput,
     await runSkillByName(agent, mcpClient, skillName, userInput, orchestration, runTurn);
 }
 export async function runSkillByName(agent, mcpClient, skillName, userInput, orchestration, runTurn) {
-    const loader = ora(chalk.gray(`Loading skill: ${skillName}...`)).start();
+    const loader = spinner(chalk.gray(`Loading skill: ${skillName}...`)).start();
     let prompt;
     try {
         const skill = await resolveSkill(mcpClient, skillName, agent.workspaceRoot, 'full');

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,46 @@
+import type { CommandContext } from './_context.js';
+import { type Theme } from '../theme.js';
+/**
+ * `/config` slash command — 0.3.7 redesign on the new atomic-frame picker
+ * (`../wizard/picker.ts`).
+ *
+ * Verb-overloaded (lifted from
+ * `openSrc/DeepSeek-TUI/crates/tui/src/commands/config.rs:43`):
+ *
+ *   - `/config`              — open the settings home panel
+ *   - `/config <key>`        — print the current value for <key>
+ *   - `/config <key> <val>`  — set <key> to <val> and persist
+ *   - `/config raw|json`     — print scrubbed JSON dump
+ *
+ * Persistence routes through `saveConfig` / `writePreferences` — never
+ * touches JSON files directly so future schema changes stay centralized.
+ */
+export declare function tryHandleConfigCommand(ctx: CommandContext): Promise<boolean>;
+export type ParsedConfigArgs = {
+    mode: 'home';
+} | {
+    mode: 'raw';
+} | {
+    mode: 'get';
+    key: string;
+} | {
+    mode: 'set';
+    key: string;
+    value: string;
+};
+export declare function parseConfigArgs(args: string[]): ParsedConfigArgs;
+export declare function listKnownConfigKeys(): string[];
+export declare function editLlm(ctx: CommandContext): Promise<boolean>;
+/**
+ * Shared prompt for the BrainRouter MCP HTTP API key (the
+ * `BRAINROUTER_API_KEY` bearer token). Pre-fills from the env var if
+ * set, then from the previously-saved key, then blank. Returns:
+ *   - the trimmed key string (possibly empty when user chose "no key")
+ *   - undefined when the user pressed Esc
+ *
+ * Exported so `/login` and any future MCP-setup surfaces share one
+ * prompt copy — same subtitle text, same env-var pre-fill, same
+ * "blank OK" semantics.
+ */
+export declare function promptBrainrouterApiKey(theme: Theme, kind: 'local' | 'remote', existing?: string): Promise<string | undefined>;
+export declare function buildScrubbedConfigJson(config: CommandContext['config']): string;