@cyanmycelium/mcp-broker 0.1.0

package/src/broker/broker.server.ts

@@ -0,0 +1,168 @@
+import { McpGrammar, McpServerBuilder, LoopbackTransport } from "@cyanmycelium/mcp-core";
+import type { IMcpServer, IMessageTransport } from "@cyanmycelium/mcp-core";
+import { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
+import { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
+import { brokerGrammarKey, defaultBrokerLocaleResolver, defaultBrokerUserAgentResolver, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom } from "./broker.grammars.js";
+import type { BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker.grammars.js";
+import type { BrokerContext } from "./broker.context.js";
+
+/**
+ * Reserved provider slot name under which the broker exposes itself as an MCP
+ * server. Clients reach it via `<host>/_broker/mcp` (or any other client transport).
+ *
+ * Prefixed with `_` to make it unambiguously a system slot, and to reduce the
+ * chance of collision with user-supplied provider names.
+ */
+export const BROKER_PROVIDER_NAME = "_broker";
+
+/**
+ * Optional knobs passed to {@link startBrokerServer}. Lets the embedder
+ * replace either resolver with custom logic without touching mcp-broker
+ * internals.
+ */
+export interface StartBrokerServerOptions {
+    /**
+     * Picks a locale (BCP-47 base language, by convention) for the current
+     * session. Defaults to {@link defaultBrokerLocaleResolver} which reads
+     * `MCP_BROKER_LOCALE` and keeps the ISO 639-1 prefix.
+     */
+    localeResolver?: BrokerLocaleResolver;
+
+    /**
+     * Picks a user-agent family for the connecting client. Defaults to
+     * {@link defaultBrokerUserAgentResolver} which substring-matches
+     * `clientInfo.name` against known LLM families.
+     */
+    userAgentResolver?: BrokerUserAgentResolver;
+
+    /**
+     * Source of the raw locale string fed to the locale resolver. Defaults
+     * to `process.env.MCP_BROKER_LOCALE`. Override when the locale lives
+     * somewhere else (config file, session metadata, HTTP header proxy, ...).
+     */
+    localeSource?: () => string | undefined;
+
+    /**
+     * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
+     * files are merged **on top of** the packaged grammars. Local entries win
+     * on conflicts; missing entries fall through to the packaged values.
+     *
+     * When `undefined` (default), only the packaged grammars are used.
+     */
+    localGrammarsDir?: string;
+}
+
+/**
+ * Constructs the broker's own MCP server (the Tier-1 introspection behaviors)
+ * and returns the running server plus the loopback transport that must be
+ * registered against the {@link WsTunnel} as the `_broker` provider slot.
+ *
+ * Usage from {@link WsTunnel.start}:
+ * ```ts
+ * const { server, clientTransport } = await startBrokerServer(this, { ... });
+ * this._registerLoopbackProvider(BROKER_PROVIDER_NAME, clientTransport);
+ * ```
+ *
+ * @param context  Read-only view of the broker's state.
+ * @param options  Optional resolver overrides.
+ * @returns The running {@link IMcpServer} (call `.stop()` on shutdown) and the
+ *          loopback transport to attach to the tunnel.
+ */
+export async function startBrokerServer(
+    context: BrokerContext,
+    options: StartBrokerServerOptions = {}
+): Promise<{
+    server: IMcpServer;
+    clientTransport: IMessageTransport;
+}> {
+    const localeResolver = options.localeResolver ?? defaultBrokerLocaleResolver;
+    const userAgentResolver = options.userAgentResolver ?? defaultBrokerUserAgentResolver;
+    const localeSource = options.localeSource ?? (() => process.env["MCP_BROKER_LOCALE"]);
+
+    const [serverEnd, clientEnd] = LoopbackTransport.createPair();
+
+    const builder = new McpServerBuilder().withName(BROKER_PROVIDER_NAME).withTransport(serverEnd).register(new BrokerInfoBehavior(context), new BrokerProvidersBehavior(context));
+
+    // Discover every grammar by scanning two directories:
+    //   1. The packaged grammars shipped with the broker.
+    //   2. Optionally, a user-supplied directory whose entries are merged
+    //      ON TOP of the packaged ones (local wins on conflicts).
+    //
+    // Then build the (userAgent × locale) matrix. Within each user-agent,
+    // the grammar cascades on top of "default:<locale>" so per-user-agent
+    // files can stay partial.
+    const defaults = new Map<string, McpGrammar>(); // locale → grammar
+    const overrides = new Map<BrokerUserAgent, Map<string, McpGrammar>>(); // userAgent → locale → grammar
+
+    function ingest(entry: { userAgent: BrokerUserAgent; locale: string; grammar: McpGrammar }, isOverride: boolean): void {
+        if (entry.userAgent === "default") {
+            const existing = defaults.get(entry.locale);
+            const merged = existing && isOverride ? McpGrammar.merge(existing, entry.grammar) : entry.grammar;
+            defaults.set(entry.locale, merged);
+        } else {
+            let byLocale = overrides.get(entry.userAgent);
+            if (!byLocale) {
+                byLocale = new Map();
+                overrides.set(entry.userAgent, byLocale);
+            }
+            const existing = byLocale.get(entry.locale);
+            const merged = existing && isOverride ? McpGrammar.merge(existing, entry.grammar) : entry.grammar;
+            byLocale.set(entry.locale, merged);
+        }
+    }
+
+    for (const entry of iterAvailableBrokerGrammars()) ingest(entry, false);
+    if (options.localGrammarsDir) {
+        for (const entry of iterBrokerGrammarsFrom(options.localGrammarsDir)) ingest(entry, true);
+    }
+
+    const availableKeys = new Set<string>();
+
+    // Register every "default:<locale>" as-is.
+    for (const [locale, grammar] of defaults) {
+        const key = brokerGrammarKey("default", locale);
+        builder.withGrammar(key, grammar);
+        availableKeys.add(key);
+    }
+
+    // Register every "<userAgent>:<locale>" as merge(default:<locale>, ua:<locale>).
+    // The user-agent grammar wins per entry; missing entries cascade from default.
+    for (const [agent, byLocale] of overrides) {
+        for (const [locale, uaGrammar] of byLocale) {
+            const baseline = defaults.get(locale);
+            const merged = baseline ? McpGrammar.merge(baseline, uaGrammar) : uaGrammar;
+            const key = brokerGrammarKey(agent, locale);
+            builder.withGrammar(key, merged);
+            availableKeys.add(key);
+        }
+    }
+
+    builder.withGrammarResolver((clientInfo) => {
+        // localeResolver returns the full fallback chain (most specific first),
+        // ending with the universal "en". The user-agent axis is the broker's
+        // own concern: per locale, prefer the user-agent-specific grammar, then
+        // fall back to the "default" agent.
+        const locales = localeResolver(localeSource());
+        const userAgent = userAgentResolver(clientInfo);
+        const userAgents = userAgent === "default" ? ["default"] : [userAgent, "default"];
+
+        for (const locale of locales) {
+            for (const ua of userAgents) {
+                const key = brokerGrammarKey(ua, locale);
+                if (availableKeys.has(key)) return key;
+            }
+        }
+
+        // None of the candidates is on disk → return an empty key. McpServer
+        // then falls back to the behavior's baseline descriptions (English).
+        return "";
+    });
+
+    // No reconnect policy → the McpServer does not attempt to reopen the loopback
+    // when WsTunnel.stop() closes it. Clean shutdown.
+    const server = builder.build();
+
+    await server.start();
+
+    return { server, clientTransport: clientEnd };
+}

package/src/broker/grammars/claude/en.json

@@ -0,0 +1,16 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Get the broker's identity: name, version, uptime, host, port, TLS, and URL paths. Call this first when you need to know what you are talking to."
+        },
+        "providers_list": {
+            "description": "List every provider slot on this broker, connected or not. Each entry tells you the transport kind, current client count, and how many requests are in flight. Use this to discover what you can route to."
+        },
+        "provider_status": {
+            "description": "Get the full status of one provider slot by name. Returns an error if the slot does not exist — start with providers_list if you are not sure of the name.",
+            "properties": {
+                "name": "The exact provider slot name. Case-sensitive. Use providers_list to discover valid values."
+            }
+        }
+    }
+}

