@kinqs/brainrouter-cli 0.3.6 → 0.3.7

package/dist/runtime/mcpPool.js

@@ -0,0 +1,423 @@
+import { McpClientWrapper, resolveIdentityFromConfig } from './mcpClient.js';
+/**
+ * Choose which configured MCP profiles should connect for a normal CLI run.
+ *
+ * BrainRouter profiles are special: users may store several BrainRouter MCPs
+ * (local, staging, remote, self-hosted), but only one should be active at a
+ * time because the BrainRouter MCP is the memory/brain plane. Third-party MCPs
+ * are additive tools, so they all connect concurrently.
+ *
+ * `requestedProfile` is the explicit escape hatch (`--profile <name>`): it
+ * scopes the run to exactly that profile, matching the existing single-server
+ * mode.
+ */
+export function selectMcpServerIds(servers, activeServer, requestedProfile) {
+    const ids = Object.keys(servers);
+    if (requestedProfile)
+        return servers[requestedProfile] ? [requestedProfile] : [];
+    const brainrouterIds = ids.filter((id) => resolveIdentityFromConfig(servers[id], id) === 'brainrouter');
+    const activeBrainrouter = activeServer && brainrouterIds.includes(activeServer)
+        ? activeServer
+        : brainrouterIds[0];
+    return ids.filter((id) => {
+        const identity = resolveIdentityFromConfig(servers[id], id);
+        return identity !== 'brainrouter' || id === activeBrainrouter;
+    });
+}
+function isBrainrouterOwnedTool(name) {
+    return name.startsWith('memory_') ||
+        [
+            'list_skills',
+            'get_skill',
+            'search_skills',
+            'create_skill',
+            'update_skill',
+            'get_persona',
+            'get_reference',
+            'list_template_docs',
+            'get_template_doc',
+        ].includes(name);
+}
+export class McpClientPool {
+    /** serverId → connected wrapper. */
+    clients = new Map();
+    /** serverId → status entry (kept even for failed/offline servers so /mcp can render them). */
+    statuses = new Map();
+    /**
+     * Unprefixed tool name → owning serverId. Sentinel `__COLLISION__`
+     * marks tool names exposed by multiple servers (must be addressed
+     * via the prefixed form).
+     */
+    toolToServer = new Map();
+    /** Prefixed form (`mcp_<serverId>_<tool>`) → `{serverId, tool}` for fast dispatch. */
+    prefixedToServer = new Map();
+    /** LLM config from the last connectAll — needed for reconnect calls. */
+    currentLlmConfig;
+    /** Raw server configs from the last connectAll — needed for /mcp reconnect <id>. */
+    serverConfigs = new Map();
+    /** serverId → prefix used in tool names. Brainrouter servers get "brainrouter"; others keep their config key. */
+    prefixIds = new Map();
+    /** Reverse: prefixId → serverId (needed to dispatch `mcp_brainrouter_X` back to the real key). */
+    prefixToServerId = new Map();
+    getPrefixId(serverId) {
+        return this.prefixIds.get(serverId) ?? serverId;
+    }
+    assignPrefixId(serverId, wrapper) {
+        const id = wrapper.getIdentity() === 'brainrouter' ? 'brainrouter' : serverId;
+        this.prefixIds.set(serverId, id);
+        this.prefixToServerId.set(id, serverId);
+    }
+    /**
+     * Connect to every entry in `servers` concurrently. Each connect
+     * gets its own timeout; offline servers don't block the others.
+     * Returns the status array after all connects settle.
+     */
+    async connectAll(servers, llmConfig, options) {
+        this.currentLlmConfig = llmConfig;
+        const entries = Object.entries(servers);
+        // Stash configs first so `/mcp reconnect <id>` can find them later.
+        for (const [serverId, cfg] of entries)
+            this.serverConfigs.set(serverId, cfg);
+        const tasks = entries.map(([serverId, cfg]) => this.connectOne(serverId, cfg, llmConfig, options?.timeoutMs).then(() => {
+            const s = this.statuses.get(serverId);
+            if (s && options?.onStatusChange)
+                options.onStatusChange(s);
+        }));
+        await Promise.allSettled(tasks);
+        await this.refreshToolIndex();
+        return this.getStatuses();
+    }
+    /**
+     * Connect a single server. Used both by `connectAll` and by
+     * `/mcp connect <id>` for late-joining servers. Idempotent — if
+     * the server is already connected, closes the previous wrapper first.
+     */
+    async connectOne(serverId, config, llmConfig, timeoutMs = 5_000) {
+        if (this.clients.has(serverId)) {
+            try {
+                await this.clients.get(serverId).close();
+            }
+            catch { /* ignore */ }
+            this.clients.delete(serverId);
+        }
+        this.serverConfigs.set(serverId, config);
+        this.statuses.set(serverId, { serverId, identity: 'unknown', status: 'connecting' });
+        const wrapper = new McpClientWrapper();
+        try {
+            await Promise.race([
+                wrapper.connect(config, llmConfig ?? this.currentLlmConfig, serverId),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs)),
+            ]);
+            this.clients.set(serverId, wrapper);
+            this.assignPrefixId(serverId, wrapper);
+            this.statuses.set(serverId, {
+                serverId,
+                identity: wrapper.getIdentity(),
+                status: 'connected',
+            });
+        }
+        catch (err) {
+            this.statuses.set(serverId, {
+                serverId,
+                identity: 'unknown',
+                status: 'failed',
+                error: err?.message ?? String(err),
+            });
+            try {
+                await wrapper.close();
+            }
+            catch { /* ignore */ }
+        }
+        await this.refreshToolIndex();
+    }
+    /** Tear down a single server. Removes it from the pool and rebuilds the tool index. */
+    async disconnectOne(serverId) {
+        const wrapper = this.clients.get(serverId);
+        if (wrapper) {
+            try {
+                await wrapper.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.clients.delete(serverId);
+        const oldPid = this.prefixIds.get(serverId);
+        if (oldPid)
+            this.prefixToServerId.delete(oldPid);
+        this.prefixIds.delete(serverId);
+        const prev = this.statuses.get(serverId);
+        this.statuses.set(serverId, {
+            serverId,
+            identity: prev?.identity ?? 'unknown',
+            status: 'offline',
+        });
+        await this.refreshToolIndex();
+    }
+    /** Reconnect: close + connect again using the stashed config. */
+    async reconnectOne(serverId) {
+        const config = this.serverConfigs.get(serverId);
+        if (!config) {
+            throw new Error(`No stored config for serverId "${serverId}". Add it to ~/.config/brainrouter/config.json first.`);
+        }
+        await this.disconnectOne(serverId);
+        await this.connectOne(serverId, config, this.currentLlmConfig);
+    }
+    /**
+     * Walk every connected client and rebuild the tool→server indices.
+     * Called after every connect / disconnect / reconnect so the
+     * dispatch path stays correct without re-fetching tools on every
+     * `callTool`.
+     */
+    async refreshToolIndex() {
+        this.toolToServer.clear();
+        this.prefixedToServer.clear();
+        for (const [serverId, wrapper] of this.clients) {
+            if (!wrapper.isConnected())
+                continue;
+            try {
+                const res = await wrapper.listTools();
+                const tools = res.tools ?? [];
+                const status = this.statuses.get(serverId);
+                if (status) {
+                    status.toolCount = tools.length;
+                    status.identity = wrapper.getIdentity();
+                }
+                for (const tool of tools) {
+                    const rawName = tool.name;
+                    const pid = this.getPrefixId(serverId);
+                    const prefixed = `mcp_${pid}_${rawName}`;
+                    this.prefixedToServer.set(prefixed, { serverId, tool: rawName });
+                    const existing = this.toolToServer.get(rawName);
+                    if (existing && existing !== serverId) {
+                        // Two servers expose the same unprefixed tool name. Mark
+                        // collision so the raw-name resolver knows to require the
+                        // prefix.
+                        this.toolToServer.set(rawName, '__COLLISION__');
+                    }
+                    else if (!existing) {
+                        this.toolToServer.set(rawName, serverId);
+                    }
+                }
+            }
+            catch {
+                // Server is connected but listTools failed — its tools won't
+                // appear this turn. Will retry on the next refresh.
+            }
+        }
+    }
+    /**
+     * Concatenated tool list across every connected server, with names
+     * prefixed `mcp_<serverId>_<toolName>` (Claude Code style). The
+     * agent calls this once per turn and hands it to the LLM.
+     */
+    async listTools() {
+        const all = [];
+        for (const [serverId, wrapper] of this.clients) {
+            if (!wrapper.isConnected())
+                continue;
+            try {
+                const res = await wrapper.listTools();
+                const tools = res.tools ?? [];
+                const status = this.statuses.get(serverId);
+                if (status) {
+                    status.identity = wrapper.getIdentity();
+                }
+                const pid = this.getPrefixId(serverId);
+                for (const tool of tools) {
+                    all.push({
+                        ...tool,
+                        name: `mcp_${pid}_${tool.name}`,
+                        __serverId: serverId,
+                        __rawName: tool.name,
+                    });
+                }
+            }
+            catch {
+                // listTools failed for this server — drop its tools this turn.
+            }
+        }
+        return { tools: all };
+    }
+    /**
+     * Route a tool call to the right server. Accepts both name forms:
+     *
+     *   - `mcp_<serverId>_<tool>` — the canonical form the LLM sees
+     *     in the inventory. Stripped + dispatched directly.
+     *   - `<tool>` raw form — back-compat for prompts/skills that
+     *     hardcode `memory_recall`-style names. Routed to the unique
+     *     server providing that tool. Returns a helpful error if two
+     *     servers expose the same name (caller must use the prefix).
+     */
+    async callTool(name, args) {
+        const resolved = this.resolveToolCall(name);
+        if (!resolved) {
+            // Distinguish the two failure modes — gives the LLM (and humans
+            // tailing logs) actionable feedback.
+            if (this.toolToServer.get(name) === '__COLLISION__') {
+                const prefixes = [...this.clients.keys()]
+                    .filter((id) => {
+                    const w = this.clients.get(id);
+                    return w && w.isConnected() && this.prefixedToServer.has(`mcp_${this.getPrefixId(id)}_${name}`);
+                })
+                    .map((id) => this.getPrefixId(id));
+                return {
+                    isError: true,
+                    content: [{
+                            type: 'text',
+                            text: `Ambiguous tool name "${name}" — exposed by ${prefixes.length} MCP servers: ${prefixes.join(', ')}. Use the prefixed form, e.g. mcp_${prefixes[0]}_${name}.`,
+                        }],
+                };
+            }
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Tool "${name}" not found on any connected MCP server.` }],
+            };
+        }
+        const wrapper = this.clients.get(resolved.serverId);
+        if (!wrapper || !wrapper.isConnected()) {
+            return {
+                isError: true,
+                content: [{
+                        type: 'text',
+                        text: `MCP server "${resolved.serverId}" is offline; tool "${resolved.tool}" cannot be reached. Try /mcp reconnect ${resolved.serverId}.`,
+                    }],
+            };
+        }
+        return wrapper.callTool(resolved.tool, args);
+    }
+    /** Internal — map a name (prefixed OR raw) to a concrete server + tool. */
+    resolveToolCall(name) {
+        // Fast path: exact prefixed form match in the index.
+        if (name.startsWith('mcp_')) {
+            const direct = this.prefixedToServer.get(name);
+            if (direct)
+                return direct;
+            // Lenient parse: walk prefix IDs first (covers "brainrouter"
+            // alias), then raw server IDs as fallback.
+            const rest = name.slice('mcp_'.length);
+            for (const [pid, realId] of this.prefixToServerId) {
+                const prefix = `${pid}_`;
+                if (rest.startsWith(prefix)) {
+                    return { serverId: realId, tool: rest.slice(prefix.length) };
+                }
+            }
+            for (const serverId of this.clients.keys()) {
+                const prefix = `${serverId}_`;
+                if (rest.startsWith(prefix)) {
+                    return { serverId, tool: rest.slice(prefix.length) };
+                }
+            }
+            return undefined;
+        }
+        if (isBrainrouterOwnedTool(name)) {
+            for (const [serverId, wrapper] of this.clients) {
+                if (wrapper.isConnected() &&
+                    wrapper.getIdentity() === 'brainrouter' &&
+                    this.prefixedToServer.has(`mcp_${serverId}_${name}`)) {
+                    return { serverId, tool: name };
+                }
+            }
+        }
+        // Raw-name fallback.
+        const owner = this.toolToServer.get(name);
+        if (!owner || owner === '__COLLISION__')
+            return undefined;
+        return { serverId: owner, tool: name };
+    }
+    // ----- Facade methods that match McpClientWrapper's public surface -----
+    /** True iff at least one server is connected. */
+    isConnected() {
+        for (const w of this.clients.values()) {
+            if (w.isConnected())
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Identity precedence: any connected `brainrouter` > any connected
+     * `third-party` > `unknown`. The CLI banner + offline prompt swap
+     * branch on this — "BrainRouter is offline" makes sense only when
+     * we expected one and didn't get one.
+     */
+    getIdentity() {
+        for (const w of this.clients.values()) {
+            if (w.isConnected() && w.getIdentity() === 'brainrouter')
+                return 'brainrouter';
+        }
+        for (const w of this.clients.values()) {
+            if (w.isConnected() && w.getIdentity() === 'third-party')
+                return 'third-party';
+        }
+        return 'unknown';
+    }
+    /**
+     * Human-readable summary for the banner/statusline. Single-server
+     * pools render just the server name; multi-server pools render
+     * a count + the first few names.
+     */
+    getServerName() {
+        const connected = [...this.clients.entries()]
+            .filter(([_, w]) => w.isConnected())
+            .map(([id]) => id);
+        if (connected.length === 0)
+            return undefined;
+        if (connected.length === 1)
+            return connected[0];
+        const head = connected.slice(0, 3).join(', ');
+        return connected.length > 3 ? `${connected.length} servers (${head}, …)` : `${connected.length} servers (${head})`;
+    }
+    /**
+     * Look up a wrapper by serverId. Used by `/mcp tools <server>` and
+     * similar commands that want to talk to one specific server.
+     */
+    getClient(serverId) {
+        return this.clients.get(serverId);
+    }
+    /**
+     * Find the connected wrapper whose identity is 'brainrouter'. Some
+     * code paths (memory capture, working-memory offload) specifically
+     * need the canonical brain regardless of how many third-party MCPs
+     * the user added.
+     */
+    getBrainrouterClient() {
+        for (const w of this.clients.values()) {
+            if (w.isConnected() && w.getIdentity() === 'brainrouter')
+                return w;
+        }
+        return undefined;
+    }
+    /** Server id for the currently connected BrainRouter MCP, if one is active. */
+    getActiveBrainrouterServerId() {
+        for (const [serverId, wrapper] of this.clients) {
+            if (wrapper.isConnected() && wrapper.getIdentity() === 'brainrouter')
+                return serverId;
+        }
+        return undefined;
+    }
+    /** Status snapshot for every server the pool has tried to connect to. */
+    getStatuses() {
+        return [...this.statuses.values()];
+    }
+    /** Status for one server (returns undefined if the pool has never seen it). */
+    getStatus(serverId) {
+        return this.statuses.get(serverId);
+    }
+    /** List of serverIds currently held by the pool (connected or not). */
+    getServerIds() {
+        return [...this.statuses.keys()];
+    }
+    /** Close every wrapper. Used on CLI exit. */
+    async close() {
+        for (const wrapper of this.clients.values()) {
+            try {
+                await wrapper.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.clients.clear();
+        this.toolToServer.clear();
+        this.prefixedToServer.clear();
+        this.prefixIds.clear();
+        this.prefixToServerId.clear();
+        // Keep `statuses` so a `getStatuses()` after close still shows what was there.
+    }
+}

package/dist/runtime/mcpUtils.d.ts

@@ -1,4 +1,6 @@
 import type { McpClientWrapper } from './mcpClient.js';
+import type { McpClientPool } from './mcpPool.js';
+export type McpClient = McpClientWrapper | McpClientPool;
 /**
  * Centralized helpers for talking to the BrainRouter MCP server.
  *
@@ -27,7 +29,7 @@ export interface McpCallResult<T = any> {
  * Network and protocol errors are converted to `{ isError: true, text: errorMessage }`
  * so callers can branch on a single shape instead of mixing try/catch with isError checks.
  */
-export declare function callMcpTool<T = any>(client: McpClientWrapper, name: string, args: Record<string, unknown>): Promise<McpCallResult<T>>;
+export declare function callMcpTool<T = any>(client: McpClient, name: string, args: Record<string, unknown>): Promise<McpCallResult<T>>;
 /**
  * Canonical convention for naming a child agent's session key relative to its
  * parent: `<parent>:child:<id>`. Centralized so a future change (e.g. switching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinqs/brainrouter-cli",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Memory-native terminal coding agent. Talks to the BrainRouter MCP cognitive engine for recall, skills, capture, persona, focus scenes, and contradiction tracking.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
     "brainrouter": "bin/cli.cjs"
   },
   "files": [
+    "agents",
     "bin",
     "dist",
     "README.md",
@@ -28,15 +29,20 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.5",
+    "ink": "^7.0.3",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
     "inquirer": "^9.3.2",
     "marked": "^12.0.1",
     "marked-terminal": "^7.0.0",
-    "ora": "^8.0.1"
+    "ora": "^8.0.1",
+    "react": "^19.2.6"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.7",
     "@types/marked": "^4.0.8",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.2.15",
     "tsx": "^4.7.0",
     "typescript": "^5.5.4"
   },

package/.env.example

@@ -1,116 +0,0 @@
-# BrainRouter CLI agent — environment template
-#
-# Copy to `brainrouter-cli/.env`. Loaded by the CLI at startup.
-#
-# This file is for CLI-AGENT concerns only:
-#   1. Chat LLM                  (the model the terminal agent talks to)
-#   2. Tool runtime              (loop limit, result clamp, MCP timeout, auto-compact)
-#   3. Sandbox                   (run_command wrapping)
-#   4. Workspace                 (root override + shared state root)
-#   5. Web search                (custom backend for the web_search tool)
-#   6. Observability             (trace log path)
-#
-# MCP-server concerns (cognitive extraction, embeddings, reranker, judge,
-# memory engine knobs, server auth) live in `brainrouter/.env.example`.
-#
-# Why split: the MCP and the CLI are separate processes with different
-# concerns. The CLI's chat LLM can be a smart cloud model while the MCP's
-# cognitive extractor is a cheap local one. Their concurrency caps differ
-# too (CLI default 4, MCP default 2). Keep them independent.
-#
-# All values in this template are blank placeholders. Fill in only what
-# you actually need — most settings have sensible defaults.
-
-
-# =============================================================================
-# 1. Chat LLM (for the agent's own conversation)
-# =============================================================================
-# Same var names as the MCP, but a separate process — set them here for the
-# CLI's chat model. Falls back to OPENAI_API_KEY.
-#
-# If you don't set BRAINROUTER_LLM_API_KEY here, the CLI also reads it from
-# `brainrouter/.env` as a transitional fallback. Setting it here makes the
-# CLI's choice explicit and lets you use a different chat model than the
-# MCP's extractor (e.g. gpt-4o for chat, gpt-4o-mini for extraction).
-BRAINROUTER_LLM_API_KEY=
-
-# OpenAI-compatible chat-completions endpoint.
-# Examples:
-#   OpenAI:                   https://api.openai.com/v1/chat/completions
-#   OpenRouter:               https://openrouter.ai/api/v1/chat/completions
-#   Anthropic via OpenRouter: model id "anthropic/claude-sonnet-4"
-#   LM Studio:                http://localhost:1234/v1/chat/completions
-BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
-BRAINROUTER_LLM_MODEL=gpt-4o-mini
-
-# Per-call timeout for the CLI's chat LLM. Default 120000 (2 min).
-# BRAINROUTER_LLM_TIMEOUT_MS=120000
-
-# Cap on concurrent in-flight chat LLM calls FROM THE CLI PROCESS.
-# Default 4 (separate from the MCP's own cap). Set to 1 for consumer-grade
-# local backends; raise to 16+ for cloud APIs.
-# BRAINROUTER_LLM_MAX_CONCURRENT=4
-
-
-# =============================================================================
-# 2. Tool runtime
-# =============================================================================
-# Per-tool timeout for CLI → MCP requests. Default 60000.
-# BRAINROUTER_MCP_TIMEOUT_MS=60000
-
-# LLM-visible clamp on a single tool-result body (full text still recorded
-# in the transcript on disk). Default 8000.
-# BRAINROUTER_MAX_TOOL_RESULT_CHARS=8000
-
-# Hard ceiling on tool-call iterations per turn. Default 60.
-# BRAINROUTER_MAX_TOOL_LOOPS=60
-
-# Estimated history-size trigger for auto-`/compact`. Default 80000 tokens.
-# BRAINROUTER_AUTO_COMPACT_TOKENS=80000
-
-
-# =============================================================================
-# 3. Sandbox (run_command)
-# =============================================================================
-# Wrap shell commands in the platform sandbox:
-#   macOS: sandbox-exec
-#   Linux: bwrap (preferred) or firejail
-# Set `on` to enable. Off by default.
-# BRAINROUTER_SANDBOX=on
-
-# Allow outbound network from sandboxed commands. Off by default.
-# BRAINROUTER_SANDBOX_NETWORK=off
-
-# Colon-separated read/write path allowlists.
-# BRAINROUTER_SANDBOX_READ_PATHS=/usr/local:/opt
-# BRAINROUTER_SANDBOX_WRITE_PATHS=/tmp
-
-
-# =============================================================================
-# 4. Workspace
-# =============================================================================
-# Override the workspace root the CLI uses for file tools + session key.
-# Most users let the CLI auto-detect via git / closest package.json.
-# BRAINROUTER_WORKSPACE=/path/to/project
-
-# Override per-user state root. Default: ~/.brainrouter.
-# Both the CLI and MCP honor this — set it once and both processes use it.
-# BRAINROUTER_HOME=/path/to/state
-
-
-# =============================================================================
-# 5. Web search
-# =============================================================================
-# Custom search backend for the web_search tool. Must accept
-#   POST { query, maxResults } → { results: [{ title, url, snippet }] }
-# Falls back to DuckDuckGo's Instant Answer API when unset.
-# Compatible with Brave Search API wrappers, Tavily, SerpAPI proxies, etc.
-# BRAINROUTER_WEB_SEARCH_ENDPOINT=https://your-search-proxy.example.com/search
-
-
-# =============================================================================
-# 6. Observability
-# =============================================================================
-# Path for OTEL-style JSONL turn traces. One line per turn/tool span.
-# Toggle at runtime with /trace on|off.
-# BRAINROUTER_TRACE_LOG=/path/to/trace.jsonl