@kinqs/brainrouter-cli 0.3.6 → 0.3.7

package/dist/orchestration/agentRegistry.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+// Resolved at import time from dist/orchestration/agentRegistry.js → ../../agents
+const BUILTIN_AGENTS_DIR = fileURLToPath(new URL('../../agents', import.meta.url));
+function getUserAgentsDir() {
+    const home = process.env.BRAINROUTER_HOME ?? path.join(os.homedir(), '.config', 'brainrouter');
+    return path.join(home, 'agents');
+}
+function getWorkspaceAgentsDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.brainrouter', 'agents');
+}
+function loadFromDir(dir, source) {
+    if (!fs.existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        const filePath = path.join(dir, entry);
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const def = JSON.parse(raw);
+            if (!def.id || typeof def.id !== 'string') {
+                console.error(`[agentRegistry] Skipping ${filePath}: missing or invalid "id" field.`);
+                continue;
+            }
+            results.push({ def, source, filePath });
+        }
+        catch (err) {
+            console.error(`[agentRegistry] Skipping ${filePath}: ${err.message}`);
+        }
+    }
+    return results;
+}
+/**
+ * Load all agent definitions from three tiers (builtin → user-global → workspace).
+ * Same `id` from a higher-priority source wins; distinct ids coexist.
+ */
+export function loadRegistry(workspaceRoot) {
+    const builtin = loadFromDir(BUILTIN_AGENTS_DIR, 'builtin');
+    const user = loadFromDir(getUserAgentsDir(), 'user');
+    const workspace = workspaceRoot
+        ? loadFromDir(getWorkspaceAgentsDir(workspaceRoot), 'workspace')
+        : [];
+    // Precedence: builtin first (lowest), workspace last (highest).
+    const merged = new Map();
+    for (const loaded of [...builtin, ...user, ...workspace]) {
+        merged.set(loaded.def.id, loaded);
+    }
+    return Array.from(merged.values());
+}
+export function findById(id, workspaceRoot) {
+    return loadRegistry(workspaceRoot).find((l) => l.def.id === id);
+}
+export function listAll(workspaceRoot) {
+    return loadRegistry(workspaceRoot);
+}

package/dist/orchestration/orchestrator.d.ts

@@ -1,4 +1,5 @@
 import { type AccessMode } from './roles.js';