package/src/broker/grammars/claude/fr.json

@@ -0,0 +1,16 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Récupère l'identité du broker : nom, version, uptime, hôte, port, TLS et chemins URL. À appeler en premier pour savoir à qui tu parles."
+        },
+        "providers_list": {
+            "description": "Liste tous les emplacements de providers de ce broker, connectés ou non. Chaque entrée indique le type de transport, le nombre de clients actuels et le nombre de requêtes en cours. Utilise-le pour découvrir vers qui tu peux router."
+        },
+        "provider_status": {
+            "description": "Récupère le statut complet d'un emplacement de provider par son nom. Retourne une erreur si l'emplacement n'existe pas — commence par providers_list si tu n'es pas sûr du nom.",
+            "properties": {
+                "name": "Le nom exact de l'emplacement provider. Sensible à la casse. Utilise providers_list pour découvrir les valeurs valides."
+            }
+        }
+    }
+}

package/src/broker/grammars/default/en.json

@@ -0,0 +1,32 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Returns the broker's name, version, uptime, host, port, TLS status, and configured URL paths."
+        },
+        "providers_list": {
+            "description": "Returns every provider slot known to the broker (connected and disconnected), with transport kind, client count, and pending request count."
+        },
+        "provider_status": {
+            "description": "Returns the status of one provider slot identified by name. Errors if the slot does not exist.",
+            "properties": {
+                "name": "Exact provider name (case-sensitive)."
+            }
+        }
+    },
+    "resources": {
+        "broker://info": {
+            "name": "Broker info",
+            "description": "Broker identity, version, uptime, and listening configuration."
+        },
+        "broker://providers": {
+            "name": "Broker providers",
+            "description": "List of every provider slot known to the broker, including disconnected ones."
+        }
+    },
+    "templates": {
+        "broker://providers/{name}": {
+            "name": "Broker provider",
+            "description": "Snapshot of one specific provider slot, addressed by its name."
+        }
+    }
+}

