@kinqs/brainrouter-cli 0.3.6 → 0.3.8

package/dist/agent/toolCallRecovery.d.ts

@@ -0,0 +1,57 @@
+export interface ToolCallLike {
+    id: string;
+    type?: string;
+    function: {
+        name: string;
+        arguments: string | object;
+    };
+}
+export interface ToolResultMessage {
+    role: 'tool';
+    tool_call_id: string;
+    name: string;
+    content: string;
+    isError?: boolean;
+}
+/**
+ * Drop duplicate tool_call ids inside a single assistant response. Keeps the
+ * LAST occurrence (closest to the model's final intent). Calls without a
+ * string id are passed through unchanged — the orphan safety net will catch
+ * them later.
+ *
+ * `onDuplicate` is invoked once per dropped duplicate so callers can log a
+ * warning without coupling this module to a logger.
+ */
+export declare function dedupeToolCalls<T extends ToolCallLike>(calls: T[] | undefined | null, onDuplicate?: (id: string, droppedIndex: number) => void): T[];
+export interface ParsedArguments {
+    args: Record<string, any>;
+    /** Defined iff the LLM emitted malformed JSON; ready-to-use error string for a tool_result envelope. */
+    error?: string;
+    rawArguments: string;
+}
+/**
+ * Try-parse `tool_call.function.arguments`. On parse failure return a
+ * structured error string instead of throwing, so the caller can attach a
+ * synthetic tool_result that the next model turn can read.
+ */
+export declare function parseArgumentsOrError(call: ToolCallLike): ParsedArguments;
+/**
+ * For every tool_call in `calls` that has no matching tool_result in
+ * `results`, build a synthetic tool message so the next LLM request stays
+ * well-formed (OpenAI strictly requires tool_call ↔ tool_result pairing).
+ *
+ * IMPORTANT: the synthetic `content` MUST start with `ERROR:` and be a plain
+ * string. The agent runtime's R1 child-drain guardrail tracks spawned
+ * children by `parseJsonObject(resultText)` on tool results — if the
+ * synthetic envelope parses as JSON with an `id` field, the guardrail would
+ * incorrectly think a child agent was spawned and try to wait on it.
+ */
+export declare function synthesizeOrphanResults<T extends ToolCallLike>(calls: T[] | undefined | null, results: ToolResultMessage[]): ToolResultMessage[];
+/**
+ * Use the caller's existing `normalizeToolName` to surface a "did you mean"
+ * suggestion when the LLM emits a tool name that doesn't exist as-is but
+ * normalizes to a real registered tool. Tolerates the single-underscore
+ * `mcp_<server>_<tool>` prefix (R5 convention) since `normalizeToolName`
+ * matches by flattened form.
+ */
+export declare function suggestSimilarToolName(raw: string, candidates: string[], normalize: (raw: string, candidates: string[]) => string): string | undefined;

package/dist/agent/toolCallRecovery.js

