@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/harness/mcp-config-formats.js

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — MCP config writers for non-JSON formats.
+//
+// Codex stores MCP servers in TOML (~/.codex/config.toml, `[mcp_servers.<name>]`)
+// and Goose in YAML (~/.config/goose/config.yaml, `extensions:` with `cmd`/`args`).
+// routeThroughProxy handles the universal JSON shape; these are the two
+// format-specific writers that reroute stdio servers through `bivy mcp-proxy` in
+// TOML/YAML, so Codex and Goose join MCP governance too.
+//
+// These are deliberately focused, line-oriented transforms for the common
+// single-line `command`/`args` (TOML) and `cmd`/`args: [..]` (YAML) shapes — not
+// full TOML/YAML parsers. Anything they don't recognize is left untouched
+// (rewritten: []), which is safe: injection is opt-in and the caller restores the
+// exact original bytes on session end regardless. Pure string→string, unit-tested
+// in test/harness-mcp-formats.test.ts.
+import { PROXY_MARKER } from "./mcp-config.js";
+function proxyArgs(launcher, server, command, origArgs) {
+    return [...(launcher.argsPrefix ?? []), PROXY_MARKER, "--server", server, "--", command, ...origArgs];
+}
+function tomlStringArray(values) {
+    return `[${values.map((v) => JSON.stringify(v)).join(", ")}]`;
+}
+/** Parse a TOML inline string array `["a", "b"]` (best-effort) into JS strings. */
+function parseTomlArray(literal) {
+    const inner = literal.trim().replace(/^\[/, "").replace(/\]$/, "");
+    if (!inner.trim())
+        return [];
+    const out = [];
+    const re = /"((?:[^"\\]|\\.)*)"|'([^']*)'/g;
+    let m;
+    while ((m = re.exec(inner)))
+        out.push(m[1] !== undefined ? JSON.parse(`"${m[1]}"`) : (m[2] ?? ""));
+    return out;
+}
+/**
+ * Rewrite `[mcp_servers.<name>]` TOML tables so each stdio server launches
+ * through the proxy. Handles single-line `command = "…"` and `args = [ … ]`.
+ */
+export function injectTomlMcp(content, launcher) {
+    const lines = content.split("\n");
+    const rewritten = [];
+    // First pass: find each [mcp_servers.NAME] section's line range + command/args.
+    let i = 0;
+    const proxyCmd = launcher.command;
+    while (i < lines.length) {
+        const header = /^\s*\[mcp_servers\.([A-Za-z0-9_.-]+)\]\s*$/.exec(lines[i]);
+        if (!header) {
+            i++;
+            continue;
+        }
+        const name = header[1];
+        let end = i + 1;
+        while (end < lines.length && !/^\s*\[/.test(lines[end]))
+            end++;
+        // Locate command/args lines in [i+1, end).
+        let cmdIdx = -1;
+        let argsIdx = -1;
+        for (let j = i + 1; j < end; j++) {
+            if (cmdIdx < 0 && /^\s*command\s*=/.test(lines[j]))
+                cmdIdx = j;
+            if (argsIdx < 0 && /^\s*args\s*=\s*\[/.test(lines[j]))
+                argsIdx = j;
+        }
+        if (cmdIdx >= 0) {
+            const cmdVal = /=\s*"((?:[^"\\]|\\.)*)"/.exec(lines[cmdIdx]) || /=\s*'([^']*)'/.exec(lines[cmdIdx]);
+            const command = cmdVal ? (cmdVal[1] ?? "") : "";
+            if (command && command !== proxyCmd) {
+                const origArgs = argsIdx >= 0 ? parseTomlArray(lines[argsIdx].slice(lines[argsIdx].indexOf("["))) : [];
+                lines[cmdIdx] = lines[cmdIdx].replace(/=\s*("(?:[^"\\]|\\.)*"|'[^']*')/, `= ${JSON.stringify(proxyCmd)}`);
+                const newArgsLine = `args = ${tomlStringArray(proxyArgs(launcher, name, command, origArgs))}`;
+                if (argsIdx >= 0)
+                    lines[argsIdx] = lines[argsIdx].replace(/args\s*=\s*\[.*\]/, newArgsLine);
+                else
+                    lines.splice(cmdIdx + 1, 0, newArgsLine);
+                rewritten.push(name);
+            }
+        }
+        i = end;
+    }
+    return { content: lines.join("\n"), rewritten };
+}
+/** Parse a YAML inline flow array `[a, "b"]` into JS strings (best-effort). */
+function parseYamlFlowArray(literal) {
+    const inner = literal.trim().replace(/^\[/, "").replace(/\]$/, "");
+    if (!inner.trim())
+        return [];
+    return inner.split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter((s) => s.length > 0);
+}
+function yamlFlowArray(values) {
+    return `[${values.map((v) => JSON.stringify(v)).join(", ")}]`;
+}
+/**
+ * Rewrite Goose `extensions:` YAML so each stdio extension launches through the
+ * proxy. Handles the common shape with `cmd:` and an inline `args: [ … ]` at a
+ * deeper indent than the extension name. Block-sequence args (`- item` lines) are
+ * left untouched (safe no-op) rather than risk a malformed rewrite.
+ */
+export function injectYamlMcp(content, launcher) {
+    const lines = content.split("\n");
+    const rewritten = [];
+    let inExtensions = false;
+    let extName = null;
+    let extIndent = -1;
+    let cmdIdx = -1;
+    let cmdValue = "";
+    let argsIdx = -1;
+    const flush = () => {
+        if (extName && cmdIdx >= 0 && cmdValue && cmdValue !== launcher.command) {
+            const origArgs = argsIdx >= 0 ? parseYamlFlowArray(lines[argsIdx].slice(lines[argsIdx].indexOf("["))) : [];
+            const indent = lines[cmdIdx].slice(0, lines[cmdIdx].length - lines[cmdIdx].trimStart().length);
+            lines[cmdIdx] = `${indent}cmd: ${JSON.stringify(launcher.command)}`;
+            const newArgs = `${indent}args: ${yamlFlowArray(proxyArgs(launcher, extName, cmdValue, origArgs))}`;
+            if (argsIdx >= 0)
+                lines[argsIdx] = newArgs;
+            else
+                lines.splice(cmdIdx + 1, 0, newArgs);
+            rewritten.push(extName);
+        }
+        extName = null;
+        cmdIdx = -1;
+        cmdValue = "";
+        argsIdx = -1;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*extensions\s*:/.test(line)) {
+            inExtensions = true;
+            continue;
+        }
+        if (!inExtensions)
+            continue;
+        const indent = line.length - line.trimStart().length;
+        if (line.trim() && indent === 0) {
+            flush();
+            inExtensions = false;
+            continue;
+        }
+        // An extension name: `  <name>:` directly under extensions.
+        const nameMatch = /^(\s+)([A-Za-z0-9_.-]+)\s*:\s*$/.exec(line);
+        if (nameMatch && (extIndent < 0 || nameMatch[1].length <= extIndent || extName === null)) {
+            // New extension block starts.
+            flush();
+            extName = nameMatch[2];
+            extIndent = nameMatch[1].length;
+            continue;
+        }
+        if (extName) {
+            const cmd = /^\s+cmd\s*:\s*(.+)$/.exec(line);
+            if (cmd) {
+                cmdIdx = i;
+                cmdValue = cmd[1].trim().replace(/^["']|["']$/g, "");
+                continue;
+            }
+            const args = /^\s+args\s*:\s*(\[.*\])\s*$/.exec(line);
+            if (args) {
+                argsIdx = i;
+                continue;
+            }
+        }
+    }
+    flush();
+    return { content: lines.join("\n"), rewritten };
+}

package/dist/harness/mcp-config.js

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — MCP config rewriting.
+//
+// The one piece of MCP governance that is unavoidably per-agent is *where* the
+// config lives — but the shape is near-universal. Claude Code, Codex, Cursor,
+// Windsurf, and most MCP hosts use the same `{ mcpServers: { name: { command,
+// args, env } } }` object (stdio servers) plus optional remote (url) servers.
+// This module rewrites that object so every stdio server launches through the
+// Bivy MCP proxy instead of directly — turning each agent's own MCP config into
+// the injection point, with no agent-specific code beyond the file location.
+//
+// Pure functions, no I/O — unit-tested in test/harness-mcp-config.test.ts. The
+// file-location table for each agent is data (see agentMcpConfigTargets) that
+// the fs inject/restore step (mcp-inject.ts) reads/writes; the transform itself
+// is shared.
+import nodePath from "node:path";
+/** Marker arg the proxy CLI recognizes, so a config can be detected as already routed. */
+export const PROXY_MARKER = "--bivy-mcp";
+/** True when a server spec already launches through the Bivy proxy. */
+export function isProxied(spec, launcher) {
+    if (spec.command !== launcher.command)
+        return false;
+    return Array.isArray(spec.args) && spec.args.includes(PROXY_MARKER);
+}
+/**
+ * Rewrite every stdio server in `config.mcpServers` to launch through the proxy:
+ *
+ *   original:  { command: "mcp-fs", args: ["--root", "/w"], env: {...} }
+ *   rewritten: { command: "bivy",
+ *                args: ["mcp-proxy", "--bivy-mcp", "--server", "<name>", "--",
+ *                       "mcp-fs", "--root", "/w"],
+ *                env: {...} }
+ *
+ * Remote (url) servers are left untouched and reported in `skipped`. Idempotent:
+ * an already-proxied server is left as-is (also reported in `skipped`).
+ */
+export function routeThroughProxy(config, launcher) {
+    const rewritten = [];
+    const skipped = [];
+    const servers = config.mcpServers ?? {};
+    const nextServers = {};
+    for (const [name, spec] of Object.entries(servers)) {
+        if (!spec || typeof spec !== "object") {
+            nextServers[name] = spec;
+            skipped.push(name);
+            continue;
+        }
+        if (typeof spec.command !== "string" || !spec.command) {
+            // Remote/url server (or malformed) — the stdio proxy can't wrap it yet.
+            nextServers[name] = spec;
+            skipped.push(name);
+            continue;
+        }
+        if (isProxied(spec, launcher)) {
+            nextServers[name] = spec;
+            skipped.push(name);
+            continue;
+        }
+        const prefix = launcher.argsPrefix ?? [];
+        nextServers[name] = {
+            ...spec,
+            command: launcher.command,
+            args: [...prefix, PROXY_MARKER, "--server", name, "--", spec.command, ...(spec.args ?? [])],
+        };
+        rewritten.push(name);
+    }
+    return {
+        config: { ...config, mcpServers: nextServers },
+        rewritten,
+        skipped,
+    };
+}
+/**
+ * Recover the original server command/args from a proxied spec's args — the
+ * inverse of routeThroughProxy, used by the proxy CLI to know what to spawn.
+ * Returns null if the args don't carry a `-- <command> ...` tail.
+ */
+export function parseProxiedArgs(args) {
+    const sep = args.indexOf("--");
+    if (sep < 0 || sep + 1 >= args.length)
+        return null;
+    const serverFlag = args.indexOf("--server");
+    const server = serverFlag >= 0 && serverFlag + 1 < sep ? args[serverFlag + 1] : undefined;
+    const tail = args.slice(sep + 1);
+    return { server, command: tail[0], args: tail.slice(1) };
+}
+/** JSON MCP-config file candidates for an agent, most-specific (safest) first. */
+export function agentMcpConfigTargets(agentId, ctx) {
+    const ws = (...parts) => nodePath.join(ctx.workspace, ...parts);
+    const home = (...parts) => nodePath.join(ctx.home, ...parts);
+    switch (agentId) {
+        case "claude":
+        case "claude-code":
+        case "claude-code-sdk":
+            return [ws(".mcp.json")];
+        case "gemini":
+            return [ws(".gemini", "settings.json"), home(".gemini", "settings.json")];
+        case "opencode":
+            return [ws("opencode.json"), ws(".opencode.json")];
+        case "codex":
+            // Codex stores MCP servers in TOML.
+            return [home(".codex", "config.toml")];
+        case "goose":
+            // Goose stores MCP "extensions" in YAML.
+            return [home(".config", "goose", "config.yaml")];
+        default:
+            // A generic project-local MCP config many hosts honor.
+            return [ws(".mcp.json")];
+    }
+}

package/dist/harness/mcp-inject.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — MCP config auto-injection (fs side).
+//
+// Phase 2b: at session start, rewrite the agent's on-disk JSON MCP config so its
+// stdio servers launch through `bivy mcp-proxy` (routeThroughProxy), and hand
+// back a restore() that puts the file back exactly as it was on session end.
+// Opt-in via BIVY_MCP_PROXY so it never surprises a user. Best-effort and
+// session-scoped (workspace-local files preferred) so a failure or a concurrent
+// session can't corrupt config: we snapshot the exact bytes and restore them.
+//
+// Only JSON configs are handled (Claude, Gemini, OpenCode, generic .mcp.json).
+// TOML/YAML-config agents are skipped — they still run and are governed by the
+// FS + network channels. Unit-tested in test/harness-mcp-inject.test.ts.
+import fs from "node:fs";
+import path from "node:path";
+import { agentMcpConfigTargets, routeThroughProxy, } from "./mcp-config.js";
+import { injectTomlMcp, injectYamlMcp } from "./mcp-config-formats.js";
+/** The proxy launcher Bivy injects — `bivy mcp-proxy …`. */
+export function bivyProxyLauncher(bivyCommand = "bivy") {
+    return { command: bivyCommand, argsPrefix: ["mcp-proxy"] };
+}
+/**
+ * Inject the proxy into a single JSON config file. Returns a restore thunk
+ * (a no-op if the file was absent, unreadable, non-JSON, or had no stdio
+ * servers to route). Never throws.
+ */
+export function injectJsonMcpConfig(filePath, launcher) {
+    let original;
+    try {
+        original = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return { injected: false, restore: () => { } };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(original);
+    }
+    catch {
+        return { injected: false, restore: () => { } };
+    }
+    const result = routeThroughProxy(parsed, launcher);
+    if (result.rewritten.length === 0)
+        return { injected: false, restore: () => { } };
+    // Preserve the file's indentation feel by re-serializing with 2 spaces; the
+    // restore path writes back the exact original bytes regardless.
+    try {
+        fs.writeFileSync(filePath, `${JSON.stringify(result.config, null, 2)}\n`);
+    }
+    catch {
+        return { injected: false, restore: () => { } };
+    }
+    return {
+        injected: true,
+        restore: () => {
+            try {
+                fs.writeFileSync(filePath, original);
+            }
+            catch {
+                // Restore is best-effort; the original bytes are all we can offer.
+            }
+        },
+    };
+}
+/**
+ * Inject the proxy into a single MCP config file, dispatching on extension:
+ * .json (universal), .toml (Codex), .yaml/.yml (Goose). Reads → transforms →
+ * writes, returning an exact-bytes restore(). Never throws; no-op when the file
+ * is absent, unparseable, or has no stdio server to route.
+ */
+export function injectMcpConfigFile(filePath, launcher) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".json")
+        return injectJsonMcpConfig(filePath, launcher);
+    let original;
+    try {
+        original = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return { injected: false, restore: () => { } };
+    }
+    let out;
+    try {
+        if (ext === ".toml")
+            out = injectTomlMcp(original, launcher);
+        else if (ext === ".yaml" || ext === ".yml")
+            out = injectYamlMcp(original, launcher);
+        else
+            return { injected: false, restore: () => { } };
+    }
+    catch {
+        return { injected: false, restore: () => { } };
+    }
+    if (out.rewritten.length === 0)
+        return { injected: false, restore: () => { } };
+    try {
+        fs.writeFileSync(filePath, out.content);
+    }
+    catch {
+        return { injected: false, restore: () => { } };
+    }
+    return {
+        injected: true,
+        restore: () => {
+            try {
+                fs.writeFileSync(filePath, original);
+            }
+            catch { /* best-effort */ }
+        },
+    };
+}
+/**
+ * Inject the proxy into every MCP config an agent reads for this session.
+ * Returns the injected files and a single restore() covering all of them.
+ */
+export function injectMcpProxyForSession(agentId, ctx, launcher = bivyProxyLauncher()) {
+    const restores = [];
+    const injected = [];
+    for (const target of agentMcpConfigTargets(agentId, ctx)) {
+        const r = injectMcpConfigFile(target, launcher);
+        if (r.injected) {
+            injected.push(target);
+            restores.push(r.restore);
+        }
+    }
+    return {
+        injected,
+        restore: () => {
+            for (const r of restores)
+                r();
+        },
+    };
+}

