@kinqs/brainrouter-cli 0.3.5 → 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/dist/state/goalStore.d.ts

@@ -24,12 +24,20 @@
  *                      "you ran out of room" from "user paused" from
  *                      "agent gave up."
  *
- * Storage (per-session bucket):
- *   ~/.brainrouter/workspaces/<encoded>/cli/sessions/<encodedKey>/goal.json
+ * Storage (priority chain — see `resolveGoalScope`):
+ *   1. Workflow bound: `<workspace>/.brainrouter/workflows/<slug>/goal.json`
+ *      (lives in the committable workflow folder so the goal travels with
+ *      the spec / tasks / walkthrough).
+ *   2. No workflow, session-scoped:
+ *      `~/.brainrouter/workspaces/<encoded>/cli/sessions/<encodedKey>/goal.json`
+ *   3. Back-compat (no workflow, no sessionKey):
+ *      `~/.brainrouter/workspaces/<encoded>/cli/goal.json`
  *
- * Legacy fallback paths exist for sessions created before per-session
- * goal isolation was added. normalize() fills missing fields with defaults
- * so resumed sessions don't crash on first read.
+ * Session-scoped reads stay isolated (Item 1 invariant — never fall back to
+ * a prior session's goal). Workflow-bound reads stay isolated by workflow
+ * (Item 3 invariant — switching workflows swaps which goal you see).
+ * normalize() fills missing fields with defaults so resumed sessions don't
+ * crash on first read.
  */
 export type GoalStatus = 'active' | 'paused' | 'complete' | 'blocked' | 'usage_limited';
 /** A pausing status is one where continuation is halted but resumable. */
@@ -57,7 +65,25 @@ export interface Goal {
     completedAt?: string;
     blockedReason?: string;
 }
-export declare const DEFAULT_GOAL_BUDGET = 10;
+/**
+ * Default iteration cap when the user doesn't pass one.
+ *
+ * Set to a very high number (effectively "unlimited" for any real task)
+ * rather than a tight 10. Rationale: the goal lifecycle has three
+ * independent safety nets that already prevent runaway loops —
+ *   1. Anti-spin   — a turn that made zero tool calls doesn't continue
+ *   2. Repeat-loop — calling the same tool with identical args 3× errors
+ *   3. Manual stop — Ctrl-C, /goal pause, /goal clear
+ *
+ * A hard iteration cap on top of those is overly paternalistic for users
+ * running local models (no $ cost) and is easily lifted with /goal budget
+ * <n> when wanted. Display layers should treat any value >= UNLIMITED_THRESHOLD
+ * as "unlimited" for friendlier UX.
+ */
+export declare const DEFAULT_GOAL_BUDGET = 1000000;
+export declare const UNLIMITED_BUDGET_THRESHOLD = 100000;
+/** Format helper — used by REPL display + status output. */
+export declare function formatBudget(maxIterations: number): string;
 /**
  * Hard cap on the goal text length. A goal is supposed to be a 1–3 sentence
  * outcome statement; multi-thousand-character pastes (e.g. full chat logs)
@@ -82,6 +108,55 @@ export declare class GoalConflictError extends Error {
     readonly existing: Goal;
     constructor(existing: Goal);
 }
+/**
+ * Where the agent's goal lives RIGHT NOW. The priority chain — adapted from
+ * openSrc/agentmemory's fallback-provider walk (guard clauses that early-
+ * return per layer rather than a single flat loop) — is:
+ *
+ *   1. workflow scope — a workflow is bound via `current-workflow.json`
+ *      (the per-user CLI pointer). Goal lives at `<workflow>/goal.json`
+ *      next to spec.md / tasks.md / meta.json. Switching workflows carries
+ *      the goal with the folder.
+ *   2. session scope — no workflow bound but a sessionKey is supplied
+ *      (the post-Item-1 default). Goal lives at
+ *      `<cliStateDir>/sessions/<encodedKey>/goal.json` — strictly per
+ *      session, never falls back to a different session's file.
+ *   3. legacy scope — no workflow, no sessionKey. Used by the very-old
+ *      single-process call sites that haven't been migrated yet (and by
+ *      back-compat reads of pre-0.3.5 workspace-level goal.json files).
+ *
+ * Every read/write entrypoint routes through this single resolver so the
+ * priority chain has exactly one decision point. Callers don't decide where
+ * to look; they get a path + scope tag and act on it.
+ */
+export type GoalScope = {
+    scope: 'session';
+    sessionKey: string;
+    path: string;
+} | {
+    scope: 'legacy';
+    path: string;
+};
+/**
+ * Resolve the on-disk location where the active goal for this CLI process
+ * lives.
+ *
+ * **Design (0.3.6 decouple-goal-from-workflow, supersedes Item 3):** goal
+ * is **always per-session**. Workflows are durable artifact folders
+ * (spec.md, tasks.md, walkthrough.md, meta.json) that have nothing to do
+ * with the agent's autonomy primitive. The earlier Item 3 design coupled
+ * the two by storing goal state inside `<workflow>/goal.json`, which
+ * meant any two CLI sessions in the same workspace that happened to land
+ * on the same workflow shared a goal — silently reintroducing the
+ * cross-session leak PR #26 had fixed. We removed that coupling
+ * entirely: workflows are storage, goals are runtime, no overlap.
+ *
+ * Priority chain:
+ *   1. Session-scoped — `<session>/goal.json`. The normal case.
+ *   2. Legacy — `<cli-state>/goal.json`. Only hit by callers without a
+ *      sessionKey (rare; mostly tooling paths that pre-date Item 1).
+ */
+export declare function resolveGoalScope(workspaceRoot: string, sessionKey?: string): GoalScope;
 export declare function readGoal(workspaceRoot: string, sessionKey?: string): Goal | null;
 /**
  * Set a new active goal. Refuses to overwrite an in-progress goal (active,
@@ -158,17 +233,23 @@ export declare function goalHasBudgetLeft(goal: Goal): boolean;
  * decision. We detect that ahead of time by checking before the tick.
  */
 export declare function goalIsOnFinalBudgetTurn(goal: Goal): boolean;
+export interface FormatGoalBlockOptions {
+    /**
+     * Override the auto-detected final-budget-turn state. Useful for tests
+     * and for callers that want to force-render the wrap-up directive. When
+     * omitted, `formatGoalBlock` calls `goalIsOnFinalBudgetTurn(goal)` itself.
+     */
+    finalBudgetTurn?: boolean;
+}
+export declare function formatGoalBlock(goal: Goal, options?: FormatGoalBlockOptions): string;
 /**
- * Wrap-up steering message injected on the final-budget turn. The agent
- * loop pushes this into the chat history as a system message so the model
- * pivots from "continue investigating" to "consolidate and report." Plain
- * directive, no role-play.
+ * Drift / ready check used by the goal-continuation prompt. Compressed
+ * from the prose-heavy 4-paragraph form into a 2-line checklist as part
+ * of 9d's prompt deduplication — the goal text, status, and budget are
+ * now owned by the goal-anchor system message; the continuation prompt
+ * carries only the per-turn drift check + a pointer to the anchor.
  *
- * The message specifically reports WHICH cap is tight (iterations, tokens,
- * or both) so the model doesn't get told "one turn left" when it actually
- * has many iterations remaining but is near the token cap, or vice versa.
- * Earlier versions hardcoded the iteration framing even when only the
- * token heuristic tripped, which misled the model on token-budgeted runs.
+ * Distinct from `buildGoalKickoffPrompt` (in `commands/_helpers.ts`),
+ * which is the FIRST-turn prompt fired by `/goal <text>` and `/goal resume`.
  */
-export declare function buildBudgetSteeringMessage(goal: Goal): string;
-export declare function formatGoalBlock(goal: Goal): string;
+export declare function buildGoalContinuationPrompt(goal: Goal, lastPrompt: string, lastAnswer: string): string;