@@ -0,0 +1,130 @@
+// Strict tool-call recovery helpers (0.3.8-I4 / roadmap §8).
+//
+// Adapted from deer-flow/backend/packages/harness/deerflow/agents/middlewares/
+//   dangling_tool_call_middleware.py — same pattern: detect tool_calls that
+//   never received a paired tool_result and inject synthetic placeholders so
+//   strict OpenAI-compatible validators don't reject the next request.
+//
+// These helpers are intentionally pure (no agent.ts imports) so they can be
+// unit-tested in isolation and reused if another runtime grows similar needs.
+/**
+ * Drop duplicate tool_call ids inside a single assistant response. Keeps the
+ * LAST occurrence (closest to the model's final intent). Calls without a
+ * string id are passed through unchanged — the orphan safety net will catch
+ * them later.
+ *
+ * `onDuplicate` is invoked once per dropped duplicate so callers can log a
+ * warning without coupling this module to a logger.
+ */
+export function dedupeToolCalls(calls, onDuplicate) {
+    if (!Array.isArray(calls) || calls.length === 0)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (let i = calls.length - 1; i >= 0; i--) {
+        const c = calls[i];
+        const id = c?.id;
+        if (typeof id !== 'string' || id === '') {
+            out.push(c);
+            continue;
+        }
+        if (seen.has(id)) {
+            onDuplicate?.(id, i);
+            continue;
+        }
+        seen.add(id);
+        out.push(c);
+    }
+    return out.reverse();
+}
+/**
+ * Try-parse `tool_call.function.arguments`. On parse failure return a
+ * structured error string instead of throwing, so the caller can attach a
+ * synthetic tool_result that the next model turn can read.
+ */
+export function parseArgumentsOrError(call) {
+    const raw = call?.function?.arguments;
+    if (raw == null)
+        return { args: {}, rawArguments: '' };
+    if (typeof raw !== 'string') {
+        // Provider already parsed it for us.
+        return {
+            args: (raw && typeof raw === 'object') ? raw : {},
+            rawArguments: (() => { try {
+                return JSON.stringify(raw);
+            }
+            catch {
+                return String(raw);
+            } })(),
+        };
+    }
+    if (raw.trim() === '')
+        return { args: {}, rawArguments: raw };
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            args: (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {},
+            rawArguments: raw,
+        };
+    }
+    catch (e) {
+        const msg = e?.message ?? String(e);
+        // Keep the raw arguments visible — the model often needs to see exactly
+        // what it produced to self-correct (e.g. trailing comma, missing quote).
+        const previewedRaw = raw.length > 400 ? `${raw.slice(0, 400)}…[truncated ${raw.length - 400} chars]` : raw;
+        return {
+            args: {},
+            error: `Tool argument JSON was malformed: ${msg}. Raw arguments emitted by the model: ${previewedRaw}. Re-issue the tool call with valid JSON arguments.`,
+            rawArguments: raw,
+        };
+    }
+}
+/**
+ * For every tool_call in `calls` that has no matching tool_result in
+ * `results`, build a synthetic tool message so the next LLM request stays
+ * well-formed (OpenAI strictly requires tool_call ↔ tool_result pairing).
+ *
+ * IMPORTANT: the synthetic `content` MUST start with `ERROR:` and be a plain
+ * string. The agent runtime's R1 child-drain guardrail tracks spawned
+ * children by `parseJsonObject(resultText)` on tool results — if the
+ * synthetic envelope parses as JSON with an `id` field, the guardrail would
+ * incorrectly think a child agent was spawned and try to wait on it.
+ */
+export function synthesizeOrphanResults(calls, results) {
+    if (!Array.isArray(calls) || calls.length === 0)
+        return [];
+    const have = new Set(results.map((r) => r.tool_call_id));
+    const synthetic = [];
+    for (const c of calls) {
+        const id = c?.id;
+        if (typeof id !== 'string' || id === '')
+            continue;
+        if (have.has(id))
+            continue;
+        synthetic.push({
+            role: 'tool',
+            tool_call_id: id,
+            name: c?.function?.name ?? 'unknown',
+            content: 'ERROR: tool call orphaned by model; no execution recorded. Re-issue the tool call if you still need this work done.',
+            isError: true,
+        });
+    }
+    return synthetic;
+}
+/**
+ * Use the caller's existing `normalizeToolName` to surface a "did you mean"
+ * suggestion when the LLM emits a tool name that doesn't exist as-is but
+ * normalizes to a real registered tool. Tolerates the single-underscore
+ * `mcp_<server>_<tool>` prefix (R5 convention) since `normalizeToolName`
+ * matches by flattened form.
+ */
+export function suggestSimilarToolName(raw, candidates, normalize) {
+    const trimmed = (raw ?? '').trim();
+    if (!trimmed || candidates.includes(trimmed))
+        return undefined;
+    const suggestion = normalize(trimmed, candidates);
+    if (suggestion && suggestion !== trimmed && candidates.includes(suggestion)) {
+        return suggestion;
+    }
+    return undefined;
+}

package/dist/agent/toolSafety.d.ts

@@ -0,0 +1,17 @@
+/**
+ * True iff `toolName` is on the conservative parallel-safe whitelist.
+ * Accepts both the bare local tool name (`read_file`) and the MCP-prefixed
+ * form (`mcp_brainrouter_memory_recall`). Anything else — including any
+ * unknown tool name — returns false so the caller falls back to safe
+ * serial execution.
+ */
+export declare function isParallelSafe(toolName: string): boolean;
+/** Companion to `isParallelSafe` — true iff the name resolves to a known MCP read tool. */
+export declare function isMcpReadTool(toolName: string): boolean;
+/**
+ * Kill switch: `BRAINROUTER_PARALLEL_SAFE_TOOL_CALLS=false` (or `0`/`off`/`no`)
+ * forces every batch back to strict serial execution — the pre-R4 shape.
+ * Useful when debugging an issue and you want to rule out concurrency, or
+ * when running against an LLM provider that rate-limits tool dispatch.
+ */
+export declare function parallelExecutionEnabled(): boolean;

package/dist/agent/toolSafety.js

