@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/cli/commands/mcp.js

@@ -0,0 +1,286 @@
+/**
+ * `/mcp` slash-command surface. 0.3.7 multi-MCP rewrite — third-party
+ * MCPs connect concurrently while BrainRouter MCP profiles are mutually
+ * exclusive so exactly one brain is active at a time.
+ *
+ *   /mcp                    — alias for /mcp list
+ *   /mcp list               — every configured profile + per-server status
+ *   /mcp tools [server]     — MCP tools grouped by `mcp__<server>__*`
+ *                             namespace; pass a server id to scope
+ *   /mcp connect <name>     — connect a configured server that's idle/offline
+ *   /mcp disconnect <name>  — close one server's transport (config preserved)
+ *   /mcp reconnect [name]   — reconnect ONE (when name given) or the selected pool
+ *
+ * Backwards-compat: `/mcp reconnect` with no arg reconnects the same
+ * selected set used at boot: all third-party MCPs plus the active
+ * BrainRouter MCP. Pass an explicit name to target one.
+ */
+import chalk from 'chalk';
+import { spinner as makeSpinner } from '../spinner.js';
+import { saveConfig } from '../../config/config.js';
+import { resolveIdentityFromConfig } from '../../runtime/mcpClient.js';
+import { selectMcpServerIds } from '../../runtime/mcpPool.js';
+import { buildBannerInputs, renderBanner } from '../banner.js';
+import { resolveTheme } from '../theme.js';
+export async function tryHandleMcpCommand(ctx) {
+    const { command, args, mcpClient, config } = ctx;
+    if (command !== '/mcp')
+        return false;
+    const sub = (args[0] ?? 'list').toLowerCase();
+    const targetName = args[1]?.trim();
+    if (sub === 'tools') {
+        const onlyServer = targetName;
+        console.log(chalk.bold('\nMCP tools (pooled)'));
+        const statuses = mcpClient.getStatuses();
+        const connected = statuses.filter((s) => s.status === 'connected');
+        if (connected.length === 0) {
+            console.log(chalk.yellow('  No MCP servers connected. Try /mcp reconnect.\n'));
+            return true;
+        }
+        const spinner = makeSpinner(chalk.gray('Fetching pooled tool surface...')).start();
+        try {
+            const res = await mcpClient.listTools();
+            const allTools = res.tools || [];
+            spinner.succeed(chalk.green(`${allTools.length} tools across ${connected.length} server${connected.length === 1 ? '' : 's'}`));
+            // Pool tools are exposed as `mcp__<serverId>__<rawTool>`. Group by serverId.
+            const byServer = {};
+            for (const t of allTools) {
+                const m = /^mcp__([^_]+(?:_[^_]+)*?)__(.+)$/.exec(t.name);
+                const serverId = m?.[1] ?? '__unknown__';
+                const raw = m?.[2] ?? t.name;
+                if (onlyServer && serverId !== onlyServer)
+                    continue;
+                (byServer[serverId] ||= []).push(raw);
+            }
+            const serverIds = Object.keys(byServer).sort();
+            if (serverIds.length === 0) {
+                console.log(chalk.gray(`\n  No tools for server "${onlyServer}".\n`));
+                return true;
+            }
+            for (const section of groupServerIdsByEcosystem(serverIds, (id) => mcpClient.getStatus(id)?.identity ?? 'unknown')) {
+                console.log(`\n${section.title}`);
+                for (const id of section.ids) {
+                    const ident = mcpClient.getStatus(id)?.identity ?? 'unknown';
+                    const identTag = formatIdentityTag(ident);
+                    console.log(`  ${chalk.bold.green(id)} ${identTag} (${byServer[id].length})`);
+                    for (const name of byServer[id].sort()) {
+                        console.log(`    ${chalk.gray('•')} ${name}  ${chalk.gray(`mcp__${id}__${name}`)}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            spinner.fail(chalk.red(`Failed: ${err.message}`));
+        }
+        console.log();
+        return true;
+    }
+    if (sub === 'list') {
+        const profiles = Object.keys(config.servers ?? {});
+        if (profiles.length === 0) {
+            console.log(chalk.yellow('\nNo MCP profiles configured. Run `/login` or `brainrouter config` to set one up.\n'));
+            return true;
+        }
+        console.log(chalk.bold('\nMCP servers'));
+        const statuses = mcpClient.getStatuses();
+        const statusById = new Map(statuses.map((s) => [s.serverId, s]));
+        const activeName = config.activeServer;
+        for (const section of groupServerIdsByEcosystem(profiles, (name) => {
+            const profile = config.servers[name];
+            return statusById.get(name)?.identity ?? profile?.identity ?? 'unknown';
+        })) {
+            console.log(`\n${section.title}`);
+            for (const name of section.ids) {
+                const profile = config.servers[name];
+                const poolStatus = statusById.get(name);
+                // Identity: pool live > config metadata > 'unknown'.
+                const identity = poolStatus?.identity ?? profile.identity ?? 'unknown';
+                // Status: pool live > 'not in pool' (configured but never tried).
+                const liveStatus = poolStatus?.status;
+                const statusLabel = liveStatus === 'connected' ? chalk.green('online') :
+                    liveStatus === 'failed' ? chalk.red('failed') :
+                        liveStatus === 'connecting' ? chalk.yellow('connecting') :
+                            liveStatus === 'offline' ? chalk.gray('disconnected') :
+                                chalk.gray('idle');
+                const idLabel = formatIdentityTag(identity);
+                const marker = name === activeName ? chalk.bold('★ ') : '  ';
+                const transport = profile.type;
+                const target = profile.type === 'http' ? profile.url ?? '<no url>' : profile.command ?? '<no command>';
+                const toolTag = poolStatus?.toolCount != null ? chalk.gray(`${poolStatus.toolCount} tools`) : '';
+                const errTag = liveStatus === 'failed' && poolStatus?.error ? chalk.red(` · ${poolStatus.error}`) : '';
+                console.log(`${marker}${chalk.bold(name)}  ${idLabel}  ${transport}  ${statusLabel}  ${chalk.gray(target)}  ${toolTag}${errTag}`);
+            }
+        }
+        console.log(chalk.gray('\n★ = highlighted profile in the banner.'));
+        console.log(chalk.gray('  Multi-MCP: third-party MCPs connect together; only one BrainRouter MCP is active. Use /mcp connect|disconnect|reconnect <name> to manage.\n'));
+        return true;
+    }
+    if (sub === 'reconnect') {
+        if (!targetName) {
+            // No name → reconnect every configured server in the pool.
+            const ids = selectMcpServerIds(config.servers ?? {}, config.activeServer);
+            if (ids.length === 0) {
+                console.log(chalk.red(`\nNo MCP profiles configured.\n`));
+                return true;
+            }
+            console.log(chalk.gray(`Reconnecting all servers (${ids.length})…`));
+            await Promise.allSettled(ids.map(async (id) => {
+                try {
+                    await mcpClient.reconnectOne(id);
+                    const s = mcpClient.getStatus(id);
+                    if (s?.status === 'connected') {
+                        console.log(chalk.green(`  ✓ ${id}`));
+                    }
+                    else {
+                        console.log(chalk.red(`  ✗ ${id} — ${s?.error ?? 'failed'}`));
+                    }
+                }
+                catch (err) {
+                    console.log(chalk.red(`  ✗ ${id} — ${err?.message ?? err}`));
+                }
+            }));
+            console.log();
+            return true;
+        }
+        if (!config.servers?.[targetName]) {
+            console.log(chalk.red(`\nNo profile named "${targetName}".\n`));
+            return true;
+        }
+        console.log(chalk.gray(`Reconnecting "${targetName}"…`));
+        try {
+            await disconnectOtherBrainrouterServers(ctx, targetName);
+            await mcpClient.reconnectOne(targetName);
+            const s = mcpClient.getStatus(targetName);
+            if (s?.status === 'connected') {
+                const activated = activateBrainrouterProfile(ctx, targetName);
+                console.log(chalk.green(`✓ Reconnected to "${targetName}".\n`));
+                if (activated) {
+                    console.log(chalk.gray(`  Active BrainRouter profile saved as "${targetName}" for this and future sessions.\n`));
+                    printRefreshedBanner(ctx);
+                }
+            }
+            else {
+                console.log(chalk.red(`✗ "${targetName}" remained ${s?.status ?? 'offline'} — ${s?.error ?? 'unknown'}\n`));
+            }
+        }
+        catch (err) {
+            console.log(chalk.red(`✗ Reconnect failed: ${err?.message ?? err}\n`));
+        }
+        return true;
+    }
+    if (sub === 'connect') {
+        if (!targetName) {
+            console.log(chalk.red('\nUsage: /mcp connect <name>\n'));
+            return true;
+        }
+        const profile = config.servers?.[targetName];
+        if (!profile) {
+            console.log(chalk.red(`\nNo profile named "${targetName}". Available: ${Object.keys(config.servers ?? {}).join(', ') || '(none)'}.\n`));
+            return true;
+        }
+        console.log(chalk.gray(`Connecting "${targetName}"…`));
+        try {
+            await disconnectOtherBrainrouterServers(ctx, targetName);
+            await mcpClient.connectOne(targetName, profile, config.llm, 5_000);
+            const s = mcpClient.getStatus(targetName);
+            if (s?.status === 'connected') {
+                const activated = activateBrainrouterProfile(ctx, targetName);
+                console.log(chalk.green(`✓ "${targetName}" online (${s.toolCount ?? 0} tools).\n`));
+                if (activated) {
+                    console.log(chalk.gray(`  Active BrainRouter profile saved as "${targetName}" for this and future sessions.\n`));
+                    printRefreshedBanner(ctx);
+                }
+            }
+            else {
+                console.log(chalk.red(`✗ "${targetName}" failed — ${s?.error ?? 'unknown'}\n`));
+            }
+        }
+        catch (err) {
+            console.log(chalk.red(`✗ Connect failed: ${err?.message ?? err}\n`));
+        }
+        return true;
+    }
+    if (sub === 'disconnect') {
+        if (!targetName) {
+            console.log(chalk.red('\nUsage: /mcp disconnect <name>\n'));
+            return true;
+        }
+        if (!mcpClient.getStatus(targetName)) {
+            console.log(chalk.yellow(`\n"${targetName}" is not in the pool.\n`));
+            return true;
+        }
+        try {
+            await mcpClient.disconnectOne(targetName);
+            console.log(chalk.green(`✓ "${targetName}" disconnected. Config preserved — /mcp connect ${targetName} to bring it back.\n`));
+        }
+        catch (err) {
+            console.log(chalk.red(`✗ Disconnect failed: ${err?.message ?? err}\n`));
+        }
+        return true;
+    }
+    console.log(chalk.red(`\nUnknown /mcp subcommand "${sub}". Usage: /mcp list | /mcp tools [server] | /mcp connect <name> | /mcp disconnect <name> | /mcp reconnect [name]\n`));
+    return true;
+}
+function formatIdentityTag(identity) {
+    return identity === 'brainrouter' ? chalk.cyan('brainrouter') :
+        identity === 'third-party' ? chalk.yellow('third-party') :
+            chalk.gray('unknown');
+}
+function groupServerIdsByEcosystem(ids, identityFor) {
+    const brainrouter = [];
+    const other = [];
+    for (const id of ids.slice().sort()) {
+        if (identityFor(id) === 'brainrouter')
+            brainrouter.push(id);
+        else
+            other.push(id);
+    }
+    const sections = [];
+    if (brainrouter.length > 0) {
+        sections.push({ title: chalk.bold.cyan('BrainRouter MCP (Our Ecosystem)'), ids: brainrouter });
+    }
+    if (other.length > 0) {
+        sections.push({ title: chalk.bold.yellow('Third-party MCPs (Other)'), ids: other });
+    }
+    return sections;
+}
+async function disconnectOtherBrainrouterServers(ctx, targetName) {
+    const targetProfile = ctx.config.servers?.[targetName];
+    if (!targetProfile)
+        return;
+    if (resolveIdentityFromConfig(targetProfile, targetName) !== 'brainrouter')
+        return;
+    for (const [id, profile] of Object.entries(ctx.config.servers ?? {})) {
+        if (id === targetName)
+            continue;
+        if (resolveIdentityFromConfig(profile, id) !== 'brainrouter')
+            continue;
+        const status = ctx.mcpClient.getStatus(id);
+        if (status?.status === 'connected' || status?.status === 'connecting') {
+            await ctx.mcpClient.disconnectOne(id);
+        }
+    }
+}
+function activateBrainrouterProfile(ctx, targetName) {
+    const status = ctx.mcpClient.getStatus(targetName);
+    const profile = ctx.config.servers?.[targetName];
+    const isBrainrouter = status?.identity === 'brainrouter' ||
+        (profile ? resolveIdentityFromConfig(profile, targetName) === 'brainrouter' : false);
+    if (!isBrainrouter)
+        return false;
+    ctx.config.activeServer = targetName;
+    saveConfig(ctx.config);
+    return true;
+}
+function printRefreshedBanner(ctx) {
+    const theme = resolveTheme(ctx.agent.workspaceRoot);
+    const banner = renderBanner(buildBannerInputs(ctx.config, ctx.agent, ctx.mcpClient), theme);
+    if (ctx.repl.replaceBanner) {
+        ctx.repl.replaceBanner('\n' + banner);
+    }
+    else {
+        console.log(chalk.gray('Updated active BrainRouter banner:'));
+        console.log(banner);
+        console.log();
+    }
+}

package/dist/cli/commands/memory.js

@@ -11,7 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
-import ora from 'ora';
+import { spinner as makeSpinner } from '../spinner.js';
 import { callMcpTool } from '../../runtime/mcpUtils.js';
 import { extractMemories, renderMemoryCards } from '../../memory/formatters.js';
 import { consolidateMemories } from '../../memory/consolidation.js';
@@ -237,7 +237,7 @@ export async function tryHandleMemoryCommand(ctx) {
                 return true;
             }
             if (sub === 'consolidate') {
-                const spinner = ora(chalk.gray('Consolidating memories from MCP into filesystem artifacts...')).start();
+                const spinner = makeSpinner(chalk.gray('Consolidating memories from MCP into filesystem artifacts...')).start();
                 try {
                     const result = await consolidateMemories(mcpClient, agent.workspaceRoot, { sessionKey: agent.sessionKey });
                     spinner.succeed(chalk.green(`Consolidated ${result.totalRecords} records.`));

package/dist/cli/commands/obs.js

@@ -98,21 +98,23 @@ export async function tryHandleObsCommand(ctx) {
             {
                 const session = agent.sessionUsage;
                 const metrics = agent.memoryMetrics;
-                const children = listSessions(agent.workspaceRoot).filter((s) => s.usage);
+                // Scope to the live parent: sessions.json is workspace-wide and
+                // persists across CLI restarts, so an unfiltered list mixes in every
+                // child spawned by every prior CLI process. Filtering by
+                // parentSessionKey limits the row to children spawned by THIS parent.
+                const children = listSessions(agent.workspaceRoot).filter((s) => s.usage && s.parentSessionKey === agent.sessionKey);
                 const childPrompt = children.reduce((acc, c) => acc + (c.usage?.promptTokens ?? 0), 0);
                 const childCompletion = children.reduce((acc, c) => acc + (c.usage?.completionTokens ?? 0), 0);
                 const childCalls = children.reduce((acc, c) => acc + (c.usage?.calls ?? 0), 0);
-                // Memory savings estimate:
-                // - Each recalled record (avg ~200 chars ≈ 50 tokens) supplies cross-
-                //   session context that would otherwise require either a manual
-                //   user explanation, a re-read of files, or skill re-discovery.
-                //   Conservative multiplier of 5× to account for the "without memory
-                //   you would have read 3-5 files" replacement cost.
-                // - Offloaded child output bytes are subtracted from what the parent
-                //   would otherwise have had to carry in context.
-                const recallSavings = metrics.briefingTokensInjected * 5;
-                const offloadSavings = Math.round(metrics.offloadCharsAvoided / 4);
-                const totalSaved = recallSavings + offloadSavings;
+                // What we can actually measure:
+                //   - offload: bytes of child output that did NOT land in the parent's
+                //     context. These are real tokens not spent on the parent. We
+                //     subtract the preview that DID land (OFFLOAD_PREVIEW_CHARS is
+                //     already netted out in tools.ts before recordOffload fires).
+                //   - briefing tokens: cost, not savings. They're already counted in
+                //     session.promptTokens. We report them so the user can see how
+                //     much of the prompt budget memory is consuming.
+                const offloadSavedTokens = Math.round(metrics.offloadCharsAvoided / 4);
                 const totalSpent = session.promptTokens + session.completionTokens + childPrompt + childCompletion;
                 console.log(chalk.bold('\nToken usage — this session'));
                 console.log(`  Parent: ${chalk.cyan(session.promptTokens.toLocaleString())}↑  ${chalk.cyan(session.completionTokens.toLocaleString())}↓  ${chalk.gray(`(${session.turns} turn${session.turns === 1 ? '' : 's'}, ${session.calls} LLM call${session.calls === 1 ? '' : 's'})`)}`);
@@ -126,17 +128,15 @@ export async function tryHandleObsCommand(ctx) {
                         console.log(chalk.gray(`    …and ${children.length - 5} more (see /agents)`));
                 }
                 console.log(`  Total this session: ${chalk.bold.cyan(totalSpent.toLocaleString())} tokens`);
-                console.log(chalk.bold('\nMemory savings (estimated)'));
-                console.log(`  Briefing tokens injected:  ${chalk.gray(metrics.briefingTokensInjected.toLocaleString())}  (${metrics.recallRecordsConsulted} records consulted)`);
-                console.log(`  Cross-session recall value: ~${chalk.green(recallSavings.toLocaleString())} tokens you'd otherwise spend re-reading files / re-explaining context`);
-                console.log(`  Offload bytes avoided:     ${chalk.gray(metrics.offloadCharsAvoided.toLocaleString())} chars (large child outputs that stayed out of parent context)`);
-                console.log(`  → Offload value:           ~${chalk.green(offloadSavings.toLocaleString())} tokens`);
-                console.log(`  ${chalk.bold('Total estimated savings:')}  ${chalk.bold.green('~' + totalSaved.toLocaleString())} tokens`);
-                if (totalSpent > 0) {
-                    const ratio = totalSaved / totalSpent;
-                    console.log(chalk.gray(`  Ratio: for every 1 token spent, memory saved ~${ratio.toFixed(2)} tokens of context.`));
+                console.log(chalk.bold('\nMemory'));
+                console.log(`  Briefing tokens injected: ${chalk.gray(metrics.briefingTokensInjected.toLocaleString())}  ${chalk.gray(`(${metrics.recallRecordsConsulted} records consulted — already included in parent ↑)`)}`);
+                console.log(`  Child output offloaded:   ${chalk.gray(metrics.offloadCharsAvoided.toLocaleString())} chars  ${chalk.gray(`(≈${offloadSavedTokens.toLocaleString()} parent tokens not spent)`)}`);
+                if (offloadSavedTokens > 0 && totalSpent > 0) {
+                    const ratio = offloadSavedTokens / totalSpent;
+                    const display = ratio >= 0.01 ? ratio.toFixed(2) : '<0.01';
+                    console.log(chalk.gray(`  Offload ratio: ~${display} saved per token spent.`));
                 }
-                console.log(chalk.gray('\n  (Estimates use a 5× multiplier on briefing tokens — a heuristic for "you would have needed to re-derive this from files/prompts otherwise". Treat as directional, not exact.)\n'));
+                console.log(chalk.gray('\n  (Offload is measured; briefing tokens are an information-gain stat, not a savings number.)\n'));
                 return true;
             }
         case '/feedback':

package/dist/cli/commands/orchestration.js

@@ -5,6 +5,7 @@
 import chalk from 'chalk';
 import { childSessionKey } from '../../runtime/mcpUtils.js';
 import { listRoles } from '../../orchestration/roles.js';
+import { listAll as listAgentDefs } from '../../orchestration/agentRegistry.js';
 import { formatSessionSummary, getSession, listSessions, reconcileStale } from '../../orchestration/orchestrator.js';
 import { readPreferences, writePreferences } from '../../state/preferencesStore.js';
 import { readTranscriptEntries } from '../../state/sessionStore.js';
@@ -26,6 +27,23 @@ export async function tryHandleOrchestrationCommand(ctx) {
             }
         case '/agents':
             {
+                if (args[0] === 'defs') {
+                    const defs = listAgentDefs(agent.workspaceRoot);
+                    console.log(chalk.bold('\nAgent Definitions:'));
+                    const ID_W = Math.max(...defs.map((l) => l.def.id.length), 4) + 2;
+                    const TIER_W = 12;
+                    const SRC_W = 10;
+                    console.log(chalk.gray(`  ${'ID'.padEnd(ID_W)}${'TIER'.padEnd(TIER_W)}${'SOURCE'.padEnd(SRC_W)}PATH`));
+                    for (const loaded of defs) {
+                        const idStr = chalk.cyan(loaded.def.id.padEnd(ID_W));
+                        const tierColor = loaded.def.tier === 'reasoning' ? chalk.blue : chalk.yellow;
+                        const tierStr = tierColor(loaded.def.tier.padEnd(TIER_W));
+                        const srcStr = chalk.gray(loaded.source.padEnd(SRC_W));
+                        console.log(`  ${idStr}${tierStr}${srcStr}${chalk.gray(loaded.filePath)}`);
+                    }
+                    console.log();
+                    return true;
+                }
                 reconcileStale(agent.workspaceRoot);
                 const sessions = listSessions(agent.workspaceRoot);
                 // `--json` for scripting. Emits a single JSON line on stdout so

package/dist/cli/commands/session.js

@@ -4,7 +4,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import chalk from 'chalk';
-import ora from 'ora';
+import { spinner as makeSpinner } from '../spinner.js';
 import { marked } from 'marked';
 import { listTranscripts, loadTranscript } from '../../state/sessionStore.js';
 import { readGoal, resumeGoal } from '../../state/goalStore.js';
@@ -51,6 +51,11 @@ export async function tryHandleSessionCommand(ctx) {
                     return true;
                 }
                 agent.sessionKey = sessionKey;
+                // The persisted transcript doesn't record per-call token usage, so
+                // we can't reconstruct counters for the resumed session — start
+                // counting from this point forward instead of carrying over the
+                // pre-resume parent counts (which were for a different session).
+                agent.resetSessionCounters();
                 const loaded = agent.loadHistory(entries);
                 console.log(chalk.green(`\n✓ Resumed session ${chalk.cyan(sessionKey)} with ${loaded} prior messages.`));
                 // If the resumed session has a goal that was suspended (paused,
@@ -73,9 +78,12 @@ export async function tryHandleSessionCommand(ctx) {
                         // before/after. Just unpause and kick off the next iteration.
                         const reactivated = resumeGoal(agent.workspaceRoot, sessionKey);
                         if (reactivated) {
-                            // Same rationale as /goal resume — drop any stale wrap-up
-                            // steering left over from the budget-trigger that paused us.
-                            agent.removeTaggedSystemMessage('goal-budget-steering');
+                            // 9d: pre-9d this branch had to drop a `goal-budget-steering`
+                            // tagged system message left over from a budget-trigger pause.
+                            // That message no longer exists — the wrap-up directive is
+                            // folded into the goal-anchor and the anchor is re-rendered
+                            // by the next runTurn. `refreshSystemPrompt` is still useful
+                            // here to rebuild any overlays that depend on the active goal.
                             agent.refreshSystemPrompt();
                             console.log(chalk.green(`\n▶  Goal resumed (${reactivated.budget.iterationsUsed}/${reactivated.budget.maxIterations} used). Starting next iteration…\n`));
                             ctx.repl.runAgentTurn(buildGoalKickoffPrompt(reactivated, 'resume'));
@@ -123,7 +131,7 @@ export async function tryHandleSessionCommand(ctx) {
             }
         case '/compact':
             {
-                const spinner = ora(chalk.gray('Summarizing conversation for compaction...')).start();
+                const spinner = makeSpinner(chalk.gray('Summarizing conversation for compaction...')).start();
                 try {
                     const result = await agent.compactHistory();
                     if (!result) {