@kinqs/brainrouter-cli 0.3.5 → 0.3.6

package/dist/cli/banner.d.ts

@@ -0,0 +1,60 @@
+import type { Config } from '../config/config.js';
+import type { Goal } from '../state/goalStore.js';
+import { type Theme } from './theme.js';
+export interface BannerInputs {
+    workspaceRoot: string;
+    /** "local-http", "stdio", "custom" — config.activeServer. */
+    mcpProfile: string;
+    /** "stdio" | "http". */
+    mcpTransport: string;
+    /** True when the MCP handshake succeeded. */
+    mcpOnline: boolean;
+    /**
+     * 10c: which MCP this profile actually IS — drives the distinct "brain"
+     * row when the active MCP is BrainRouter (or unknown, which we treat as
+     * "likely brain"). When the active MCP is explicitly third-party, the
+     * brain row is omitted entirely so the box stays compact.
+     */
+    mcpIdentity?: 'brainrouter' | 'third-party' | 'unknown';
+    /** Resolved sessionKey for this CLI process. */
+    sessionKey: string;
+    /** Chat-LLM model name (e.g. gpt-4o-mini). */
+    model: string;
+    /** Slug + status of the currently-bound workflow, if any. */
+    workflow?: {
+        slug: string;
+        status: string;
+    };
+    /**
+     * Slug of the last workflow that was active in this workspace, surfaced
+     * only when the current session has NO workflow bound. Rendered as a
+     * one-line hint so the user can `/workflow switch <slug>` to resume.
+     * Doesn't auto-bind anything — workflows are pure storage now (goals
+     * are session-scoped runtime state). Empty / matching the active
+     * workflow → no hint row.
+     */
+    lastUsedWorkflow?: string;
+    /** Goal-store snapshot, if any. */
+    goal?: Goal;
+    /** Version override (test fixture). */
+    version?: string;
+}
+/**
+ * Pure renderer — returns the box as a single newline-joined string with
+ * ANSI sequences from `theme`. Caller appends the trailing newline.
+ */
+export declare function renderBanner(inputs: BannerInputs, theme: Theme): string;
+/**
+ * Convenience: assemble the inputs from live agent + config + workspace
+ * state. Pure read; no side effects. Anything that throws while reading the
+ * goal or current-workflow files is treated as "not set" so a half-set-up
+ * workspace doesn't crash the banner.
+ */
+export declare function buildBannerInputs(config: Config, agent: {
+    sessionKey: string;
+    workspaceRoot: string;
+    getModel: () => string;
+}, mcpClient: {
+    isConnected: () => boolean;
+    getIdentity?: () => 'brainrouter' | 'third-party' | 'unknown';
+}): BannerInputs;

package/dist/cli/banner.js