@@ -0,0 +1,102 @@
+// 0.3.8-R4 — Single source of truth for which tool calls are safe to
+// dispatch concurrently within one LLM response.
+//
+// Pre-R4 the runtime executed every tool call from one assistant message
+// strictly serially. That's safe but it's pure latency loss for the common
+// case of "read 5 files in one turn" — none of those reads share state or
+// depend on each other's results. Writes and shell commands still need to
+// serialize to preserve causality.
+//
+// `isParallelSafe(toolName)` is the conservative whitelist. Anything not on
+// the list is treated as serial — the failure mode is "we ran something
+// sequentially that could have been concurrent," which is the same
+// performance the pre-R4 code shipped with. Adding tools here is the only
+// way to opt them in.
+/**
+ * Local read-only tools whose execution is independent and has no
+ * observable side effect on the workspace, on child-session state, or on
+ * the agent's own bookkeeping. These can run concurrently within a single
+ * LLM response.
+ *
+ * Explicitly EXCLUDED (must stay serial):
+ *   - write_file / edit_file / apply_patch / run_command  — workspace mutation.
+ *   - spawn_agent / spawn_agents / task_agent / delegate_agent
+ *     / wait_agent / wait_agents / close_agent / route_agent
+ *     / read_agent_transcript  — orchestration / child-session mutation.
+ *     (R1's child-drain guardrail tracks every spawn/wait one-by-one;
+ *     running them in parallel would let bookkeeping diverge.)
+ *   - update_plan / goal_complete / goal_blocked  — session state mutation.
+ *   - ask_user_choice  — interactive picker; must not interleave with other UI.
+ *   - list_agents  — reads orchestration state but classified serial out of
+ *     caution; cheap and rarely batched.
+ */
+const PARALLEL_SAFE_LOCAL_TOOLS = new Set([
+    'read_file',
+    'list_dir',
+    'grep_search',
+    'glob_files',
+    'fetch_url',
+    'web_search',
+]);
+/**
+ * MCP read tools — bare tool names (without the `mcp_<server>_` prefix)
+ * that BrainRouter knows to be read-only. The pool normalises any legacy
+ * double-underscore emissions to the canonical single-underscore
+ * `mcp_<server>_<tool>` form at its boundary (0.3.8-R5), so the matcher
+ * here only deals with that one shape.
+ */
+const PARALLEL_SAFE_MCP_READ_TOOLS = new Set([
+    'memory_recall',
+    'memory_search',
+    'memory_file_history',
+    'memory_task_state',
+    'memory_contradictions',
+    'memory_inspect',
+    'memory_list_records',
+]);
+/**
+ * True iff `toolName` is on the conservative parallel-safe whitelist.
+ * Accepts both the bare local tool name (`read_file`) and the MCP-prefixed
+ * form (`mcp_brainrouter_memory_recall`). Anything else — including any
+ * unknown tool name — returns false so the caller falls back to safe
+ * serial execution.
+ */
+export function isParallelSafe(toolName) {
+    if (!toolName)
+        return false;
+    if (PARALLEL_SAFE_LOCAL_TOOLS.has(toolName))
+        return true;
+    const bare = stripMcpPrefix(toolName);
+    if (bare && PARALLEL_SAFE_MCP_READ_TOOLS.has(bare))
+        return true;
+    return false;
+}
+/** Companion to `isParallelSafe` — true iff the name resolves to a known MCP read tool. */
+export function isMcpReadTool(toolName) {
+    const bare = stripMcpPrefix(toolName);
+    return !!bare && PARALLEL_SAFE_MCP_READ_TOOLS.has(bare);
+}
+function stripMcpPrefix(name) {
+    // Canonical single-underscore shape: mcp_<server>_<tool>. Server names
+    // may contain underscores so we suffix-match against known bare tools
+    // instead of guessing where the server segment ends.
+    if (name.startsWith('mcp_')) {
+        for (const known of PARALLEL_SAFE_MCP_READ_TOOLS) {
+            if (name.endsWith('_' + known))
+                return known;
+        }
+    }
+    return undefined;
+}
+/**
+ * Kill switch: `BRAINROUTER_PARALLEL_SAFE_TOOL_CALLS=false` (or `0`/`off`/`no`)
+ * forces every batch back to strict serial execution — the pre-R4 shape.
+ * Useful when debugging an issue and you want to rule out concurrency, or
+ * when running against an LLM provider that rate-limits tool dispatch.
+ */
+export function parallelExecutionEnabled() {
+    const raw = (process.env.BRAINROUTER_PARALLEL_SAFE_TOOL_CALLS ?? '').trim().toLowerCase();
+    if (raw === 'false' || raw === '0' || raw === 'off' || raw === 'no')
+        return false;
+    return true;
+}