package/dist/harness/mcp-proxy-cli.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — `bivy mcp-proxy` entry point.
+//
+// The agent launches its MCP servers through this (via routeThroughProxy config
+// rewriting): `bivy mcp-proxy --bivy-mcp --server <name> -- <real cmd> <args>`.
+// This process spawns the real server and mediates its JSON-RPC, asking the
+// local Bivy daemon to decide each `tools/call` — which runs the SAME guardian /
+// PolicyEngine / ApprovalCard path as native tool calls, so MCP tools are
+// governed identically for every agent.
+//
+// Fail-open by design: if the daemon is unreachable, the proxy must never break
+// the agent — it allows the call and logs to stderr. Governance is a safety net,
+// not a hard dependency that can wedge a user's agent when the node restarts.
+//
+// The HTTP decider is factored out and unit-tested (test/harness-mcp-cli.test.ts)
+// with an injected fetch; the process wiring itself is thin.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runMcpProxy } from "./mcp-proxy.js";
+import { parseProxiedArgs } from "./mcp-config.js";
+const DEFAULT_ENDPOINT = "http://127.0.0.1:4317";
+/**
+ * Build a decider that asks the daemon whether an MCP `tools/call` may run.
+ * Fail-open on any transport/HTTP error so a down node never wedges the agent.
+ */
+export function buildHttpDecider(endpoint, sessionId, server, fetchImpl) {
+    return async (tool, args) => {
+        try {
+            const r = await fetchImpl(`${endpoint}/api/mcp/decide`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ sessionId, server, tool, args }),
+            });
+            if (!r.ok)
+                return { allow: true };
+            const j = (await r.json());
+            return { allow: j.allow !== false, reason: typeof j.reason === "string" ? j.reason : undefined };
+        }
+        catch {
+            return { allow: true }; // fail-open
+        }
+    };
+}
+/** Best-effort event post (inventory / results). Never throws. */
+function reportEvent(endpoint, sessionId, event, fetchImpl) {
+    void fetchImpl(`${endpoint}/api/mcp/event`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ sessionId, event }),
+    }).catch(() => { });
+}
+/** Parse `bivy mcp-proxy` args and run the proxy. Returns the child exit code. */
+export async function runMcpProxyCli(argv, deps = {}) {
+    const parsed = parseProxiedArgs(argv);
+    if (!parsed || !parsed.command) {
+        process.stderr.write("bivy mcp-proxy: expected `--server <name> -- <command> [args…]`\n");
+        return 2;
+    }
+    const endpoint = deps.endpoint ?? process.env.BIVY_MCP_ENDPOINT ?? DEFAULT_ENDPOINT;
+    const sessionId = deps.sessionId ?? process.env.BIVY_MCP_SESSION ?? "";
+    const server = parsed.server ?? "mcp";
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    return await runMcpProxy({
+        command: parsed.command,
+        args: parsed.args,
+        server,
+        decide: buildHttpDecider(endpoint, sessionId, server, fetchImpl),
+        // The daemon already records the call via /api/mcp/decide; only forward the
+        // inventory and result events here to avoid double-counting.
+        onEvent: (event) => {
+            if (event.type !== "call")
+                reportEvent(endpoint, sessionId, event, fetchImpl);
+        },
+    });
+}
+// Run when invoked directly (via `bivy mcp-proxy …` → tsx this file).
+const invokedDirectly = (() => {
+    try {
+        return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    void runMcpProxyCli(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/dist/harness/mcp-proxy.js

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — MCP effect boundary (governing tool calls).
+//
+// Second pillar of "govern the substrate, not the agent". MCP (Model Context
+// Protocol) is a wire standard every serious agent now speaks — Claude Code,
+// Codex, Goose, Gemini, OpenCode — so instead of teaching Bivy each agent's
+// chat protocol, we sit in front of the agent's MCP servers and mediate the
+// JSON-RPC. Rewriting an agent's MCP config so each server launches as
+// `bivy mcp-proxy -- <real server cmd>` means EVERY MCP tool call flows through
+// Bivy for inventory, policy, and logging — with zero agent-specific code.
+//
+// MCP stdio transport is newline-delimited JSON-RPC 2.0 (one message per line).
+// The mediator below is transport-free and fully unit-testable: it takes decoded
+// messages and says whether to forward them or short-circuit a denied tool call
+// back to the agent. runMcpProxy() wraps it around a real child process's stdio.
+//
+// Unit-tested in test/harness-mcp-proxy.test.ts.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+/**
+ * Transport-free MCP JSON-RPC mediator. Feed it decoded messages in each
+ * direction; it enforces policy on `tools/call`, inventories `tools/list`
+ * results, and otherwise passes everything through untouched.
+ */
+export class McpMediator {
+    decide;
+    onEvent;
+    server;
+    /** Request ids we short-circuited (denied) — never expect a server reply for them. */
+    denied = new Set();
+    constructor(options) {
+        this.decide = options.decide;
+        this.onEvent = options.onEvent ?? (() => { });
+        this.server = options.server ?? "mcp";
+    }
+    /** Mediate one message coming from the agent (client) toward the server. */
+    async handleClientMessage(msg) {
+        if (msg.method !== "tools/call")
+            return { forward: msg };
+        const params = (msg.params ?? {});
+        const tool = typeof params.name === "string" ? params.name : "";
+        const args = params.arguments;
+        let decision;
+        try {
+            decision = await this.decide(tool, args);
+        }
+        catch {
+            // A failing policy check must fail safe (deny), not crash the proxy.
+            decision = { allow: false, reason: "Policy check failed." };
+        }
+        this.onEvent({ type: "call", server: this.server, tool, args, allowed: decision.allow, reason: decision.reason });
+        if (decision.allow)
+            return { forward: msg };
+        // Denied: reply to the agent with an MCP tool *result* carrying isError,
+        // so the agent sees a normal tool failure rather than a transport crash.
+        if (msg.id !== undefined && msg.id !== null)
+            this.denied.add(msg.id);
+        return {
+            reply: {
+                jsonrpc: "2.0",
+                id: msg.id ?? null,
+                result: {
+                    isError: true,
+                    content: [{ type: "text", text: decision.reason || `Blocked by Bivy policy: ${tool}` }],
+                },
+            },
+        };
+    }
+    /** Observe one message coming from the server toward the agent (client). */
+    handleServerMessage(msg) {
+        const result = msg.result;
+        if (result && Array.isArray(result.tools)) {
+            const tools = result.tools
+                .map((t) => (t && typeof t === "object" ? t : {}))
+                .filter((t) => typeof t.name === "string")
+                .map((t) => ({ name: t.name, description: typeof t.description === "string" ? t.description : undefined }));
+            this.onEvent({ type: "tools", server: this.server, tools });
+        }
+        else if (msg.id !== undefined && msg.id !== null && (msg.result !== undefined || msg.error !== undefined)) {
+            const isError = Boolean(msg.result?.isError) || msg.error !== undefined;
+            this.onEvent({ type: "result", server: this.server, id: msg.id, isError });
+        }
+        return { forward: msg };
+    }
+    wasDenied(id) {
+        return this.denied.has(id);
+    }
+}
+/**
+ * Wrap the mediator around a real MCP server subprocess: agent ⇄ (this process's
+ * stdio) ⇄ mediator ⇄ child stdio ⇄ real server. Newline-delimited JSON-RPC in
+ * both directions. Resolves with the child's exit code.
+ */
+export function runMcpProxy(options) {
+    const mediator = new McpMediator(options);
+    const agentIn = options.agentInput ?? process.stdin;
+    const agentOut = options.agentOutput ?? process.stdout;
+    const child = spawn(options.command, options.args ?? [], {
+        stdio: ["pipe", "pipe", "inherit"],
+        env: { ...process.env, ...options.env },
+        cwd: options.cwd,
+    });
+    const writeToAgent = (msg) => agentOut.write(`${JSON.stringify(msg)}\n`);
+    const writeToServer = (msg) => child.stdin.write(`${JSON.stringify(msg)}\n`);
+    // Agent → (mediate) → server, or short-circuit back to the agent.
+    const fromAgent = createInterface({ input: agentIn });
+    fromAgent.on("line", (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            // Not valid JSON-RPC — drop it rather than forward a malformed frame.
+            return;
+        }
+        void mediator.handleClientMessage(msg).then((outcome) => {
+            if (outcome.reply)
+                writeToAgent(outcome.reply);
+            else if (outcome.forward)
+                writeToServer(outcome.forward);
+        });
+    });
+    // When the agent closes its side, close the server's stdin so it sees EOF and
+    // shuts down (otherwise the child — and this promise — would hang forever).
+    fromAgent.on("close", () => child.stdin.end());
+    // Server → (observe) → agent.
+    const fromServer = createInterface({ input: child.stdout });
+    fromServer.on("line", (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            process.stdout.write(`${line}\n`);
+            return;
+        }
+        writeToAgent(mediator.handleServerMessage(msg).forward);
+    });
+    return new Promise((resolve) => {
+        child.on("exit", (code) => resolve(code ?? 0));
+        child.on("error", () => resolve(1));
+    });
+}