@kinqs/brainrouter-cli 0.3.6 → 0.3.8

package/dist/runtime/mcpPool.js

@@ -0,0 +1,442 @@
+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;
+    });
+}
+/**
+ * 0.3.8-R5 — Single-underscore `mcp_<server>_<tool>` is the canonical
+ * tool-name shape across the CLI. Any legacy double-underscore
+ * `mcp__<server>__<tool>` form that arrives at the pool boundary
+ * (e.g. through an external surface or older skill) is collapsed here
+ * so downstream code can assume one convention.
+ */
+export function normalizeMcpToolName(name) {
+    if (!name.startsWith('mcp__'))
+        return name;
+    const rest = name.slice('mcp__'.length);
+    const sep = rest.indexOf('__');
+    if (sep < 0)
+        return name;
+    return `mcp_${rest.slice(0, sep)}_${rest.slice(sep + 2)}`;
+}
+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) {
+        // Back-compat: any legacy double-underscore form is collapsed first so
+        // the rest of the resolver only deals with the canonical shape.
+        name = normalizeMcpToolName(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,10 +29,24 @@ 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
  * to UUIDs or namespacing per-role) is a one-file edit, not a sweep.
  */
 export declare function childSessionKey(parentSessionKey: string, childId: string): string;
+/**
+ * Discovery helper for `Set<string>` tool-name lookups across MCP prefix
+ * conventions. The pool normalises tool names to single-underscore
+ * `mcp_<server>_<tool>` at the boundary (0.3.8-R5), so a discovery check
+ * for "is `memory_recall` exposed?" must match either the bare name (raw
+ * single-server flow) or any `mcp_<server>_memory_recall` (post-pool
+ * normalisation).
+ *
+ * Use this anywhere a caller previously did `toolNames.has('memory_recall')` —
+ * those bare-name checks silently miss prefixed names and were the root
+ * cause of `🧠 Briefing: 0 records from (none)` even with the brain MCP
+ * connected.
+ */
+export declare function hasMcpTool(toolNames: Set<string>, bareName: string): boolean;

package/dist/runtime/mcpUtils.js

@@ -62,3 +62,26 @@ export async function callMcpTool(client, name, args) {
 export function childSessionKey(parentSessionKey, childId) {
     return `${parentSessionKey}:child:${childId}`;
 }
+/**
+ * Discovery helper for `Set<string>` tool-name lookups across MCP prefix
+ * conventions. The pool normalises tool names to single-underscore
+ * `mcp_<server>_<tool>` at the boundary (0.3.8-R5), so a discovery check
+ * for "is `memory_recall` exposed?" must match either the bare name (raw
+ * single-server flow) or any `mcp_<server>_memory_recall` (post-pool
+ * normalisation).
+ *
+ * Use this anywhere a caller previously did `toolNames.has('memory_recall')` —
+ * those bare-name checks silently miss prefixed names and were the root
+ * cause of `🧠 Briefing: 0 records from (none)` even with the brain MCP
+ * connected.
+ */
+export function hasMcpTool(toolNames, bareName) {
+    if (toolNames.has(bareName))
+        return true;
+    const suffix = `_${bareName}`;
+    for (const name of toolNames) {
+        if (name.startsWith('mcp_') && name.endsWith(suffix))
+            return true;
+    }
+    return false;
+}

package/dist/runtime/scheduleTicker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-process ticker that fires due `/schedule` jobs.
+ *
+ * Singleton per CLI process. Wakes every 30s (override via
+ * `BRAINROUTER_SCHEDULE_TICK_MS`), reloads the persisted store, fires
+ * any jobs whose `nextRun` is now in the past, then advances `nextRun`
+ * past `now()` so a missed window only fires ONCE (catch-up
+ * idempotency).
+ *
+ * No daemon — the ticker dies with the REPL. Schedules that miss
+ * because the CLI was closed are caught on the next REPL boot via the
+ * same "advance past now" rule.
+ */
+import { type ScheduleRecord } from '../state/scheduleStore.js';
+export interface ScheduleTickerOptions {
+    workspaceRoot: string;
+    sessionKey: string;
+    /** Called when a schedule is due. Fire-and-forget. */
+    fire: (command: string, schedule: ScheduleRecord) => void;
+    /** Override the wake interval. Defaults to env or 30 000 ms. */
+    intervalMs?: number;
+    /** Injected clock for tests. */
+    now?: () => number;
+    /** Called when a fire is skipped because the expression is unparseable. */
+    onError?: (msg: string) => void;
+}
+export interface ScheduleTickerHandle {
+    stop: () => void;
+    /** Force one immediate scan (tests + boot catch-up). */
+    tickNow: () => void;
+}
+export declare function isScheduleTickerRunning(): boolean;
+export declare function startScheduleTicker(opts: ScheduleTickerOptions): ScheduleTickerHandle;

package/dist/runtime/scheduleTicker.js

@@ -0,0 +1,99 @@
+/**
+ * In-process ticker that fires due `/schedule` jobs.
+ *
+ * Singleton per CLI process. Wakes every 30s (override via
+ * `BRAINROUTER_SCHEDULE_TICK_MS`), reloads the persisted store, fires
+ * any jobs whose `nextRun` is now in the past, then advances `nextRun`
+ * past `now()` so a missed window only fires ONCE (catch-up
+ * idempotency).
+ *
+ * No daemon — the ticker dies with the REPL. Schedules that miss
+ * because the CLI was closed are caught on the next REPL boot via the
+ * same "advance past now" rule.
+ */
+import { loadSchedules, recordFire, removeSchedule, setScheduleEnabled } from '../state/scheduleStore.js';
+import { parseCron, nextCronFire } from './cronParser.js';
+const DEFAULT_INTERVAL_MS = 30_000;
+const MIN_INTERVAL_MS = 100;
+let active = null;
+export function isScheduleTickerRunning() {
+    return active !== null;
+}
+export function startScheduleTicker(opts) {
+    if (active)
+        return active;
+    const envOverride = Number(process.env.BRAINROUTER_SCHEDULE_TICK_MS);
+    const rawInterval = opts.intervalMs ?? (Number.isFinite(envOverride) && envOverride > 0 ? envOverride : DEFAULT_INTERVAL_MS);
+    const interval = Math.max(MIN_INTERVAL_MS, rawInterval);
+    const now = opts.now ?? (() => Date.now());
+    let stopped = false;
+    let timer = null;
+    const scan = () => {
+        if (stopped)
+            return;
+        const t = now();
+        let schedules;
+        try {
+            schedules = loadSchedules(opts.workspaceRoot);
+        }
+        catch (err) {
+            opts.onError?.(`load failed: ${err.message}`);
+            return;
+        }
+        for (const s of schedules) {
+            if (!s.enabled)
+                continue;
+            if (s.owner !== opts.sessionKey)
+                continue;
+            const nextMs = Date.parse(s.nextRun);
+            if (!Number.isFinite(nextMs) || nextMs > t)
+                continue;
+            try {
+                opts.fire(s.command, s);
+            }
+            catch (err) {
+                opts.onError?.(`fire failed for ${s.id}: ${err.message}`);
+            }
+            if (s.kind === 'once') {
+                removeSchedule(opts.workspaceRoot, s.id);
+                continue;
+            }
+            // Cron: advance nextRun strictly past `t`. parseCron should always
+            // succeed (we validated on add), but tolerate corruption by
+            // disabling rather than spinning forever on a past nextRun.
+            const cron = parseCron(s.expr);
+            if (!cron) {
+                opts.onError?.(`cron expression invalid; disabling ${s.id}: ${s.expr}`);
+                try {
+                    setScheduleEnabled(opts.workspaceRoot, s.id, false);
+                }
+                catch { /* swallow */ }
+                continue;
+            }
+            const next = nextCronFire(cron, new Date(t));
+            recordFire(opts.workspaceRoot, s.id, new Date(t), next.toISOString());
+        }
+    };
+    const tick = () => {
+        if (stopped)
+            return;
+        scan();
+        if (stopped)
+            return;
+        timer = setTimeout(tick, interval);
+    };
+    // Defer the first scan to the next macrotask so the caller finishes
+    // wiring (e.g. Ink's `onReady`) before any fire callback runs.
+    timer = setTimeout(tick, 0);
+    active = {
+        stop: () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            active = null;
+        },
+        tickNow: scan,
+    };
+    return active;
+}

package/dist/runtime/vendorSnippets.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-vendor MCP install snippets (0.3.8-I5 / roadmap §9).
+ *
+ * Pattern adapted from semble's per-agent install docs
+ * (openSrc/semble/src/semble/agents/*.md) — one focused entry per vendor
+ * with the exact JSON shape and config file path. Where semble ships
+ * markdown, we ship structured templates so the CLI can substitute the
+ * user's live profile URL + API key on the fly.
+ *
+ * Notes
+ * - Tool name examples use the single-underscore convention
+ *   `mcp_<server>_<tool>` (0.3.8-R5 decision).
+ * - Each template is pinned to a "verified against vendor docs as of …"
+ *   comment. Vendor MCP schemas drift; bump the date when you re-verify.
+ * - We never auto-write the vendor config file. Print only — direct-write
+ *   is a future enhancement (roadmap: future item; do not file a follow-up).
+ */
+export type VendorSchema = 'stdio' | 'http' | 'sse';
+export interface VendorVars {
+    /** Active BrainRouter profile URL (http transport). */
+    url: string;
+    /** Active BrainRouter profile API key — rendered verbatim into the snippet. */
+    apiKey: string;
+    /** Server id the user picks in their vendor config (defaults to "brainrouter"). */
+    serverId?: string;
+}
+export interface VendorEntry {
+    id: string;
+    label: string;
+    schema: VendorSchema;
+    /** Restart note shown after the snippet. */
+    restart: string;
+    /** Per-OS config file path. POSIX path with `~` for the user's home. */
+    configPath: (platform: NodeJS.Platform) => string;
+    /** Pure template — returns the JSON object the user should merge into their vendor config. */
+    template: (vars: VendorVars) => unknown;
+    /** Free-form note (e.g. nested-key location, alternative shape). */
+    note?: string;
+}
+/** Render a config path for human display — backslashes on Windows. */
+export declare function displayPath(p: string, platform?: NodeJS.Platform): string;
+export declare const VENDORS: Record<string, VendorEntry>;
+export declare function listVendors(): VendorEntry[];
+export declare function getVendor(id: string): VendorEntry | undefined;
+export declare function renderSnippet(entry: VendorEntry, vars: VendorVars): string;