package/dist/cli/banner.d.ts

@@ -39,6 +39,12 @@ export interface BannerInputs {
     /** Version override (test fixture). */
     version?: string;
 }
+export interface DisplayedMcpState {
+    profile: string;
+    transport: string;
+    online: boolean;
+    identity: 'brainrouter' | 'third-party' | 'unknown';
+}
 /**
  * Pure renderer — returns the box as a single newline-joined string with
  * ANSI sequences from `theme`. Caller appends the trailing newline.
@@ -57,4 +63,18 @@ export declare function buildBannerInputs(config: Config, agent: {
 }, mcpClient: {
     isConnected: () => boolean;
     getIdentity?: () => 'brainrouter' | 'third-party' | 'unknown';
+    getStatus?: (serverId: string) => {
+        status: string;
+        identity: 'brainrouter' | 'third-party' | 'unknown';
+    } | undefined;
+    getActiveBrainrouterServerId?: () => string | undefined;
 }): BannerInputs;
+export declare function resolveDisplayedMcpState(config: Config, mcpClient: {
+    isConnected: () => boolean;
+    getIdentity?: () => 'brainrouter' | 'third-party' | 'unknown';
+    getStatus?: (serverId: string) => {
+        status: string;
+        identity: 'brainrouter' | 'third-party' | 'unknown';
+    } | undefined;
+    getActiveBrainrouterServerId?: () => string | undefined;
+}): DisplayedMcpState;

package/dist/cli/banner.js

@@ -9,7 +9,7 @@ import { BOX } from './theme.js';
  * (chalk title + workspace line + connecting-to line) with a single visually
  * scannable block:
  *
- *   ╭─ 🧠 BrainRouter CLI 0.3.5 ──────────────────────────────╮
+ *   ╭─ 🧠 BrainRouter CLI 0.3.8 ──────────────────────────────╮
  *   │ workspace  BrainRouter  ·  c5b8c12d                     │
  *   │ mcp        local-http  ·  http  ·  online               │
  *   │ workflow   cli-shell-redesign  (in-progress)            │
@@ -26,10 +26,19 @@ import { BOX } from './theme.js';
  * 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 VERSION = '0.3.8';
 const TITLE = '🧠 BrainRouter CLI';
-const MIN_WIDTH = 56;
+// Width floor for the BOXED banner. Below this we fall through to the
+// `renderPlainBanner` plaintext format. Was 56 — that caused the box to
+// overflow on terminals narrower than 58 cols (each row wrapped to
+// multiple terminal rows with broken border alignment). 38 fits a
+// 40-col terminal (the smallest realistic phone / split-pane width).
+const MIN_BOX_WIDTH = 38;
 const MAX_WIDTH = 100;
+// Below this width we skip the box entirely and render the rows as
+// "label: value" lines. The boxed format with horizontal borders +
+// title is meaningless when each border row wraps.
+const PLAIN_TEXT_THRESHOLD = 38;
 function shortHash(absPath) {
     return crypto.createHash('sha1').update(absPath).digest('hex').slice(0, 8);
 }
@@ -123,8 +132,14 @@ export function renderBanner(inputs, theme) {
     // 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;
+    // Below the plaintext threshold the boxed layout is hostile (each
+    // border row wraps and looks chaotic). Fall back to a label:value
+    // text dump that the terminal can wrap naturally.
+    if (targetCols < PLAIN_TEXT_THRESHOLD) {
+        return renderPlainBanner(titleText, rows, theme);
+    }
     // Reserve 2 columns for the side borders.
-    const innerWidth = Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, Math.min(naturalInner, targetCols - 2)));
+    const innerWidth = Math.max(MIN_BOX_WIDTH, Math.min(MAX_WIDTH, Math.min(naturalInner, targetCols - 2)));
     const top = (() => {
         // ╭─ <title> ──╮  — title sits inline at the top border.
         const titlePiece = ` ${titleText} `;
@@ -140,6 +155,17 @@ export function renderBanner(inputs, theme) {
     const bottom = theme.primary(BOX.bottomLeft + BOX.horizontal.repeat(innerWidth) + BOX.bottomRight);
     return [top, ...bodyLines, bottom].join('\n');
 }
+/**
+ * Compact label:value text banner — used on terminals narrower than
+ * PLAIN_TEXT_THRESHOLD cols where the boxed layout's border rows
+ * would wrap and look broken. Same information, no chrome.
+ */
+function renderPlainBanner(titleText, rows, theme) {
+    const labelWidth = rows.reduce((w, r) => Math.max(w, r.label.length), 0);
+    const headerLine = theme.primary(titleText);
+    const bodyLines = rows.map((row) => theme.muted(padRight(row.label, labelWidth) + '  ') + theme.plain(row.value));
+    return [headerLine, ...bodyLines].join('\n');
+}
 /**
  * Convenience: assemble the inputs from live agent + config + workspace
  * state. Pure read; no side effects. Anything that throws while reading the
@@ -147,12 +173,7 @@ export function renderBanner(inputs, theme) {
  * 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');
+    const displayedMcp = resolveDisplayedMcpState(config, mcpClient);
     let workflow;
     let lastUsedWorkflow;
     try {
@@ -186,10 +207,10 @@ export function buildBannerInputs(config, agent, mcpClient) {
     catch { /* ignore — no goal yet */ }
     return {
         workspaceRoot: agent.workspaceRoot,
-        mcpProfile: profile,
-        mcpTransport: transport,
-        mcpOnline: mcpClient.isConnected(),
-        mcpIdentity,
+        mcpProfile: displayedMcp.profile,
+        mcpTransport: displayedMcp.transport,
+        mcpOnline: displayedMcp.online,
+        mcpIdentity: displayedMcp.identity,
         sessionKey: agent.sessionKey,
         model: agent.getModel(),
         workflow,
@@ -197,3 +218,15 @@ export function buildBannerInputs(config, agent, mcpClient) {
         goal,
     };
 }