+import type { Tier } from './agentRegistry.js';
 export type ChildStatus = 'pending' | 'running' | 'completed' | 'failed' | 'stale' | 'closed';
 export interface ChildSessionRecord {
     id: string;
@@ -14,6 +15,10 @@ export interface ChildSessionRecord {
     pid: number;
     finalOutput?: string;
     error?: string;
+    /** Agent tier from the definition (reasoning | worker). Undefined for legacy records. */
+    tier?: Tier;
+    /** Nesting depth in the spawn chain; 0 = direct child of the chat root. */
+    depth?: number;
     /** LLM usage attributable to this child (filled when the child completes). */
     usage?: {
         promptTokens: number;
@@ -30,6 +35,8 @@ export declare function createSession(workspaceRoot: string, input: {
     parentSessionKey: string;
     access?: AccessMode;
     label?: string;
+    tier?: Tier;
+    depth?: number;
 }): ChildSessionRecord;
 export declare function updateSession(workspaceRoot: string, id: string, patch: Partial<ChildSessionRecord>): ChildSessionRecord;
 export declare function reconcileStale(workspaceRoot: string): number;

package/dist/orchestration/orchestrator.js

@@ -28,6 +28,8 @@ export function createSession(workspaceRoot, input) {
         startedAt: now,
         updatedAt: now,
         pid: process.pid,
+        tier: input.tier,
+        depth: input.depth,
     };
     const data = readFile(workspaceRoot);
     data.sessions.push(record);

package/dist/orchestration/tools.d.ts

@@ -1,6 +1,7 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../runtime/mcpPool.js';
 import type { LLMConfig } from '../config/config.js';
 import { type AccessMode } from './roles.js';
+import { type Tier } from './agentRegistry.js';
 export interface OrchestrationContext {
     workspaceRoot: string;
     parentSessionKey: string;
@@ -21,6 +22,10 @@ export interface OrchestrationContext {
     parentSpanId?: string;
     /** Parent agent_id so children can be grouped via attribute even without trace links. */
     parentAgentId?: string;
+    /** Parent agent tier — used for hierarchy checks (worker cannot spawn; reasoning can only spawn workers). */
+    parentTier?: Tier;
+    /** Current spawn-chain depth (0 = direct child of chat root). */
+    depth?: number;
     mcpClient: McpClientWrapper;
     llmConfig: LLMConfig;
     launchCwd: string;
@@ -76,6 +81,10 @@ export declare function createSpawnAgentTool(): {
                 type: string;
                 description: string;
             };
+            agentId: {
+                type: string;
+                description: string;
+            };
             prompt: {
                 type: string;
                 description: string;

package/dist/orchestration/tools.js

@@ -1,6 +1,7 @@
 import { Agent } from '../agent/agent.js';
 import { createSession, formatSessionSummary, getSession, listSessions, updateSession, } from './orchestrator.js';
 import { buildRolePrompt, resolveRole } from './roles.js';
+import { findById, listAll } from './agentRegistry.js';
 import { buildSystemPrompt, loadWorkspaceInstructionSummary } from '../prompt/systemPrompt.js';
 import { readTranscriptEntries } from '../state/sessionStore.js';
 import { callMcpTool, childSessionKey } from '../runtime/mcpUtils.js';
@@ -100,11 +101,12 @@ export function trackedPromiseFor(id) {
 export function createSpawnAgentTool() {
     return {
         name: 'spawn_agent',
-        description: 'Spawn a child agent with a specific role (explorer, architect, reviewer, worker, verifier) and a bounded prompt. Returns the child agent id immediately; the child runs in the background.',
+        description: 'Spawn a child agent and a bounded prompt. Returns the child agent id immediately; the child runs in the background. Specify the agent via `role` (legacy: explorer/architect/reviewer/worker/verifier) or `agentId` (registry id, e.g. a custom workspace definition).',
         inputSchema: {
             type: 'object',
             properties: {
-                role: { type: 'string', description: 'One of: explorer, architect, reviewer, worker, verifier.' },
+                role: { type: 'string', description: 'One of: explorer, architect, reviewer, worker, verifier. Prefer agentId for custom definitions.' },
+                agentId: { type: 'string', description: 'Registry id of the agent definition. Takes precedence over role when both are provided.' },
                 prompt: { type: 'string', description: 'The bounded task prompt for the child agent.' },
                 label: { type: 'string', description: 'Optional short label for the child run.' },
                 access: { type: 'string', enum: ['read', 'write', 'shell'], description: 'Override the role default access mode. Default: role default.' },
@@ -116,7 +118,7 @@ export function createSpawnAgentTool() {
                     description: 'Optional BrainRouter memory record IDs that the parent already recalled. The child agent is told to build on these instead of re-discovering them.',
                 },
             },
-            required: ['role', 'prompt'],
+            required: ['prompt'],
         },
     };
 }
@@ -297,10 +299,47 @@ function explainRoute(task, role) {
     }
 }
 async function handleSpawn(args, ctx) {
-    const role = resolveRole(String(args.role));
+    // Resolve agent definition via agentId (registry) or role (legacy).
+    let role;
+    let childTier;
+    if (typeof args.agentId === 'string' && args.agentId.trim()) {
+        const loaded = findById(args.agentId.trim(), ctx.workspaceRoot);
+        if (!loaded) {
+            const known = listAll(ctx.workspaceRoot).map((l) => l.def.id).join(', ');
+            throw new Error(`Unknown agentId "${args.agentId}". Known agents: ${known}.`);
+        }
+        role = {
+            name: loaded.def.id,
+            description: loaded.def.whenToUse,
+            defaultAccess: loaded.def.defaultAccess,
+            promptOverlay: loaded.def.prompt,
+        };
+        childTier = loaded.def.tier;
+    }
+    else {
+        const roleName = String(args.role ?? '');
+        if (!roleName.trim())
+            throw new Error('spawn_agent requires either "agentId" or "role".');
+        role = resolveRole(roleName);
+        childTier = findById(role.name, ctx.workspaceRoot)?.def.tier;
+    }
     const prompt = String(args.prompt ?? '');
     if (!prompt.trim())
         throw new Error('spawn_agent requires a non-empty prompt.');
+    // P1.2 — spawn hierarchy checks.
+    const rawMaxDepth = parseInt(process.env.BRAINROUTER_MAX_SPAWN_DEPTH ?? '3', 10);
+    const maxDepth = Number.isFinite(rawMaxDepth) && rawMaxDepth > 0 ? rawMaxDepth : 3;
+    const currentDepth = ctx.depth ?? 0;
+    const parentTier = ctx.parentTier;
+    if (parentTier === 'worker') {
+        throw new Error('Tier "worker" cannot delegate — ask the parent agent to spawn instead.');
+    }
+    if (parentTier === 'reasoning' && childTier && (childTier === 'chat' || childTier === 'reasoning')) {
+        throw new Error(`Tier "reasoning" cannot spawn a "${childTier}" agent — only "worker" children are allowed.`);
+    }
+    if (currentDepth >= maxDepth) {
+        throw new Error(`Spawn depth cap reached (${currentDepth}/${maxDepth}). Reduce agent nesting or raise BRAINROUTER_MAX_SPAWN_DEPTH.`);
+    }
     const requested = args.access ?? role.defaultAccess;
     const access = clampAccess(ctx.parentAccessMode ?? 'shell', requested);
     const record = createSession(ctx.workspaceRoot, {
@@ -309,6 +348,8 @@ async function handleSpawn(args, ctx) {
         parentSessionKey: ctx.parentSessionKey,
         access,
         label: typeof args.label === 'string' ? args.label : undefined,
+        tier: childTier,
+        depth: currentDepth + 1,
     });
     const childKey = childSessionKey(ctx.parentSessionKey, record.id);
     const seededIds = Array.isArray(args.seedRecordIds)
@@ -346,6 +387,9 @@ async function handleSpawn(args, ctx) {
         // dispatching spawn_agent tool span instead of starting a fresh tree.
         parentTraceId: ctx.parentTraceId,
         parentSpanId: ctx.parentSpanId,
+        // Propagate tier and depth so grandchildren can enforce hierarchy caps.
+        tier: childTier,
+        agentDepth: currentDepth + 1,
     });
     if (ctx.parentAgentId)
         childAgent.setParentAgentId(ctx.parentAgentId);

package/dist/prompt/skillCatalog.d.ts

@@ -0,0 +1,11 @@
+export interface SkillListItem {
+    name: string;
+    scope?: string;
+    category?: string;
+    description?: string;
+    source?: 'mcp' | 'filesystem';
+}
+export declare function listFilesystemSkills(workspaceRoot: string): SkillListItem[];
+export declare function mergeSkillLists(primary: SkillListItem[], fallback: SkillListItem[]): SkillListItem[];
+export declare function sortSkills(a: SkillListItem, b: SkillListItem): number;
+export declare function skillSearchRoots(workspaceRoot: string): string[];

package/dist/prompt/skillCatalog.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const requireFromHere = createRequire(import.meta.url);
+const WORKSPACE_SKILL_ROOTS = ['skills', '.brainrouter/skills'];
+export function listFilesystemSkills(workspaceRoot) {
+    const seen = new Map();
+    for (const root of skillSearchRoots(workspaceRoot)) {
+        if (!fs.existsSync(root))
+            continue;
+        const scope = inferRootScope(root, workspaceRoot);
+        for (const filePath of findSkillFiles(root)) {
+            const parsed = parseSkillFile(filePath);
+            if (!parsed)
+                continue;
+            const rel = path.relative(root, filePath);
+            const category = rel.split(path.sep)[0] || 'uncategorized';
+            if (!seen.has(parsed.name)) {
+                seen.set(parsed.name, {
+                    name: parsed.name,
+                    category,
+                    description: parsed.description,
+                    scope,
+                    source: 'filesystem',
+                });
+            }
+        }
+    }
+    return Array.from(seen.values()).sort(sortSkills);
+}
+export function mergeSkillLists(primary, fallback) {
+    const merged = new Map();
+    for (const skill of primary) {
+        merged.set(skill.name, { ...skill, source: skill.source ?? 'mcp' });
+    }
+    for (const skill of fallback) {
+        if (!merged.has(skill.name))
+            merged.set(skill.name, skill);
+    }
+    return Array.from(merged.values()).sort(sortSkills);
+}
+export function sortSkills(a, b) {
+    return (a.category ?? '').localeCompare(b.category ?? '') || a.name.localeCompare(b.name);
+}
+export function skillSearchRoots(workspaceRoot) {
+    const roots = [];
+    for (const sub of WORKSPACE_SKILL_ROOTS)
+        roots.push(path.join(workspaceRoot, sub));
+    const mcpPkgDir = resolveInstalledMcpPackageDir();
+    if (mcpPkgDir) {
+        roots.push(path.join(mcpPkgDir, 'skills'));
+        const monorepoRoot = path.dirname(mcpPkgDir);
+        roots.push(path.join(monorepoRoot, 'skills'));
+    }
+    return [...new Set(roots.map((root) => path.resolve(root)))];
+}
+function resolveInstalledMcpPackageDir() {
+    try {
+        const pkgJsonPath = requireFromHere.resolve('@kinqs/brainrouter-mcp-server/package.json');
+        return path.dirname(pkgJsonPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function inferRootScope(root, workspaceRoot) {
+    const resolvedWorkspace = path.resolve(workspaceRoot);
+    const resolvedRoot = path.resolve(root);
+    if (resolvedRoot.startsWith(path.join(resolvedWorkspace, '.brainrouter')))
+        return 'local';
+    if (isBrainRouterRepoRoot(path.dirname(resolvedRoot)))
+        return 'global';
+    return resolvedRoot.startsWith(resolvedWorkspace) ? 'local' : 'global';
+}
+function isBrainRouterRepoRoot(root) {
+    return (fs.existsSync(path.join(root, 'brainrouter', 'package.json')) &&
+        fs.existsSync(path.join(root, 'brainrouter-cli', 'package.json')) &&
+        fs.existsSync(path.join(root, 'skills')));
+}
+function findSkillFiles(root) {
+    const results = [];
+    function walk(current, depth) {
+        if (depth < 0)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === 'node_modules' || entry.name === '.git')
+                continue;
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                walk(full, depth - 1);
+            else if (entry.isFile() && entry.name === 'SKILL.md')
+                results.push(full);
+        }
+    }
+    walk(root, 5);
+    return results;
+}
+function parseSkillFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const frontmatter = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const block = frontmatter?.[1] ?? '';
+    const name = readYamlScalar(block, 'name') ?? path.basename(path.dirname(filePath));
+    const description = readYamlScalar(block, 'description') ?? firstParagraph(raw);
+    if (!name)
+        return undefined;
+    return { name, description };
+}
+function readYamlScalar(block, key) {
+    const match = block.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+    if (!match?.[1])
+        return undefined;
+    return match[1].trim().replace(/^['"]|['"]$/g, '');
+}
+function firstParagraph(raw) {
+    const withoutFrontmatter = raw.replace(/^---\r?\n[\s\S]*?\r?\n---/, '').trim();
+    const line = withoutFrontmatter
+        .split(/\r?\n/)
+        .map((part) => part.trim())
+        .find((part) => part && !part.startsWith('#'));
+    return line;
+}

package/dist/prompt/skillRunner.d.ts

@@ -1,4 +1,4 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClient } from '../runtime/mcpUtils.js';
 export interface SkillResolution {
     name: string;
     body: string;
@@ -24,7 +24,7 @@ export declare const SLASH_TO_SKILL: Record<string, string>;
  * server has loaded, including their own private skills), falls back to a
  * local filesystem scan of `skills/` for when the MCP tool is unavailable.
  */
-export declare function resolveSkill(mcpClient: McpClientWrapper, name: string, workspaceRoot: string, section?: RunSkillOptions['section']): Promise<SkillResolution>;
+export declare function resolveSkill(mcpClient: McpClient, name: string, workspaceRoot: string, section?: RunSkillOptions['section']): Promise<SkillResolution>;
 /**
  * Build the user prompt that asks the agent to execute a skill. The skill
  * body is embedded so the agent does not need to round-trip through

package/dist/prompt/skillRunner.js

@@ -1,7 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { createRequire } from 'node:module';
-const requireFromHere = createRequire(import.meta.url);
+import { skillSearchRoots } from './skillCatalog.js';
 /**
  * Slash-command → skill mapping. Each entry names the skill catalogued in
  * the BrainRouter skills/ folder (and exposed by the MCP server) that the
@@ -21,7 +20,6 @@ export const SLASH_TO_SKILL = {
     '/refactor': 'code-simplification',
     '/test': 'testing-skill',
 };
-const WORKSPACE_SKILL_ROOTS = ['skills', '.brainrouter/skills'];
 /**
  * Resolve a skill by name. Prefers the MCP server (so users get whatever the
  * server has loaded, including their own private skills), falls back to a
@@ -61,34 +59,7 @@ function readSkillFromFilesystem(workspaceRoot, name) {
     }
     return undefined;
 }
-/**
- * Roots to search for SKILL.md when the MCP server is unavailable. Includes:
- *  - the user's workspace (so per-project skills win locally)
- *  - the installed @kinqs/brainrouter-mcp-server package directory (so the canonical
- *    BrainRouter catalogue is found even when MCP is down, because prepack
- *    bundles `skills/` into the published package)
- *  - the monorepo root (when running from source during development)
- */
-function skillSearchRoots(workspaceRoot) {
-    const roots = [];
-    for (const sub of WORKSPACE_SKILL_ROOTS) {
-        roots.push(path.join(workspaceRoot, sub));
-    }
-    const mcpPkgDir = resolveInstalledMcpPackageDir();
-    if (mcpPkgDir)
-        roots.push(path.join(mcpPkgDir, 'skills'));
-    return roots;
-}
-function resolveInstalledMcpPackageDir() {
-    try {
-        const pkgJsonPath = requireFromHere.resolve('@kinqs/brainrouter-mcp-server/package.json');
-        return path.dirname(pkgJsonPath);
-    }
-    catch {
-        return undefined;
-    }
-}
-function findSkillDir(rootDir, skillName, depth = 3) {
+function findSkillDir(rootDir, skillName, depth = 5) {
     if (depth < 0)
         return undefined;
     let entries;

package/dist/prompt/systemPrompt.js

@@ -77,7 +77,11 @@ function clarifyOverlay(activeSkill) {
 function isBrainOnline(connectedTools) {
     if (!connectedTools)
         return true;
-    return connectedTools.includes('memory_recall');
+    // Match bare `memory_recall`, double-underscore `mcp__<server>__memory_recall`,
+    // and single-underscore `mcp_<server>_memory_recall` (both prefix conventions
+    // are in use across the multi-MCP codepaths until naming is unified).
+    return connectedTools.some((tool) => tool === 'memory_recall' ||
+        (tool.startsWith('mcp_') && tool.endsWith('memory_recall')));
 }
 function brainOfflineNotice() {
     return [

package/dist/runtime/mcpClient.js

@@ -23,7 +23,7 @@ export class McpClientWrapper {
     identity = 'unknown';
     serverName;
     constructor() {
-        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.5' }, { capabilities: {} });
+        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.7' }, { capabilities: {} });
     }
     /** Whether this wrapper has an active MCP transport. */
     isConnected() {
@@ -139,16 +139,11 @@ export class McpClientWrapper {
             if (llmConfig?.model && !mergedEnv.BRAINROUTER_LLM_MODEL) {
                 mergedEnv.BRAINROUTER_LLM_MODEL = llmConfig.model;
             }
-            // Loud diagnostic: if NO LLM key reached the child, server-side
-            // memory extraction is dead — every sensory capture will pile up
-            // un-extracted. Print a yellow banner so the user knows BEFORE they
-            // see "0 records" in every briefing.
-            if (!mergedEnv.BRAINROUTER_LLM_API_KEY) {
-                console.warn('\n⚠️  No LLM API key reached the MCP child. Sensory turns will be ' +
-                    'captured but cognitive extraction (the thing that makes them ' +
-                    'searchable) will fail silently. Set OPENAI_API_KEY or ' +
-                    'BRAINROUTER_LLM_API_KEY before starting brainrouter.\n');
-            }
+            // (Previously: a loud console.warn here if no LLM API key reached the
+            // MCP child. That message landed above the Ink banner and looked like a
+            // CLI error even though it was a server-side concern. Server-side
+            // extraction failures should surface through MCP's own status channel —
+            // not by the CLI second-guessing what the server needs.)
             // Spawn the MCP child with cwd set to the MCP package directory if we
             // can find it from the first arg (typically
             // `node /path/to/BrainRouter/brainrouter/dist/index.js`). The child
@@ -179,6 +174,14 @@ export class McpClientWrapper {
                 args: serverConfig.args ?? [],
                 env: mergedEnv,
                 cwd: childCwd,
+                // The MCP child is a separate process with its own concerns (its own
+                // dotenv, its own auth failures, its own platform warnings). Inheriting
+                // its stderr meant every `[BrainRouter] FATAL …`, every dotenv banner,
+                // every SQLite ExperimentalWarning leaked above our Ink chat banner
+                // and looked like the CLI was crashing. Pipe it so the SDK owns the
+                // stream; the CLI can surface a single graceful "MCP unreachable" line
+                // through its own offline-mode flow instead.
+                stderr: 'pipe',
             });
             await this.client.connect(this.transport);
             this.connected = true;

package/dist/runtime/mcpPool.d.ts

@@ -0,0 +1,162 @@
+import { McpClientWrapper } from './mcpClient.js';
+import type { LLMConfig, ServerConfig } from '../config/config.js';
+/**
+ * 0.3.7 — Multi-MCP support. Wraps a `Map<serverId, McpClientWrapper>`
+ * and exposes the same public API as a single wrapper (`isConnected`,
+ * `getIdentity`, `getServerName`, `listTools`, `callTool`, `close`),
+ * so existing call-sites that hold an `mcpClient` reference keep
+ * working unchanged.
+ *
+ * Pattern lifted from Claude Code's `.mcp.json` model (see
+ * `openSrc/claude-code/CHANGELOG.md` — concurrent startup at line 688,
+ * tool prefixing at line 1515, graceful degradation at line 189). Our
+ * shape:
+ *
+ *   - All configured servers attempt connection concurrently on boot,
+ *     each with a 5s timeout. Offline ones do NOT block others.
+ *   - Tools surface to the agent with `mcp_<serverId>_<toolName>`
+ *     prefix (Claude Code style).
+ *   - `callTool` accepts BOTH the prefixed form (the canonical name
+ *     the LLM sees in the tool inventory) AND the raw form (back-compat
+ *     for the existing system prompt and skills that hardcode
+ *     `memory_recall` etc.). Raw form routes to the unique server
+ *     providing that tool name; collision (two servers expose the same
+ *     unprefixed name) returns a helpful error pointing at the
+ *     prefixed form.
+ *
+ * Future versions may drop the raw-name fallback once skills and
+ * prompts are migrated to prefixed names; the pool then becomes the
+ * pure Claude Code shape. Until then the dual-name resolution is a
+ * transition aid documented in CHANGELOG `[0.3.7]`.
+ */
+export type McpServerStatus = {
+    serverId: string;
+    identity: 'brainrouter' | 'third-party' | 'unknown';
+    /** 'connected' once the underlying wrapper reports isConnected. */
+    status: 'connected' | 'connecting' | 'offline' | 'failed';
+    /** Filled after the first successful listTools (used by /mcp list). */
+    toolCount?: number;
+    /** Per-server error message when status === 'failed'. */
+    error?: string;
+};
+/**
+ * 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 declare function selectMcpServerIds(servers: Record<string, ServerConfig>, activeServer?: string, requestedProfile?: string): string[];
+export declare class McpClientPool {
+    /** serverId → connected wrapper. */
+    private clients;
+    /** serverId → status entry (kept even for failed/offline servers so /mcp can render them). */
+    private statuses;
+    /**
+     * Unprefixed tool name → owning serverId. Sentinel `__COLLISION__`
+     * marks tool names exposed by multiple servers (must be addressed
+     * via the prefixed form).
+     */
+    private toolToServer;
+    /** Prefixed form (`mcp_<serverId>_<tool>`) → `{serverId, tool}` for fast dispatch. */
+    private prefixedToServer;
+    /** LLM config from the last connectAll — needed for reconnect calls. */
+    private currentLlmConfig?;
+    /** Raw server configs from the last connectAll — needed for /mcp reconnect <id>. */
+    private serverConfigs;
+    /** serverId → prefix used in tool names. Brainrouter servers get "brainrouter"; others keep their config key. */
+    private prefixIds;
+    /** Reverse: prefixId → serverId (needed to dispatch `mcp_brainrouter_X` back to the real key). */
+    private prefixToServerId;
+    private getPrefixId;
+    private assignPrefixId;
+    /**
+     * 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.
+     */
+    connectAll(servers: Record<string, ServerConfig>, llmConfig?: LLMConfig, options?: {
+        timeoutMs?: number;
+        onStatusChange?: (s: McpServerStatus) => void;
+    }): Promise<McpServerStatus[]>;
+    /**
+     * 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.
+     */
+    connectOne(serverId: string, config: ServerConfig, llmConfig?: LLMConfig, timeoutMs?: number): Promise<void>;
+    /** Tear down a single server. Removes it from the pool and rebuilds the tool index. */
+    disconnectOne(serverId: string): Promise<void>;
+    /** Reconnect: close + connect again using the stashed config. */
+    reconnectOne(serverId: string): Promise<void>;
+    /**
+     * 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`.
+     */
+    private refreshToolIndex;
+    /**
+     * 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.
+     */
+    listTools(): Promise<{
+        tools: any[];
+    }>;
+    /**
+     * 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).
+     */
+    callTool(name: string, args: Record<string, any>): Promise<any>;
+    /** Internal — map a name (prefixed OR raw) to a concrete server + tool. */
+    private resolveToolCall;
+    /** True iff at least one server is connected. */
+    isConnected(): boolean;
+    /**
+     * 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(): 'brainrouter' | 'third-party' | '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(): string | undefined;
+    /**
+     * Look up a wrapper by serverId. Used by `/mcp tools <server>` and
+     * similar commands that want to talk to one specific server.
+     */
+    getClient(serverId: string): McpClientWrapper | undefined;
+    /**
+     * 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(): McpClientWrapper | undefined;
+    /** Server id for the currently connected BrainRouter MCP, if one is active. */
+    getActiveBrainrouterServerId(): string | undefined;
+    /** Status snapshot for every server the pool has tried to connect to. */
+    getStatuses(): McpServerStatus[];
+    /** Status for one server (returns undefined if the pool has never seen it). */
+    getStatus(serverId: string): McpServerStatus | undefined;
+    /** List of serverIds currently held by the pool (connected or not). */
+    getServerIds(): string[];
+    /** Close every wrapper. Used on CLI exit. */
+    close(): Promise<void>;
+}