package/src/broker/grammars/default/fr.json

@@ -0,0 +1,32 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Retourne le nom, la version, l'uptime, l'hôte, le port, l'état TLS et les chemins URL du broker."
+        },
+        "providers_list": {
+            "description": "Liste tous les emplacements de providers connus du broker (connectés et déconnectés), avec leur type de transport, leur nombre de clients et le nombre de requêtes en attente."
+        },
+        "provider_status": {
+            "description": "Retourne l'état d'un emplacement de provider identifié par son nom. Échoue si le provider n'existe pas.",
+            "properties": {
+                "name": "Nom exact du provider (sensible à la casse)."
+            }
+        }
+    },
+    "resources": {
+        "broker://info": {
+            "name": "Informations du broker",
+            "description": "Identité, version, uptime et configuration d'écoute du broker."
+        },
+        "broker://providers": {
+            "name": "Providers du broker",
+            "description": "Liste de tous les emplacements de providers connus du broker, y compris les déconnectés."
+        }
+    },
+    "templates": {
+        "broker://providers/{name}": {
+            "name": "Provider du broker",
+            "description": "Snapshot d'un emplacement de provider spécifique, identifié par son nom."
+        }
+    }
+}

package/src/broker/grammars/default/zh.json

@@ -0,0 +1,32 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "返回 broker 的名称、版本、运行时间、主机、端口、TLS 状态和已配置的 URL 路径。"
+        },
+        "providers_list": {
+            "description": "列出 broker 已知的所有 provider 槽位（已连接和未连接），包括传输类型、客户端数量和待处理请求数量。"
+        },
+        "provider_status": {
+            "description": "返回由名称标识的某个 provider 槽位的状态。如果槽位不存在则返回错误。",
+            "properties": {
+                "name": "provider 的精确名称（区分大小写）。"
+            }
+        }
+    },
+    "resources": {
+        "broker://info": {
+            "name": "Broker 信息",
+            "description": "Broker 的身份、版本、运行时间和监听配置。"
+        },
+        "broker://providers": {
+            "name": "Broker Providers",
+            "description": "Broker 已知的所有 provider 槽位列表，包括未连接的。"
+        }
+    },
+    "templates": {
+        "broker://providers/{name}": {
+            "name": "Broker Provider",
+            "description": "指定名称的 provider 槽位快照。"
+        }
+    }
+}