+export function resolveDisplayedMcpState(config, mcpClient) {
+    const liveBrain = mcpClient.getActiveBrainrouterServerId?.();
+    const profile = liveBrain || config.activeServer;
+    const server = config.servers[profile];
+    const status = profile ? mcpClient.getStatus?.(profile) : undefined;
+    return {
+        profile,
+        transport: server?.type ?? 'unknown',
+        online: status ? status.status === 'connected' : mcpClient.isConnected(),
+        identity: status?.identity ?? server?.identity ?? mcpClient.getIdentity?.() ?? 'unknown',
+    };
+}

package/dist/cli/cliPrompt.d.ts

@@ -55,7 +55,22 @@ export interface PickerKey {
     /** A single printable character for free-text capture (Other phase). */
     char?: string;
 }
-export declare function initPickerState(options: ChoiceOption[], multiSelect: boolean): PickerState;
+/**
+ * `prefilledOther` drops the picker straight into the free-text "Other"
+ * phase with the supplied string already in the buffer. Used by the
+ * 0.3.7 wizard / `/config` panel when a value can be derived from an
+ * env var — the user sees the env value and presses ENTER to accept or
+ * edits to override. Pass an empty string to keep today's behaviour.
+ *
+ * `initialCursor` lets a picker open with a non-zero highlight so the
+ * settings home panel can re-open on the row the user just edited
+ * without re-scrolling them to the top.
+ */
+export interface InitPickerStateOptions {
+    prefilledOther?: string;
+    initialCursor?: number;
+}
+export declare function initPickerState(options: ChoiceOption[], multiSelect: boolean, init?: InitPickerStateOptions): PickerState;
 export declare function reducePicker(state: PickerState, key: PickerKey): PickerState;
 export declare function renderPicker(state: PickerState, question: string, header?: string): string;
 /**
@@ -72,10 +87,32 @@ export declare function renderPicker(state: PickerState, question: string, heade
  * 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?: {
+/**
+ * 0.3.7 picker opts.
+ *
+ * `onCursorChange(index)` fires after every arrow-key move that actually
+ * moves the cursor (no-op keys, ENTER, SPACE don't fire it). The 0.3.7
+ * theme picker uses this to live-preview the selected theme by redrawing
+ * the banner accent before the user confirms — pattern lifted from
+ * `openSrc/codex/codex-rs/tui/src/bottom_pane/list_selection_view.rs` and
+ * `openSrc/codex/codex-rs/tui/src/theme_picker.rs`.
+ *
+ * `prefilledOther` opens the picker with the synthetic "Other" row
+ * already selected AND the free-text input pre-filled. Used when a value
+ * is derived from an env var so the user can press ENTER to accept or
+ * edit in-place. Pre-fill flips `awaitingOther` true on init.
+ *
+ * `initialCursor` lets the settings home panel re-open on the row the
+ * user just left, avoiding a snap-to-row-0 after every sub-picker.
+ */
+export interface AskChoiceOptions {
     multiSelect?: boolean;
     header?: string;
-}): Promise<string | string[]>;
+    onCursorChange?: (cursor: number) => void;
+    prefilledOther?: string;
+    initialCursor?: number;
+}
+export declare function askChoice(question: string, options: ChoiceOption[], opts?: AskChoiceOptions): 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