@@ -0,0 +1,199 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { formatBudget } from '../state/goalStore.js';
+import { getCurrentWorkflow, getLastUsedWorkflow } from '../state/workflowArtifacts.js';
+import { readGoal } from '../state/goalStore.js';
+import { BOX } from './theme.js';
+/**
+ * Compose the boxed startup banner. Replaces the prior three-line text dump
+ * (chalk title + workspace line + connecting-to line) with a single visually
+ * scannable block:
+ *
+ *   ╭─ 🧠 BrainRouter CLI 0.3.5 ──────────────────────────────╮
+ *   │ workspace  BrainRouter  ·  c5b8c12d                     │
+ *   │ mcp        local-http  ·  http  ·  online               │
+ *   │ workflow   cli-shell-redesign  (in-progress)            │
+ *   │ goal       active 3 of unlimited iterations             │
+ *   │ session    7f3a1e0c                                     │
+ *   │ model      gpt-4o-mini                                  │
+ *   ╰─────────────────────────────────────────────────────────╯
+ *
+ * Designed so a glance tells the user where they are: which repo, which MCP
+ * profile, what's the in-flight goal, which model is running. Anything not
+ * applicable (e.g. no goal set, no current workflow) is silently omitted —
+ * the box shrinks to fit instead of showing "—" placeholders.
+ *
+ * The function returns a single string with embedded ANSI; the caller prints
+ * it once. Pure-function so tests can assert against the rendered output.
+ */
+const VERSION = '0.3.6';
+const TITLE = '🧠 BrainRouter CLI';
+const MIN_WIDTH = 56;
+const MAX_WIDTH = 100;
+function shortHash(absPath) {
+    return crypto.createHash('sha1').update(absPath).digest('hex').slice(0, 8);
+}
+function formatGoalSummary(goal) {
+    const cap = formatBudget(goal.budget.maxIterations);
+    const used = goal.budget.iterationsUsed;
+    // Status verbs read naturally inline. "usage_limited" → "limited".
+    const statusWord = goal.status === 'usage_limited' ? 'limited' :
+        goal.status === 'active' ? 'active' :
+            goal.status;
+    if (goal.status === 'complete')
+        return 'complete';
+    if (goal.status === 'blocked')
+        return `blocked — ${goal.blockedReason?.slice(0, 40) ?? 'see /goal'}`;
+    return `${statusWord} ${used} of ${cap} iterations`;
+}
+/**
+ * Workspace label — basename of the workspace root, with a short hash so
+ * two repos with the same basename (e.g. two clones of "playground") don't
+ * look identical.
+ */
+function formatWorkspace(workspaceRoot) {
+    const base = path.basename(workspaceRoot) || workspaceRoot;
+    return `${base}  ·  ${shortHash(workspaceRoot)}`;
+}
+function formatMcp(profile, transport, online) {
+    const dot = online ? 'online' : 'offline';
+    return `${profile}  ·  ${transport}  ·  ${dot}`;
+}
+/**
+ * 10c: brain row — distinct from the generic MCP row so the user can tell
+ * "the BrainRouter cloud brain is down" from "a third-party MCP is down".
+ * Renders only when the active MCP is BrainRouter (or unknown). Returns
+ * `undefined` when there's nothing meaningful to say (e.g. user only has a
+ * third-party MCP connected).
+ */
+function formatBrain(identity, online) {
+    if (identity === 'third-party')
+        return undefined;
+    if (identity === 'unknown')
+        return undefined; // wait for tool-signature detection
+    if (online)
+        return '🟢 online';
+    return '🔴 offline · cloud unreachable';
+}
+function formatWorkflow(workflow) {
+    if (!workflow)
+        return undefined;
+    return `${workflow.slug}  (${workflow.status})`;
+}
+function clipValue(value, width) {
+    if (value.length <= width)
+        return value;
+    if (width <= 1)
+        return value.slice(0, width);
+    return value.slice(0, width - 1) + '…';
+}
+function padRight(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+/**
+ * Pure renderer — returns the box as a single newline-joined string with
+ * ANSI sequences from `theme`. Caller appends the trailing newline.
+ */
+export function renderBanner(inputs, theme) {
+    const rows = [];
+    rows.push({ label: 'workspace', value: formatWorkspace(inputs.workspaceRoot) });
+    rows.push({ label: 'mcp', value: formatMcp(inputs.mcpProfile, inputs.mcpTransport, inputs.mcpOnline) });
+    // 10c: brain status sits below the mcp row — same level of visibility,
+    // but distinct so multi-MCP setups (Item 11) won't be ambiguous.
+    const brain = formatBrain(inputs.mcpIdentity, inputs.mcpOnline);
+    if (brain)
+        rows.push({ label: 'brain', value: brain });
+    const wf = formatWorkflow(inputs.workflow);
+    if (wf) {
+        rows.push({ label: 'workflow', value: wf });
+    }
+    else if (inputs.lastUsedWorkflow) {
+        // Fresh session with no current workflow but a known last-used
+        // workflow in this workspace — offer the resume incantation without
+        // auto-binding. Quiet so the user notices but isn't pushed into it.
+        rows.push({ label: 'last on', value: `${inputs.lastUsedWorkflow}   /workflow switch ${inputs.lastUsedWorkflow}` });
+    }
+    if (inputs.goal)
+        rows.push({ label: 'goal', value: formatGoalSummary(inputs.goal) });
+    rows.push({ label: 'session', value: inputs.sessionKey.slice(0, 8) });
+    rows.push({ label: 'model', value: inputs.model });
+    const version = inputs.version ?? VERSION;
+    const titleText = `${TITLE} ${version}`;
+    const labelWidth = rows.reduce((w, r) => Math.max(w, r.label.length), 0);
+    // Inner width is the widest "label + 2 spaces + value", clamped.
+    const naturalInner = rows.reduce((w, r) => Math.max(w, labelWidth + 2 + r.value.length), titleText.length + 4);
+    const targetCols = process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : MAX_WIDTH;
+    // Reserve 2 columns for the side borders.
+    const innerWidth = Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, Math.min(naturalInner, targetCols - 2)));
+    const top = (() => {
+        // ╭─ <title> ──╮  — title sits inline at the top border.
+        const titlePiece = ` ${titleText} `;
+        const horizontalFill = Math.max(0, innerWidth - 1 - titlePiece.length);
+        return theme.primary(BOX.topLeft + BOX.horizontal + titlePiece + BOX.horizontal.repeat(horizontalFill) + BOX.topRight);
+    })();
+    const bodyLines = rows.map((row) => {
+        const valueWidth = innerWidth - labelWidth - 3; // 1 left pad + 2 gap
+        const clipped = clipValue(row.value, valueWidth);
+        const inside = ' ' + theme.muted(padRight(row.label, labelWidth)) + '  ' + theme.plain(padRight(clipped, valueWidth));
+        return theme.primary(BOX.vertical) + inside + theme.primary(BOX.vertical);
+    });
+    const bottom = theme.primary(BOX.bottomLeft + BOX.horizontal.repeat(innerWidth) + BOX.bottomRight);
+    return [top, ...bodyLines, bottom].join('\n');
+}
+/**
+ * Convenience: assemble the inputs from live agent + config + workspace
+ * state. Pure read; no side effects. Anything that throws while reading the
+ * goal or current-workflow files is treated as "not set" so a half-set-up
+ * workspace doesn't crash the banner.
+ */
+export function buildBannerInputs(config, agent, mcpClient) {
+    const profile = config.activeServer;
+    const server = config.servers[profile];
+    const transport = server?.type ?? 'unknown';
+    // 10c: identity comes from the live wrapper when present; fall back to
+    // the config field for callers that pass a thin stub.
+    const mcpIdentity = mcpClient.getIdentity ? mcpClient.getIdentity() : (server?.identity ?? 'unknown');
+    let workflow;
+    let lastUsedWorkflow;
+    try {
+        // 9d-bugfix: read the session-scoped binding so a fresh CLI session
+        // shows no workflow row even when another CLI in the same workspace
+        // has one bound.
+        const slug = getCurrentWorkflow(agent.workspaceRoot, agent.sessionKey);
+        if (slug) {
+            // We don't crack open workflowArtifacts.listWorkflows here — just the
+            // pointer file. Status would require parsing meta.json, which has its
+            // own cost on a slow disk; "bound" is enough to communicate state.
+            workflow = { slug, status: 'bound' };
+        }
+        else {
+            // Fresh session in a workspace where a previous CLI was on
+            // workflow X — surface that as a hint so the user can rebind via
+            // `/workflow switch X` if they want continuity. Doesn't auto-bind
+            // (per the decoupling design — workflows are storage, goals are
+            // runtime, the two have orthogonal lifecycles).
+            try {
+                lastUsedWorkflow = getLastUsedWorkflow(agent.workspaceRoot);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    catch { /* ignore — no workflow bound */ }
+    let goal;
+    try {
+        goal = readGoal(agent.workspaceRoot, agent.sessionKey) ?? undefined;
+    }
+    catch { /* ignore — no goal yet */ }
+    return {
+        workspaceRoot: agent.workspaceRoot,
+        mcpProfile: profile,
+        mcpTransport: transport,
+        mcpOnline: mcpClient.isConnected(),
+        mcpIdentity,
+        sessionKey: agent.sessionKey,
+        model: agent.getModel(),
+        workflow,
+        lastUsedWorkflow,
+        goal,
+    };
+}

package/dist/cli/cliPrompt.d.ts

@@ -1,12 +1,81 @@
 import readline from 'node:readline';
 export declare function setActiveReadline(rl: readline.Interface | undefined): void;
 export declare function getActiveReadline(): readline.Interface | undefined;
+export declare function isPickerActive(): boolean;
 /**
  * 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
  * (e.g. piped non-interactive runs).
  */
 export declare function askYesNo(question: string, defaultValue?: boolean): Promise<boolean>;
+/**
+ * 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 declare class NoTTYError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare class CancelledChoiceError extends Error {
+    constructor(message?: string);
+}
+export interface ChoiceOption {
+    label: string;
+    description: string;
+}
+export interface PickerState {
+    /** Includes the synthetic Other entry at the last index. */
+    options: ChoiceOption[];
+    cursor: number;
+    multiSelect: boolean;
+    /** Indices of options the user has toggled on (multi-select only). */
+    selected: Set<number>;
+    /** True once the user confirmed Other and we're collecting free text. */
+    awaitingOther: boolean;
+    /** Accumulated free-text for the Other prompt. */
+    otherText: string;
+    done: boolean;
+    cancelled: boolean;
+    /** Final resolved value when `done && !cancelled`. */
+    result: string | string[] | null;
+}
+/** Normalized keystroke shape the reducer consumes. Decoupled from Node's
+ * raw `keypress` event so the reducer can be driven by test inputs that
+ * don't go through `emitKeypressEvents`. */
+export interface PickerKey {
+    name?: string;
+    ctrl?: boolean;
+    sequence?: string;
+    /** A single printable character for free-text capture (Other phase). */
+    char?: string;
+}
+export declare function initPickerState(options: ChoiceOption[], multiSelect: boolean): PickerState;
+export declare function reducePicker(state: PickerState, key: PickerKey): PickerState;
+export declare function renderPicker(state: PickerState, question: string, header?: string): string;
+/**
+ * Mid-turn multi-choice prompt with arrow-key navigation, a checkbox UI
+ * for multi-select, and an always-on "Other" option that drops to free-text
+ * input. Pause/resume the parent REPL the same way `askYesNo` does, so it
+ * composes cleanly with the existing readline bridge.
+ *
+ * Non-TTY behavior is strict: throws `NoTTYError` instead of defaulting to
+ * option 1. The agent calling this is asking the human for judgment; making
+ * the call for them in CI / piped / `brainrouter run` would silently commit
+ * to a path the user never saw.
+ *
+ * User cancellation (Esc, q, Ctrl+C) throws `CancelledChoiceError` so the
+ * tool wrapper can surface "user declined to commit" as a tool-call error.
+ */
+export declare function askChoice(question: string, options: ChoiceOption[], opts?: {
+    multiSelect?: boolean;
+    header?: string;
+}): Promise<string | string[]>;
 /**
  * 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/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,285 @@ 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) {
+    const augmented = [...options, { label: OTHER_LABEL, description: OTHER_DESCRIPTION }];
+    return {
+        options: augmented,
+        cursor: 0,
+        multiSelect,
+        selected: new Set(),
+        awaitingOther: false,
+        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');
+}
+/**
+ * Mid-turn multi-choice prompt with arrow-key navigation, a checkbox UI
+ * for multi-select, and an always-on "Other" option that drops to free-text
+ * input. Pause/resume the parent REPL the same way `askYesNo` does, so it
+ * composes cleanly with the existing readline bridge.
+ *
+ * Non-TTY behavior is strict: throws `NoTTYError` instead of defaulting to
+ * option 1. The agent calling this is asking the human for judgment; making
+ * the call for them in CI / piped / `brainrouter run` would silently commit
+ * to a path the user never saw.
+ *
+ * User cancellation (Esc, q, Ctrl+C) throws `CancelledChoiceError` so the
+ * tool wrapper can surface "user declined to commit" as a tool-call error.
+ */
+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);
+        let renderedLines = 0;
+        // 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 (renderedLines > 0) {
+                // Move cursor up `renderedLines` then clear to end of screen.
+                stdout.write(`\x1b[${renderedLines}A\r\x1b[J`);
+            }
+        };
+        const render = () => {
+            clear();
+            const text = renderPicker(state, question, opts.header);
+            stdout.write(text + '\n');
+            renderedLines = text.split('\n').length;
+        };
+        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 nextState = reducePicker(state, pk);
+            if (nextState === state)
+                return;
+            state = nextState;
+            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