package/src/broker/index.ts

@@ -0,0 +1,24 @@
+export { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
+export { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
+export { BrokerInfoAdapter, BROKER_INFO_URI } from "./adapters/broker.adapter.info.js";
+export { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "./adapters/broker.adapter.providers.js";
+export { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker.server.js";
+export type { StartBrokerServerOptions } from "./broker.server.js";
+export {
+    brokerBaselineGrammar,
+    brokerBaselinePropertyDescription,
+    brokerBaselineResourceDescription,
+    brokerBaselineResourceName,
+    brokerBaselineResourceTemplateDescription,
+    brokerBaselineResourceTemplateName,
+    brokerBaselineToolDescription,
+    brokerGrammarKey,
+    defaultBrokerLocaleResolver,
+    defaultBrokerUserAgentResolver,
+    iterAvailableBrokerGrammars,
+    loadBrokerGrammar,
+    resolveBrokerLocale,
+    resolveBrokerUserAgent,
+} from "./broker.grammars.js";
+export type { BrokerLocale, BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker.grammars.js";
+export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport } from "./broker.context.js";

package/src/config.ts

@@ -0,0 +1,155 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/**
+ * Shape of the optional JSON config file consumed by `bin.ts` at startup.
+ * Every field is optional. Environment variables (`MCP_BROKER_*`) always win
+ * over file values, and file values win over the built-in defaults.
+ *
+ * @example
+ * ```json
+ * {
+ *     "port": 3001,
+ *     "locale": "fr",
+ *     "tls": { "cert": "certs/cert.pem", "key": "certs/key.pem" },
+ *     "stdioUpstreams": [
+ *         { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
+ *     ]
+ * }
+ * ```
+ */
+export interface BrokerConfig {
+    /** TCP port. Maps to `MCP_BROKER_PORT`. */
+    port?: number;
+
+    /** Bind host. Maps to `MCP_BROKER_HOST`. */
+    host?: string;
+
+    /** Force protocol (`http`/`https`) regardless of cert presence. Maps to `MCP_BROKER_PROTOCOL`. */
+    protocol?: "http" | "https";
+
+    /** Locale fed to the broker grammar resolver. Maps to `MCP_BROKER_LOCALE`. */
+    locale?: string;
+
+    /** Bridge stdin/stdout for a Claude-Desktop-style client. Maps to `MCP_BROKER_STDIO_PROVIDER`. */
+    stdioProvider?: string;
+
+    /** Logical broker name reported by `broker_info`. */
+    brokerName?: string;
+
+    /** URL paths (override the defaults). */
+    paths?: {
+        provider?: string;
+        providers?: string;
+        client?: string;
+        mcp?: string;
+        sse?: string;
+        messages?: string;
+    };
+
+    /** TLS material as paths on disk. Resolved against the config file's directory. */
+    tls?: {
+        cert: string;
+        key: string;
+    };
+
+    /**
+     * Static-file serving alongside the JSON-RPC endpoints. JSON-RPC routes
+     * always take precedence.
+     */
+    www?: {
+        /** Auto-launch the default browser at the root URL on startup. */
+        open?: boolean;
+        /** URL-prefix → directory mappings. Longest-prefix match wins. */
+        mounts?: Array<{
+            urlPrefix: string;
+            dir: string;
+        }>;
+    };
+
+    /** Stdio upstream providers spawned by the broker at startup. */
+    stdioUpstreams?: Array<{
+        name: string;
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    }>;
+}
+
+/**
+ * Returned by {@link loadBrokerConfig}. The {@link config} is the parsed JSON;
+ * {@link baseDir} is the directory used to resolve relative paths inside it
+ * (the directory containing the config file when one was found, otherwise
+ * `process.cwd()`).
+ */
+export interface LoadedBrokerConfig {
+    config: BrokerConfig;
+    baseDir: string;
+    /** Absolute path of the config file that was loaded, or `null` if none. */
+    sourcePath: string | null;
+}
+
+/** Default folder name (relative to `process.cwd()`) holding broker-local files. */
+export const DEFAULT_CONFIG_DIR = ".mcp-broker";
+
+/** Default config filename inside {@link DEFAULT_CONFIG_DIR}. */
+export const DEFAULT_CONFIG_FILENAME = "config.json";
+
+/** Legacy flat config filename at the cwd root (pre-`.mcp-broker/` layout). */
+export const LEGACY_CONFIG_FILENAME = "mcp-broker.config.json";
+
+/**
+ * Loads the broker config from a JSON file.
+ *
+ * Discovery order:
+ * 1. The `path` argument when provided (explicit override).
+ * 2. The `MCP_BROKER_CONFIG` env var.
+ * 3. `./.mcp-broker/config.json` relative to `process.cwd()`.
+ * 4. `./mcp-broker.config.json` relative to `process.cwd()` (legacy layout —
+ *    a deprecation warning is written to stderr).
+ *
+ * When no file is found, returns the built-in empty config with
+ * `baseDir = process.cwd()`. On invalid JSON, logs a warning to stderr and
+ * returns the same empty config — never throws.
+ *
+ * Paths inside the config file are intended to be resolved against
+ * {@link LoadedBrokerConfig.baseDir} by the consumer.
+ */
+export function loadBrokerConfig(path?: string): LoadedBrokerConfig {
+    const cwd = process.cwd();
+    const envPath = process.env["MCP_BROKER_CONFIG"];
+
+    let sourcePath: string | null = null;
+
+    if (path) {
+        sourcePath = resolve(cwd, path);
+    } else if (envPath) {
+        sourcePath = resolve(cwd, envPath);
+    } else {
+        const modern = resolve(cwd, DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_FILENAME);
+        const legacy = resolve(cwd, LEGACY_CONFIG_FILENAME);
+        if (existsSync(modern)) {
+            sourcePath = modern;
+        } else if (existsSync(legacy)) {
+            sourcePath = legacy;
+            process.stderr.write(
+                `[mcp-broker] Using legacy config at ${legacy}. ` + `Move it to ${resolve(cwd, DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_FILENAME)} ` + `to silence this warning.\n`
+            );
+        }
+    }
+
+    if (!sourcePath || !existsSync(sourcePath)) {
+        return { config: {}, baseDir: cwd, sourcePath: null };
+    }
+
+    const baseDir = dirname(sourcePath);
+
+    try {
+        const raw = readFileSync(sourcePath, "utf-8");
+        const config = JSON.parse(raw) as BrokerConfig;
+        return { config, baseDir, sourcePath };
+    } catch (err) {
+        process.stderr.write(`[mcp-broker] Failed to parse config file at ${sourcePath}: ${(err as Error).message}\n`);
+        return { config: {}, baseDir: cwd, sourcePath: null };
+    }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { WsTunnel } from "./ws.tunnel.js";
+export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
+export type { WsTunnelOptions, StaticMount } from "./ws.tunnel.js";
+export { StdioUpstream } from "./stdio.upstream.js";
+export type { StdioUpstreamConfig } from "./stdio.upstream.js";
+
+// Broker introspection — tier 1.
+export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
+export type { StartBrokerServerOptions } from "./broker/index.js";
+export {
+    brokerGrammarKey,
+    defaultBrokerLocaleResolver,
+    defaultBrokerUserAgentResolver,
+    iterAvailableBrokerGrammars,
+    loadBrokerGrammar,
+    resolveBrokerLocale,
+    resolveBrokerUserAgent,
+} from "./broker/index.js";
+export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport, BrokerLocale, BrokerLocaleResolver, BrokerUserAgent, BrokerUserAgentResolver } from "./broker/index.js";
+
+export { VERSION, PACKAGE_NAME } from "./version.js";
+
+// JSON config file used by `bin.ts` at startup. Exported so a programmatic
+// embedder can re-use the same loader against a custom path.
+export { loadBrokerConfig, DEFAULT_CONFIG_FILENAME } from "./config.js";
+export type { BrokerConfig } from "./config.js";

package/src/stdio.upstream.ts

@@ -0,0 +1,114 @@
+import { spawn, ChildProcess } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface StdioUpstreamConfig {
+    /** Logical name of this provider (matched against incoming WebSocket provider names). */
+    name: string;
+    /** Executable to spawn (e.g. `"node"`, `"python"`, an absolute path). */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Extra environment variables merged with `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+
+// ---------------------------------------------------------------------------
+// StdioUpstream
+// ---------------------------------------------------------------------------
+
+/**
+ * Manages a stdio-based MCP server process.
+ * JSON-RPC messages are exchanged over the child process stdin/stdout using
+ * newline-delimited framing (matching the MCP SDK stdio transport).
+ *
+ * One instance per configured provider. The broker uses this to bridge
+ * WebSocket/SSE/HTTP clients to local MCP server processes.
+ */
+export class StdioUpstream {
+    readonly name: string;
+
+    private readonly _config: StdioUpstreamConfig;
+    private _proc: ChildProcess | null = null;
+    private _buffer = "";
+    private _open = false;
+    private _stopped = false;
+
+    /** Called when a complete JSON-RPC line arrives from the process stdout. */
+    onMessage: ((data: string) => void) | null = null;
+
+    /** Called when the process has started and stdin is writable. */
+    onOpen: (() => void) | null = null;
+
+    /** Called when the process exits (cleanly or otherwise). */
+    onClose: (() => void) | null = null;
+
+    /** Called on spawn or runtime errors. */
+    onError: ((error: Error) => void) | null = null;
+
+    constructor(config: StdioUpstreamConfig) {
+        this.name = config.name;
+        this._config = config;
+    }
+
+    get isOpen(): boolean {
+        return this._open;
+    }
+
+    /** Spawns the child process and wires up stdio listeners. */
+    connect(): void {
+        this._stopped = false;
+        const { command, args = [], env } = this._config;
+
+        this._proc = spawn(command, args, {
+            env: { ...process.env, ...env },
+            stdio: ["pipe", "pipe", "inherit"],
+        });
+
+        this._proc.on("error", (err: Error) => {
+            this._open = false;
+            this.onError?.(new Error(`StdioUpstream "${this.name}": process error — ${err.message}`));
+        });
+
+        this._proc.on("spawn", () => {
+            this._open = true;
+            this.onOpen?.();
+        });
+
+        this._proc.stdout!.on("data", (chunk: Buffer) => {
+            this._buffer += chunk.toString("utf8");
+            let nl: number;
+            while ((nl = this._buffer.indexOf("\n")) !== -1) {
+                const line = this._buffer.slice(0, nl).trim();
+                this._buffer = this._buffer.slice(nl + 1);
+                if (line) this.onMessage?.(line);
+            }
+        });
+
+        this._proc.on("close", (code) => {
+            this._open = false;
+            this._proc = null;
+            this.onClose?.();
+            if (!this._stopped) {
+                this.onError?.(new Error(`StdioUpstream "${this.name}": process exited with code ${code ?? "null"}`));
+            }
+        });
+    }
+
+    /** Sends a JSON-RPC message to the process stdin (appends newline). */
+    send(data: string): void {
+        if (!this._open || !this._proc?.stdin?.writable) return;
+        this._proc.stdin.write(data + "\n", "utf8");
+    }
+
+    /** Kills the child process and prevents further reconnection attempts. */
+    close(): void {
+        this._stopped = true;
+        this._open = false;
+        this._proc?.stdin?.end();
+        this._proc?.kill();
+        this._proc = null;
+    }
+}

package/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "module";
+
+// Resolves the package's own version from package.json without bundler help.
+// Works both for the compiled dist/version.js (one level below package.json)
+// and for tsc's source-level resolution from src/version.ts.
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json") as { version: string; name: string };
+
+export const VERSION: string = pkg.version;
+export const PACKAGE_NAME: string = pkg.name;