open-multi-agent-kit 0.95.0 → 0.95.2

package/dist/core/mcp/manager.js

@@ -0,0 +1,173 @@
+/**
+ * Lazy, crash-isolated MCP server manager.
+ *
+ * Design constraints that shaped this:
+ * - A workspace can configure 25 servers. Spawning them all at startup would
+ *   trade a 0.6s cold start for a multi-second one, so connection is lazy and
+ *   only happens when tools are actually requested.
+ * - One broken server must never take a session down. Every connect and every
+ *   listing is isolated; a failure is recorded as server status and the other
+ *   servers still contribute tools.
+ * - Connect work is deduplicated: concurrent `listToolDefinitions()` calls
+ *   share one in-flight connect per server.
+ */
+import { McpClient } from "./client.js";
+import { createMcpToolDefinition } from "./tools.js";
+export class McpManager {
+    runtimes = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+        for (const config of options.servers) {
+            if (this.runtimes.has(config.name))
+                continue; // First definition wins; inventory already applies precedence.
+            this.runtimes.set(config.name, { config, state: "idle", tools: [] });
+        }
+    }
+    /** Configured server names, in configuration order. */
+    get serverNames() {
+        return [...this.runtimes.keys()];
+    }
+    /** Current status per server. Safe to call before any connection attempt. */
+    status() {
+        return [...this.runtimes.values()].map((runtime) => ({
+            name: runtime.config.name,
+            state: runtime.state,
+            toolCount: runtime.tools.length,
+            error: runtime.error,
+            serverVersion: runtime.client?.serverInfo.version,
+        }));
+    }
+    /**
+     * Connect every enabled server that has not been attempted yet, then return
+     * the union of their tools. Servers are connected concurrently and failures
+     * are isolated, so a partial result is the normal outcome, not an error.
+     */
+    async listToolDefinitions() {
+        await Promise.all([...this.runtimes.values()].map((runtime) => this.ensureConnected(runtime)));
+        const tools = [];
+        const seen = new Set();
+        for (const runtime of this.runtimes.values()) {
+            for (const tool of runtime.tools) {
+                if (seen.has(tool.name))
+                    continue; // Namespacing makes this rare; keep it deterministic anyway.
+                seen.add(tool.name);
+                tools.push(tool);
+            }
+        }
+        return tools;
+    }
+    /** Connect a single server by name. Returns its status either way. */
+    async connect(name) {
+        const runtime = this.runtimes.get(name);
+        if (!runtime) {
+            return { name, state: "failed", toolCount: 0, error: `Unknown MCP server "${name}"` };
+        }
+        await this.ensureConnected(runtime);
+        return {
+            name,
+            state: runtime.state,
+            toolCount: runtime.tools.length,
+            error: runtime.error,
+            serverVersion: runtime.client?.serverInfo.version,
+        };
+    }
+    /** Terminate every connected server. Idempotent. */
+    close() {
+        for (const runtime of this.runtimes.values()) {
+            runtime.client?.close();
+            runtime.client = undefined;
+            runtime.tools = [];
+            if (runtime.state === "ready" || runtime.state === "connecting")
+                runtime.state = "idle";
+        }
+    }
+    /**
+     * Verify that `ready` servers are actually alive with a protocol ping. A
+     * failed ping closes the client and marks the server `failed`, so a
+     * silently killed process stops masquerading as connected. Servers already
+     * `failed` are re-attempted only when `reconnectFailed` is set — callers
+     * should gate that behind a slow cadence so a permanently broken server is
+     * not respawned every probe. Idle servers stay idle: connection is lazy by
+     * design, and a status probe must not spawn processes.
+     */
+    async checkHealth(options) {
+        const work = [];
+        for (const runtime of this.runtimes.values()) {
+            if (runtime.state === "ready" && runtime.client) {
+                work.push(this.pingRuntime(runtime, options?.pingTimeoutMs));
+            }
+            else if (runtime.state === "failed" && options?.reconnectFailed && !runtime.config.disabled) {
+                runtime.state = "idle";
+                runtime.error = undefined;
+                work.push(this.ensureConnected(runtime));
+            }
+        }
+        await Promise.all(work);
+        return this.status();
+    }
+    async pingRuntime(runtime, timeoutMs) {
+        try {
+            await runtime.client?.ping(timeoutMs);
+        }
+        catch (error) {
+            // Isolation point: only this server transitions; the rest stay ready.
+            runtime.client?.close();
+            runtime.client = undefined;
+            runtime.tools = [];
+            runtime.state = "failed";
+            runtime.error = `health check failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    ensureConnected(runtime) {
+        if (runtime.config.disabled) {
+            runtime.state = "failed";
+            runtime.error = "disabled by configuration";
+            return Promise.resolve();
+        }
+        if (runtime.state === "ready" || runtime.state === "failed")
+            return Promise.resolve();
+        if (runtime.connecting)
+            return runtime.connecting;
+        runtime.state = "connecting";
+        const attempt = this.connectRuntime(runtime).finally(() => {
+            runtime.connecting = undefined;
+        });
+        runtime.connecting = attempt;
+        return attempt;
+    }
+    async connectRuntime(runtime) {
+        const clientOptions = {
+            name: runtime.config.name,
+            clientInfo: this.options.clientInfo,
+            requestTimeoutMs: runtime.config.requestTimeoutMs,
+            handshakeTimeoutMs: runtime.config.handshakeTimeoutMs,
+            transport: {
+                command: runtime.config.command,
+                args: runtime.config.args,
+                env: runtime.config.env,
+                cwd: runtime.config.cwd ?? this.options.cwd,
+            },
+        };
+        const client = this.options.createClient?.(clientOptions) ?? new McpClient(clientOptions);
+        try {
+            await client.connect();
+            const schemas = await client.listTools();
+            runtime.client = client;
+            runtime.tools = schemas.map((schema) => createMcpToolDefinition(runtime.config.name, client, schema, {
+                callTimeoutMs: this.options.callTimeoutMs,
+            }));
+            runtime.state = "ready";
+            runtime.error = undefined;
+        }
+        catch (error) {
+            // Isolation point: this server is out, every other server is unaffected.
+            client.close();
+            runtime.client = undefined;
+            runtime.tools = [];
+            runtime.state = "failed";
+            runtime.error = error instanceof Error ? error.message : String(error);
+        }
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/core/mcp/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/core/mcp/manager.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Lazy, crash-isolated MCP server manager.\n *\n * Design constraints that shaped this:\n * - A workspace can configure 25 servers. Spawning them all at startup would\n *   trade a 0.6s cold start for a multi-second one, so connection is lazy and\n *   only happens when tools are actually requested.\n * - One broken server must never take a session down. Every connect and every\n *   listing is isolated; a failure is recorded as server status and the other\n *   servers still contribute tools.\n * - Connect work is deduplicated: concurrent `listToolDefinitions()` calls\n *   share one in-flight connect per server.\n */\n\nimport type { TSchema } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport { McpClient, type McpClientOptions } from \"./client.ts\";\nimport { createMcpToolDefinition, type McpToolDetails } from \"./tools.ts\";\n\nexport type McpServerState = \"idle\" | \"connecting\" | \"ready\" | \"failed\";\n\nexport interface McpServerConfig {\n\treadonly name: string;\n\treadonly command: string;\n\treadonly args?: readonly string[];\n\treadonly env?: Readonly<Record<string, string>>;\n\treadonly cwd?: string;\n\t/** Skip this server without removing it from configuration. */\n\treadonly disabled?: boolean;\n\treadonly requestTimeoutMs?: number;\n\treadonly handshakeTimeoutMs?: number;\n}\n\nexport interface McpServerStatus {\n\treadonly name: string;\n\treadonly state: McpServerState;\n\treadonly toolCount: number;\n\t/** Failure reason when `state` is `failed`. Never contains configured env values. */\n\treadonly error?: string;\n\treadonly serverVersion?: string;\n}\n\nexport interface McpManagerOptions {\n\treadonly servers: readonly McpServerConfig[];\n\treadonly cwd?: string;\n\treadonly clientInfo?: { readonly name: string; readonly version: string };\n\treadonly callTimeoutMs?: number;\n\t/** Injected for tests so the manager can be exercised without spawning processes. */\n\treadonly createClient?: (options: McpClientOptions) => McpClient;\n}\n\ninterface ServerRuntime {\n\treadonly config: McpServerConfig;\n\tstate: McpServerState;\n\tclient?: McpClient;\n\ttools: ToolDefinition<TSchema, McpToolDetails>[];\n\terror?: string;\n\tconnecting?: Promise<void>;\n}\n\nexport class McpManager {\n\tprivate readonly runtimes = new Map<string, ServerRuntime>();\n\tprivate readonly options: McpManagerOptions;\n\n\tconstructor(options: McpManagerOptions) {\n\t\tthis.options = options;\n\t\tfor (const config of options.servers) {\n\t\t\tif (this.runtimes.has(config.name)) continue; // First definition wins; inventory already applies precedence.\n\t\t\tthis.runtimes.set(config.name, { config, state: \"idle\", tools: [] });\n\t\t}\n\t}\n\n\t/** Configured server names, in configuration order. */\n\tget serverNames(): string[] {\n\t\treturn [...this.runtimes.keys()];\n\t}\n\n\t/** Current status per server. Safe to call before any connection attempt. */\n\tstatus(): McpServerStatus[] {\n\t\treturn [...this.runtimes.values()].map((runtime) => ({\n\t\t\tname: runtime.config.name,\n\t\t\tstate: runtime.state,\n\t\t\ttoolCount: runtime.tools.length,\n\t\t\terror: runtime.error,\n\t\t\tserverVersion: runtime.client?.serverInfo.version,\n\t\t}));\n\t}\n\n\t/**\n\t * Connect every enabled server that has not been attempted yet, then return\n\t * the union of their tools. Servers are connected concurrently and failures\n\t * are isolated, so a partial result is the normal outcome, not an error.\n\t */\n\tasync listToolDefinitions(): Promise<ToolDefinition<TSchema, McpToolDetails>[]> {\n\t\tawait Promise.all([...this.runtimes.values()].map((runtime) => this.ensureConnected(runtime)));\n\t\tconst tools: ToolDefinition<TSchema, McpToolDetails>[] = [];\n\t\tconst seen = new Set<string>();\n\t\tfor (const runtime of this.runtimes.values()) {\n\t\t\tfor (const tool of runtime.tools) {\n\t\t\t\tif (seen.has(tool.name)) continue; // Namespacing makes this rare; keep it deterministic anyway.\n\t\t\t\tseen.add(tool.name);\n\t\t\t\ttools.push(tool);\n\t\t\t}\n\t\t}\n\t\treturn tools;\n\t}\n\n\t/** Connect a single server by name. Returns its status either way. */\n\tasync connect(name: string): Promise<McpServerStatus> {\n\t\tconst runtime = this.runtimes.get(name);\n\t\tif (!runtime) {\n\t\t\treturn { name, state: \"failed\", toolCount: 0, error: `Unknown MCP server \"${name}\"` };\n\t\t}\n\t\tawait this.ensureConnected(runtime);\n\t\treturn {\n\t\t\tname,\n\t\t\tstate: runtime.state,\n\t\t\ttoolCount: runtime.tools.length,\n\t\t\terror: runtime.error,\n\t\t\tserverVersion: runtime.client?.serverInfo.version,\n\t\t};\n\t}\n\n\t/** Terminate every connected server. Idempotent. */\n\tclose(): void {\n\t\tfor (const runtime of this.runtimes.values()) {\n\t\t\truntime.client?.close();\n\t\t\truntime.client = undefined;\n\t\t\truntime.tools = [];\n\t\t\tif (runtime.state === \"ready\" || runtime.state === \"connecting\") runtime.state = \"idle\";\n\t\t}\n\t}\n\n\t/**\n\t * Verify that `ready` servers are actually alive with a protocol ping. A\n\t * failed ping closes the client and marks the server `failed`, so a\n\t * silently killed process stops masquerading as connected. Servers already\n\t * `failed` are re-attempted only when `reconnectFailed` is set — callers\n\t * should gate that behind a slow cadence so a permanently broken server is\n\t * not respawned every probe. Idle servers stay idle: connection is lazy by\n\t * design, and a status probe must not spawn processes.\n\t */\n\tasync checkHealth(options?: { pingTimeoutMs?: number; reconnectFailed?: boolean }): Promise<McpServerStatus[]> {\n\t\tconst work: Promise<void>[] = [];\n\t\tfor (const runtime of this.runtimes.values()) {\n\t\t\tif (runtime.state === \"ready\" && runtime.client) {\n\t\t\t\twork.push(this.pingRuntime(runtime, options?.pingTimeoutMs));\n\t\t\t} else if (runtime.state === \"failed\" && options?.reconnectFailed && !runtime.config.disabled) {\n\t\t\t\truntime.state = \"idle\";\n\t\t\t\truntime.error = undefined;\n\t\t\t\twork.push(this.ensureConnected(runtime));\n\t\t\t}\n\t\t}\n\t\tawait Promise.all(work);\n\t\treturn this.status();\n\t}\n\n\tprivate async pingRuntime(runtime: ServerRuntime, timeoutMs?: number): Promise<void> {\n\t\ttry {\n\t\t\tawait runtime.client?.ping(timeoutMs);\n\t\t} catch (error) {\n\t\t\t// Isolation point: only this server transitions; the rest stay ready.\n\t\t\truntime.client?.close();\n\t\t\truntime.client = undefined;\n\t\t\truntime.tools = [];\n\t\t\truntime.state = \"failed\";\n\t\t\truntime.error = `health check failed: ${error instanceof Error ? error.message : String(error)}`;\n\t\t}\n\t}\n\n\tprivate ensureConnected(runtime: ServerRuntime): Promise<void> {\n\t\tif (runtime.config.disabled) {\n\t\t\truntime.state = \"failed\";\n\t\t\truntime.error = \"disabled by configuration\";\n\t\t\treturn Promise.resolve();\n\t\t}\n\t\tif (runtime.state === \"ready\" || runtime.state === \"failed\") return Promise.resolve();\n\t\tif (runtime.connecting) return runtime.connecting;\n\n\t\truntime.state = \"connecting\";\n\t\tconst attempt = this.connectRuntime(runtime).finally(() => {\n\t\t\truntime.connecting = undefined;\n\t\t});\n\t\truntime.connecting = attempt;\n\t\treturn attempt;\n\t}\n\n\tprivate async connectRuntime(runtime: ServerRuntime): Promise<void> {\n\t\tconst clientOptions: McpClientOptions = {\n\t\t\tname: runtime.config.name,\n\t\t\tclientInfo: this.options.clientInfo,\n\t\t\trequestTimeoutMs: runtime.config.requestTimeoutMs,\n\t\t\thandshakeTimeoutMs: runtime.config.handshakeTimeoutMs,\n\t\t\ttransport: {\n\t\t\t\tcommand: runtime.config.command,\n\t\t\t\targs: runtime.config.args,\n\t\t\t\tenv: runtime.config.env,\n\t\t\t\tcwd: runtime.config.cwd ?? this.options.cwd,\n\t\t\t},\n\t\t};\n\t\tconst client = this.options.createClient?.(clientOptions) ?? new McpClient(clientOptions);\n\t\ttry {\n\t\t\tawait client.connect();\n\t\t\tconst schemas = await client.listTools();\n\t\t\truntime.client = client;\n\t\t\truntime.tools = schemas.map((schema) =>\n\t\t\t\tcreateMcpToolDefinition(runtime.config.name, client, schema, {\n\t\t\t\t\tcallTimeoutMs: this.options.callTimeoutMs,\n\t\t\t\t}),\n\t\t\t);\n\t\t\truntime.state = \"ready\";\n\t\t\truntime.error = undefined;\n\t\t} catch (error) {\n\t\t\t// Isolation point: this server is out, every other server is unaffected.\n\t\t\tclient.close();\n\t\t\truntime.client = undefined;\n\t\t\truntime.tools = [];\n\t\t\truntime.state = \"failed\";\n\t\t\truntime.error = error instanceof Error ? error.message : String(error);\n\t\t}\n\t}\n}\n"]}

package/dist/core/mcp/protocol.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure JSON-RPC 2.0 framing for the MCP stdio transport.
+ *
+ * MCP stdio frames one JSON message per line on stdout; embedded newlines are
+ * illegal, so decoding is a line split with a hard length ceiling. Nothing here
+ * touches a process, a socket, or a clock — the transport owns all I/O so this
+ * layer stays trivially testable.
+ */
+/** Ceiling for a single decoded line. A server that exceeds it is malfunctioning, not slow. */
+export declare const MAX_MESSAGE_LINE_BYTES: number;
+export type JsonRpcId = number | string;
+export interface JsonRpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: JsonRpcId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcErrorBody {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface JsonRpcResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: JsonRpcId;
+    readonly result?: unknown;
+    readonly error?: JsonRpcErrorBody;
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+export declare function isJsonRpcResponse(message: unknown): message is JsonRpcResponse;
+export declare function isJsonRpcNotification(message: unknown): message is JsonRpcNotification;
+export declare function isJsonRpcRequest(message: unknown): message is JsonRpcRequest;
+/** Serialize one message as a single stdio frame (JSON + newline). */
+export declare function encodeMessage(message: JsonRpcMessage): string;
+export interface DecodedLine {
+    /** Parsed message, when the line was valid JSON. */
+    readonly message?: JsonRpcMessage;
+    /** Why the line was dropped, when it was not usable. */
+    readonly error?: string;
+}
+/**
+ * Incremental newline-delimited JSON decoder.
+ *
+ * Holds at most one partial line. A line longer than {@link MAX_MESSAGE_LINE_BYTES}
+ * is dropped with an error rather than buffered, so a runaway server cannot
+ * exhaust memory.
+ */
+export declare function createLineDecoder(maxLineBytes?: number): {
+    push(chunk: string): DecodedLine[];
+    reset(): void;
+};
+/** Format a JSON-RPC error body for a human or a model. */
+export declare function formatJsonRpcError(error: JsonRpcErrorBody): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/core/mcp/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAClC;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,mBAAmB,GAAG,eAAe,CAAC;AAMpF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,eAAe,CAM9E;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,mBAAmB,CAEtF;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,cAAc,CAK5E;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAQ7D;AAED,MAAM,WAAW,WAAW;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,GAAE,MAA+B,GAAG;IACjF,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IACnC,KAAK,IAAI,IAAI,CAAC;CACd,CAkCA;AAeD,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAGlE","sourcesContent":["/**\n * Pure JSON-RPC 2.0 framing for the MCP stdio transport.\n *\n * MCP stdio frames one JSON message per line on stdout; embedded newlines are\n * illegal, so decoding is a line split with a hard length ceiling. Nothing here\n * touches a process, a socket, or a clock — the transport owns all I/O so this\n * layer stays trivially testable.\n */\n\n/** Ceiling for a single decoded line. A server that exceeds it is malfunctioning, not slow. */\nexport const MAX_MESSAGE_LINE_BYTES = 16 * 1024 * 1024;\n\nexport type JsonRpcId = number | string;\n\nexport interface JsonRpcRequest {\n\treadonly jsonrpc: \"2.0\";\n\treadonly id: JsonRpcId;\n\treadonly method: string;\n\treadonly params?: unknown;\n}\n\nexport interface JsonRpcNotification {\n\treadonly jsonrpc: \"2.0\";\n\treadonly method: string;\n\treadonly params?: unknown;\n}\n\nexport interface JsonRpcErrorBody {\n\treadonly code: number;\n\treadonly message: string;\n\treadonly data?: unknown;\n}\n\nexport interface JsonRpcResponse {\n\treadonly jsonrpc: \"2.0\";\n\treadonly id: JsonRpcId;\n\treadonly result?: unknown;\n\treadonly error?: JsonRpcErrorBody;\n}\n\nexport type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function isJsonRpcResponse(message: unknown): message is JsonRpcResponse {\n\tif (!isRecord(message) || message.jsonrpc !== \"2.0\") return false;\n\tif (!(\"id\" in message)) return false;\n\tconst id = message.id;\n\tif (typeof id !== \"number\" && typeof id !== \"string\") return false;\n\treturn \"result\" in message || \"error\" in message;\n}\n\nexport function isJsonRpcNotification(message: unknown): message is JsonRpcNotification {\n\treturn isRecord(message) && message.jsonrpc === \"2.0\" && typeof message.method === \"string\" && !(\"id\" in message);\n}\n\nexport function isJsonRpcRequest(message: unknown): message is JsonRpcRequest {\n\tif (!isRecord(message) || message.jsonrpc !== \"2.0\") return false;\n\tif (typeof message.method !== \"string\") return false;\n\tconst id = message.id;\n\treturn typeof id === \"number\" || typeof id === \"string\";\n}\n\n/** Serialize one message as a single stdio frame (JSON + newline). */\nexport function encodeMessage(message: JsonRpcMessage): string {\n\tconst line = JSON.stringify(message);\n\tif (line.includes(\"\\n\")) {\n\t\t// JSON.stringify escapes newlines, so this is unreachable for valid input;\n\t\t// keep the guard so a future custom serializer cannot corrupt framing.\n\t\tthrow new Error(\"MCP frame contains a literal newline\");\n\t}\n\treturn `${line}\\n`;\n}\n\nexport interface DecodedLine {\n\t/** Parsed message, when the line was valid JSON. */\n\treadonly message?: JsonRpcMessage;\n\t/** Why the line was dropped, when it was not usable. */\n\treadonly error?: string;\n}\n\n/**\n * Incremental newline-delimited JSON decoder.\n *\n * Holds at most one partial line. A line longer than {@link MAX_MESSAGE_LINE_BYTES}\n * is dropped with an error rather than buffered, so a runaway server cannot\n * exhaust memory.\n */\nexport function createLineDecoder(maxLineBytes: number = MAX_MESSAGE_LINE_BYTES): {\n\tpush(chunk: string): DecodedLine[];\n\treset(): void;\n} {\n\tlet buffer = \"\";\n\tlet overflowed = false;\n\n\treturn {\n\t\tpush(chunk: string): DecodedLine[] {\n\t\t\tconst out: DecodedLine[] = [];\n\t\t\tbuffer += chunk;\n\n\t\t\tlet newlineIndex = buffer.indexOf(\"\\n\");\n\t\t\twhile (newlineIndex !== -1) {\n\t\t\t\tconst line = buffer.slice(0, newlineIndex).trim();\n\t\t\t\tbuffer = buffer.slice(newlineIndex + 1);\n\t\t\t\tif (overflowed) {\n\t\t\t\t\t// The oversized line ends here; resume clean at the next boundary.\n\t\t\t\t\toverflowed = false;\n\t\t\t\t} else if (line.length > 0) {\n\t\t\t\t\tout.push(decodeLine(line));\n\t\t\t\t}\n\t\t\t\tnewlineIndex = buffer.indexOf(\"\\n\");\n\t\t\t}\n\n\t\t\tif (!overflowed && buffer.length > maxLineBytes) {\n\t\t\t\tout.push({ error: `MCP frame exceeded ${maxLineBytes} bytes` });\n\t\t\t\toverflowed = true;\n\t\t\t\tbuffer = \"\";\n\t\t\t}\n\t\t\treturn out;\n\t\t},\n\t\treset(): void {\n\t\t\tbuffer = \"\";\n\t\t\toverflowed = false;\n\t\t},\n\t};\n}\n\nfunction decodeLine(line: string): DecodedLine {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(line);\n\t} catch {\n\t\treturn { error: \"MCP frame is not valid JSON\" };\n\t}\n\tif (isJsonRpcResponse(parsed) || isJsonRpcNotification(parsed) || isJsonRpcRequest(parsed)) {\n\t\treturn { message: parsed };\n\t}\n\treturn { error: \"MCP frame is not a JSON-RPC 2.0 message\" };\n}\n\n/** Format a JSON-RPC error body for a human or a model. */\nexport function formatJsonRpcError(error: JsonRpcErrorBody): string {\n\tconst suffix = error.data === undefined ? \"\" : ` (${JSON.stringify(error.data)})`;\n\treturn `JSON-RPC error ${error.code}: ${error.message}${suffix}`;\n}\n"]}

package/dist/core/mcp/protocol.js

@@ -0,0 +1,103 @@
+/**
+ * Pure JSON-RPC 2.0 framing for the MCP stdio transport.
+ *
+ * MCP stdio frames one JSON message per line on stdout; embedded newlines are
+ * illegal, so decoding is a line split with a hard length ceiling. Nothing here
+ * touches a process, a socket, or a clock — the transport owns all I/O so this
+ * layer stays trivially testable.
+ */
+/** Ceiling for a single decoded line. A server that exceeds it is malfunctioning, not slow. */
+export const MAX_MESSAGE_LINE_BYTES = 16 * 1024 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isJsonRpcResponse(message) {
+    if (!isRecord(message) || message.jsonrpc !== "2.0")
+        return false;
+    if (!("id" in message))
+        return false;
+    const id = message.id;
+    if (typeof id !== "number" && typeof id !== "string")
+        return false;
+    return "result" in message || "error" in message;
+}
+export function isJsonRpcNotification(message) {
+    return isRecord(message) && message.jsonrpc === "2.0" && typeof message.method === "string" && !("id" in message);
+}
+export function isJsonRpcRequest(message) {
+    if (!isRecord(message) || message.jsonrpc !== "2.0")
+        return false;
+    if (typeof message.method !== "string")
+        return false;
+    const id = message.id;
+    return typeof id === "number" || typeof id === "string";
+}
+/** Serialize one message as a single stdio frame (JSON + newline). */
+export function encodeMessage(message) {
+    const line = JSON.stringify(message);
+    if (line.includes("\n")) {
+        // JSON.stringify escapes newlines, so this is unreachable for valid input;
+        // keep the guard so a future custom serializer cannot corrupt framing.
+        throw new Error("MCP frame contains a literal newline");
+    }
+    return `${line}\n`;
+}
+/**
+ * Incremental newline-delimited JSON decoder.
+ *
+ * Holds at most one partial line. A line longer than {@link MAX_MESSAGE_LINE_BYTES}
+ * is dropped with an error rather than buffered, so a runaway server cannot
+ * exhaust memory.
+ */
+export function createLineDecoder(maxLineBytes = MAX_MESSAGE_LINE_BYTES) {
+    let buffer = "";
+    let overflowed = false;
+    return {
+        push(chunk) {
+            const out = [];
+            buffer += chunk;
+            let newlineIndex = buffer.indexOf("\n");
+            while (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                if (overflowed) {
+                    // The oversized line ends here; resume clean at the next boundary.
+                    overflowed = false;
+                }
+                else if (line.length > 0) {
+                    out.push(decodeLine(line));
+                }
+                newlineIndex = buffer.indexOf("\n");
+            }
+            if (!overflowed && buffer.length > maxLineBytes) {
+                out.push({ error: `MCP frame exceeded ${maxLineBytes} bytes` });
+                overflowed = true;
+                buffer = "";
+            }
+            return out;
+        },
+        reset() {
+            buffer = "";
+            overflowed = false;
+        },
+    };
+}
+function decodeLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { error: "MCP frame is not valid JSON" };
+    }
+    if (isJsonRpcResponse(parsed) || isJsonRpcNotification(parsed) || isJsonRpcRequest(parsed)) {
+        return { message: parsed };
+    }
+    return { error: "MCP frame is not a JSON-RPC 2.0 message" };
+}
+/** Format a JSON-RPC error body for a human or a model. */
+export function formatJsonRpcError(error) {
+    const suffix = error.data === undefined ? "" : ` (${JSON.stringify(error.data)})`;
+    return `JSON-RPC error ${error.code}: ${error.message}${suffix}`;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/core/mcp/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/core/mcp/protocol.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure JSON-RPC 2.0 framing for the MCP stdio transport.\n *\n * MCP stdio frames one JSON message per line on stdout; embedded newlines are\n * illegal, so decoding is a line split with a hard length ceiling. Nothing here\n * touches a process, a socket, or a clock — the transport owns all I/O so this\n * layer stays trivially testable.\n */\n\n/** Ceiling for a single decoded line. A server that exceeds it is malfunctioning, not slow. */\nexport const MAX_MESSAGE_LINE_BYTES = 16 * 1024 * 1024;\n\nexport type JsonRpcId = number | string;\n\nexport interface JsonRpcRequest {\n\treadonly jsonrpc: \"2.0\";\n\treadonly id: JsonRpcId;\n\treadonly method: string;\n\treadonly params?: unknown;\n}\n\nexport interface JsonRpcNotification {\n\treadonly jsonrpc: \"2.0\";\n\treadonly method: string;\n\treadonly params?: unknown;\n}\n\nexport interface JsonRpcErrorBody {\n\treadonly code: number;\n\treadonly message: string;\n\treadonly data?: unknown;\n}\n\nexport interface JsonRpcResponse {\n\treadonly jsonrpc: \"2.0\";\n\treadonly id: JsonRpcId;\n\treadonly result?: unknown;\n\treadonly error?: JsonRpcErrorBody;\n}\n\nexport type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function isJsonRpcResponse(message: unknown): message is JsonRpcResponse {\n\tif (!isRecord(message) || message.jsonrpc !== \"2.0\") return false;\n\tif (!(\"id\" in message)) return false;\n\tconst id = message.id;\n\tif (typeof id !== \"number\" && typeof id !== \"string\") return false;\n\treturn \"result\" in message || \"error\" in message;\n}\n\nexport function isJsonRpcNotification(message: unknown): message is JsonRpcNotification {\n\treturn isRecord(message) && message.jsonrpc === \"2.0\" && typeof message.method === \"string\" && !(\"id\" in message);\n}\n\nexport function isJsonRpcRequest(message: unknown): message is JsonRpcRequest {\n\tif (!isRecord(message) || message.jsonrpc !== \"2.0\") return false;\n\tif (typeof message.method !== \"string\") return false;\n\tconst id = message.id;\n\treturn typeof id === \"number\" || typeof id === \"string\";\n}\n\n/** Serialize one message as a single stdio frame (JSON + newline). */\nexport function encodeMessage(message: JsonRpcMessage): string {\n\tconst line = JSON.stringify(message);\n\tif (line.includes(\"\\n\")) {\n\t\t// JSON.stringify escapes newlines, so this is unreachable for valid input;\n\t\t// keep the guard so a future custom serializer cannot corrupt framing.\n\t\tthrow new Error(\"MCP frame contains a literal newline\");\n\t}\n\treturn `${line}\\n`;\n}\n\nexport interface DecodedLine {\n\t/** Parsed message, when the line was valid JSON. */\n\treadonly message?: JsonRpcMessage;\n\t/** Why the line was dropped, when it was not usable. */\n\treadonly error?: string;\n}\n\n/**\n * Incremental newline-delimited JSON decoder.\n *\n * Holds at most one partial line. A line longer than {@link MAX_MESSAGE_LINE_BYTES}\n * is dropped with an error rather than buffered, so a runaway server cannot\n * exhaust memory.\n */\nexport function createLineDecoder(maxLineBytes: number = MAX_MESSAGE_LINE_BYTES): {\n\tpush(chunk: string): DecodedLine[];\n\treset(): void;\n} {\n\tlet buffer = \"\";\n\tlet overflowed = false;\n\n\treturn {\n\t\tpush(chunk: string): DecodedLine[] {\n\t\t\tconst out: DecodedLine[] = [];\n\t\t\tbuffer += chunk;\n\n\t\t\tlet newlineIndex = buffer.indexOf(\"\\n\");\n\t\t\twhile (newlineIndex !== -1) {\n\t\t\t\tconst line = buffer.slice(0, newlineIndex).trim();\n\t\t\t\tbuffer = buffer.slice(newlineIndex + 1);\n\t\t\t\tif (overflowed) {\n\t\t\t\t\t// The oversized line ends here; resume clean at the next boundary.\n\t\t\t\t\toverflowed = false;\n\t\t\t\t} else if (line.length > 0) {\n\t\t\t\t\tout.push(decodeLine(line));\n\t\t\t\t}\n\t\t\t\tnewlineIndex = buffer.indexOf(\"\\n\");\n\t\t\t}\n\n\t\t\tif (!overflowed && buffer.length > maxLineBytes) {\n\t\t\t\tout.push({ error: `MCP frame exceeded ${maxLineBytes} bytes` });\n\t\t\t\toverflowed = true;\n\t\t\t\tbuffer = \"\";\n\t\t\t}\n\t\t\treturn out;\n\t\t},\n\t\treset(): void {\n\t\t\tbuffer = \"\";\n\t\t\toverflowed = false;\n\t\t},\n\t};\n}\n\nfunction decodeLine(line: string): DecodedLine {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(line);\n\t} catch {\n\t\treturn { error: \"MCP frame is not valid JSON\" };\n\t}\n\tif (isJsonRpcResponse(parsed) || isJsonRpcNotification(parsed) || isJsonRpcRequest(parsed)) {\n\t\treturn { message: parsed };\n\t}\n\treturn { error: \"MCP frame is not a JSON-RPC 2.0 message\" };\n}\n\n/** Format a JSON-RPC error body for a human or a model. */\nexport function formatJsonRpcError(error: JsonRpcErrorBody): string {\n\tconst suffix = error.data === undefined ? \"\" : ` (${JSON.stringify(error.data)})`;\n\treturn `JSON-RPC error ${error.code}: ${error.message}${suffix}`;\n}\n"]}

package/dist/core/mcp/stdio-transport.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Child-process stdio transport for MCP.
+ *
+ * Owns exactly one server process: writes newline-delimited JSON to stdin,
+ * decodes stdout into messages, keeps a bounded tail of stderr for diagnostics,
+ * and reports exit exactly once. It never interprets MCP semantics — that is
+ * the client's job.
+ *
+ * Every configured OMK MCP server uses a `command`, so stdio is the whole
+ * transport surface today. HTTP servers would get a sibling module rather than
+ * a flag on this one.
+ */
+import { type JsonRpcMessage } from "./protocol.ts";
+/** How much stderr tail to keep per server for error reporting. */
+export declare const MAX_STDERR_TAIL_CHARS = 8192;
+/** Grace period between SIGTERM and SIGKILL on close. */
+export declare const DEFAULT_KILL_GRACE_MS = 2000;
+export interface StdioTransportOptions {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    readonly cwd?: string;
+    /** Grace period before SIGKILL. */
+    readonly killGraceMs?: number;
+    /** Inherit the parent environment. Default `true`. */
+    readonly inheritEnv?: boolean;
+}
+export interface StdioTransportHandlers {
+    readonly onMessage: (message: JsonRpcMessage) => void;
+    /** Malformed frames are surfaced, never silently dropped. */
+    readonly onDecodeError?: (reason: string) => void;
+    /** Called at most once, with the exit code or signal. */
+    readonly onExit: (info: {
+        readonly code: number | null;
+        readonly signal: string | null;
+    }) => void;
+}
+export declare class McpStdioTransport {
+    private child;
+    private readonly decoder;
+    private readonly killGraceMs;
+    private stderrTail;
+    private exited;
+    private killTimer;
+    private readonly options;
+    private readonly handlers;
+    constructor(options: StdioTransportOptions, handlers: StdioTransportHandlers);
+    /** Bounded tail of the server's stderr. Empty when the server has been quiet. */
+    get stderr(): string;
+    get running(): boolean;
+    /**
+     * Spawn the server process. Throws synchronously only on an invalid
+     * configuration; a spawn failure surfaces through `onExit`, so callers have
+     * one failure path instead of two.
+     */
+    start(): void;
+    /** Write one message. Returns `false` when the server is no longer writable. */
+    send(message: JsonRpcMessage): boolean;
+    /** Terminate the server: SIGTERM, then SIGKILL after the grace period. */
+    close(): void;
+    private settleExit;
+}
+//# sourceMappingURL=stdio-transport.d.ts.map

package/dist/core/mcp/stdio-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-transport.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/stdio-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAEtF,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IACtD,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,CAAC;CAClG;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,KAAK,CAA6C;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAElD,YAAY,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,sBAAsB,EAI3E;IAED,iFAAiF;IACjF,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI,CA+BZ;IAED,gFAAgF;IAChF,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CASrC;IAED,0EAA0E;IAC1E,KAAK,IAAI,IAAI,CAuBZ;IAED,OAAO,CAAC,UAAU;CAUlB","sourcesContent":["/**\n * Child-process stdio transport for MCP.\n *\n * Owns exactly one server process: writes newline-delimited JSON to stdin,\n * decodes stdout into messages, keeps a bounded tail of stderr for diagnostics,\n * and reports exit exactly once. It never interprets MCP semantics — that is\n * the client's job.\n *\n * Every configured OMK MCP server uses a `command`, so stdio is the whole\n * transport surface today. HTTP servers would get a sibling module rather than\n * a flag on this one.\n */\n\nimport type { ChildProcessWithoutNullStreams } from \"node:child_process\";\nimport spawn from \"cross-spawn\";\nimport { createLineDecoder, encodeMessage, type JsonRpcMessage } from \"./protocol.ts\";\n\n/** How much stderr tail to keep per server for error reporting. */\nexport const MAX_STDERR_TAIL_CHARS = 8192;\n/** Grace period between SIGTERM and SIGKILL on close. */\nexport const DEFAULT_KILL_GRACE_MS = 2000;\n\nexport interface StdioTransportOptions {\n\treadonly command: string;\n\treadonly args?: readonly string[];\n\treadonly env?: Readonly<Record<string, string>>;\n\treadonly cwd?: string;\n\t/** Grace period before SIGKILL. */\n\treadonly killGraceMs?: number;\n\t/** Inherit the parent environment. Default `true`. */\n\treadonly inheritEnv?: boolean;\n}\n\nexport interface StdioTransportHandlers {\n\treadonly onMessage: (message: JsonRpcMessage) => void;\n\t/** Malformed frames are surfaced, never silently dropped. */\n\treadonly onDecodeError?: (reason: string) => void;\n\t/** Called at most once, with the exit code or signal. */\n\treadonly onExit: (info: { readonly code: number | null; readonly signal: string | null }) => void;\n}\n\nexport class McpStdioTransport {\n\tprivate child: ChildProcessWithoutNullStreams | undefined;\n\tprivate readonly decoder = createLineDecoder();\n\tprivate readonly killGraceMs: number;\n\tprivate stderrTail = \"\";\n\tprivate exited = false;\n\tprivate killTimer: ReturnType<typeof setTimeout> | undefined;\n\tprivate readonly options: StdioTransportOptions;\n\tprivate readonly handlers: StdioTransportHandlers;\n\n\tconstructor(options: StdioTransportOptions, handlers: StdioTransportHandlers) {\n\t\tthis.options = options;\n\t\tthis.handlers = handlers;\n\t\tthis.killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;\n\t}\n\n\t/** Bounded tail of the server's stderr. Empty when the server has been quiet. */\n\tget stderr(): string {\n\t\treturn this.stderrTail;\n\t}\n\n\tget running(): boolean {\n\t\treturn this.child !== undefined && !this.exited;\n\t}\n\n\t/**\n\t * Spawn the server process. Throws synchronously only on an invalid\n\t * configuration; a spawn failure surfaces through `onExit`, so callers have\n\t * one failure path instead of two.\n\t */\n\tstart(): void {\n\t\tif (this.child) throw new Error(\"MCP stdio transport already started\");\n\t\tconst env = this.options.inheritEnv === false ? { ...this.options.env } : { ...process.env, ...this.options.env };\n\t\tconst child = spawn(this.options.command, [...(this.options.args ?? [])], {\n\t\t\tcwd: this.options.cwd,\n\t\t\tenv,\n\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\twindowsHide: true,\n\t\t}) as ChildProcessWithoutNullStreams;\n\t\tthis.child = child;\n\n\t\tchild.stdout.setEncoding(\"utf8\");\n\t\tchild.stdout.on(\"data\", (chunk: string) => {\n\t\t\tfor (const decoded of this.decoder.push(chunk)) {\n\t\t\t\tif (decoded.message) this.handlers.onMessage(decoded.message);\n\t\t\t\telse if (decoded.error) this.handlers.onDecodeError?.(decoded.error);\n\t\t\t}\n\t\t});\n\n\t\tchild.stderr.setEncoding(\"utf8\");\n\t\tchild.stderr.on(\"data\", (chunk: string) => {\n\t\t\tthis.stderrTail = `${this.stderrTail}${chunk}`.slice(-MAX_STDERR_TAIL_CHARS);\n\t\t});\n\n\t\t// A stdin EPIPE after the server exits is expected, not an error worth throwing.\n\t\tchild.stdin.on(\"error\", () => {});\n\t\tchild.on(\"error\", (error: Error) => {\n\t\t\tthis.stderrTail = `${this.stderrTail}${error.message}\\n`.slice(-MAX_STDERR_TAIL_CHARS);\n\t\t\tthis.settleExit(null, null);\n\t\t});\n\t\tchild.on(\"exit\", (code, signal) => this.settleExit(code, signal));\n\t}\n\n\t/** Write one message. Returns `false` when the server is no longer writable. */\n\tsend(message: JsonRpcMessage): boolean {\n\t\tconst child = this.child;\n\t\tif (!child || this.exited || !child.stdin.writable) return false;\n\t\ttry {\n\t\t\tchild.stdin.write(encodeMessage(message));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Terminate the server: SIGTERM, then SIGKILL after the grace period. */\n\tclose(): void {\n\t\tconst child = this.child;\n\t\tif (!child || this.exited) return;\n\t\ttry {\n\t\t\tchild.stdin.end();\n\t\t} catch {\n\t\t\t// Already closed.\n\t\t}\n\t\ttry {\n\t\t\tchild.kill(\"SIGTERM\");\n\t\t} catch {\n\t\t\t// Already gone.\n\t\t}\n\t\tif (this.killTimer !== undefined) return;\n\t\tthis.killTimer = setTimeout(() => {\n\t\t\tthis.killTimer = undefined;\n\t\t\ttry {\n\t\t\t\tchild.kill(\"SIGKILL\");\n\t\t\t} catch {\n\t\t\t\t// Already gone.\n\t\t\t}\n\t\t}, this.killGraceMs);\n\t\tthis.killTimer.unref?.();\n\t}\n\n\tprivate settleExit(code: number | null, signal: string | null): void {\n\t\tif (this.exited) return;\n\t\tthis.exited = true;\n\t\tif (this.killTimer !== undefined) {\n\t\t\tclearTimeout(this.killTimer);\n\t\t\tthis.killTimer = undefined;\n\t\t}\n\t\tthis.decoder.reset();\n\t\tthis.handlers.onExit({ code, signal });\n\t}\n}\n"]}

package/dist/core/mcp/stdio-transport.js

@@ -0,0 +1,132 @@
+/**
+ * Child-process stdio transport for MCP.
+ *
+ * Owns exactly one server process: writes newline-delimited JSON to stdin,
+ * decodes stdout into messages, keeps a bounded tail of stderr for diagnostics,
+ * and reports exit exactly once. It never interprets MCP semantics — that is
+ * the client's job.
+ *
+ * Every configured OMK MCP server uses a `command`, so stdio is the whole
+ * transport surface today. HTTP servers would get a sibling module rather than
+ * a flag on this one.
+ */
+import spawn from "cross-spawn";
+import { createLineDecoder, encodeMessage } from "./protocol.js";
+/** How much stderr tail to keep per server for error reporting. */
+export const MAX_STDERR_TAIL_CHARS = 8192;
+/** Grace period between SIGTERM and SIGKILL on close. */
+export const DEFAULT_KILL_GRACE_MS = 2000;
+export class McpStdioTransport {
+    child;
+    decoder = createLineDecoder();
+    killGraceMs;
+    stderrTail = "";
+    exited = false;
+    killTimer;
+    options;
+    handlers;
+    constructor(options, handlers) {
+        this.options = options;
+        this.handlers = handlers;
+        this.killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    }
+    /** Bounded tail of the server's stderr. Empty when the server has been quiet. */
+    get stderr() {
+        return this.stderrTail;
+    }
+    get running() {
+        return this.child !== undefined && !this.exited;
+    }
+    /**
+     * Spawn the server process. Throws synchronously only on an invalid
+     * configuration; a spawn failure surfaces through `onExit`, so callers have
+     * one failure path instead of two.
+     */
+    start() {
+        if (this.child)
+            throw new Error("MCP stdio transport already started");
+        const env = this.options.inheritEnv === false ? { ...this.options.env } : { ...process.env, ...this.options.env };
+        const child = spawn(this.options.command, [...(this.options.args ?? [])], {
+            cwd: this.options.cwd,
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        this.child = child;
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            for (const decoded of this.decoder.push(chunk)) {
+                if (decoded.message)
+                    this.handlers.onMessage(decoded.message);
+                else if (decoded.error)
+                    this.handlers.onDecodeError?.(decoded.error);
+            }
+        });
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            this.stderrTail = `${this.stderrTail}${chunk}`.slice(-MAX_STDERR_TAIL_CHARS);
+        });
+        // A stdin EPIPE after the server exits is expected, not an error worth throwing.
+        child.stdin.on("error", () => { });
+        child.on("error", (error) => {
+            this.stderrTail = `${this.stderrTail}${error.message}\n`.slice(-MAX_STDERR_TAIL_CHARS);
+            this.settleExit(null, null);
+        });
+        child.on("exit", (code, signal) => this.settleExit(code, signal));
+    }
+    /** Write one message. Returns `false` when the server is no longer writable. */
+    send(message) {
+        const child = this.child;
+        if (!child || this.exited || !child.stdin.writable)
+            return false;
+        try {
+            child.stdin.write(encodeMessage(message));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Terminate the server: SIGTERM, then SIGKILL after the grace period. */
+    close() {
+        const child = this.child;
+        if (!child || this.exited)
+            return;
+        try {
+            child.stdin.end();
+        }
+        catch {
+            // Already closed.
+        }
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // Already gone.
+        }
+        if (this.killTimer !== undefined)
+            return;
+        this.killTimer = setTimeout(() => {
+            this.killTimer = undefined;
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // Already gone.
+            }
+        }, this.killGraceMs);
+        this.killTimer.unref?.();
+    }
+    settleExit(code, signal) {
+        if (this.exited)
+            return;
+        this.exited = true;
+        if (this.killTimer !== undefined) {
+            clearTimeout(this.killTimer);
+            this.killTimer = undefined;
+        }
+        this.decoder.reset();
+        this.handlers.onExit({ code, signal });
+    }
+}
+//# sourceMappingURL=stdio-transport.js.map

package/dist/core/mcp/stdio-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-transport.js","sourceRoot":"","sources":["../../../src/core/mcp/stdio-transport.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Child-process stdio transport for MCP.\n *\n * Owns exactly one server process: writes newline-delimited JSON to stdin,\n * decodes stdout into messages, keeps a bounded tail of stderr for diagnostics,\n * and reports exit exactly once. It never interprets MCP semantics — that is\n * the client's job.\n *\n * Every configured OMK MCP server uses a `command`, so stdio is the whole\n * transport surface today. HTTP servers would get a sibling module rather than\n * a flag on this one.\n */\n\nimport type { ChildProcessWithoutNullStreams } from \"node:child_process\";\nimport spawn from \"cross-spawn\";\nimport { createLineDecoder, encodeMessage, type JsonRpcMessage } from \"./protocol.ts\";\n\n/** How much stderr tail to keep per server for error reporting. */\nexport const MAX_STDERR_TAIL_CHARS = 8192;\n/** Grace period between SIGTERM and SIGKILL on close. */\nexport const DEFAULT_KILL_GRACE_MS = 2000;\n\nexport interface StdioTransportOptions {\n\treadonly command: string;\n\treadonly args?: readonly string[];\n\treadonly env?: Readonly<Record<string, string>>;\n\treadonly cwd?: string;\n\t/** Grace period before SIGKILL. */\n\treadonly killGraceMs?: number;\n\t/** Inherit the parent environment. Default `true`. */\n\treadonly inheritEnv?: boolean;\n}\n\nexport interface StdioTransportHandlers {\n\treadonly onMessage: (message: JsonRpcMessage) => void;\n\t/** Malformed frames are surfaced, never silently dropped. */\n\treadonly onDecodeError?: (reason: string) => void;\n\t/** Called at most once, with the exit code or signal. */\n\treadonly onExit: (info: { readonly code: number | null; readonly signal: string | null }) => void;\n}\n\nexport class McpStdioTransport {\n\tprivate child: ChildProcessWithoutNullStreams | undefined;\n\tprivate readonly decoder = createLineDecoder();\n\tprivate readonly killGraceMs: number;\n\tprivate stderrTail = \"\";\n\tprivate exited = false;\n\tprivate killTimer: ReturnType<typeof setTimeout> | undefined;\n\tprivate readonly options: StdioTransportOptions;\n\tprivate readonly handlers: StdioTransportHandlers;\n\n\tconstructor(options: StdioTransportOptions, handlers: StdioTransportHandlers) {\n\t\tthis.options = options;\n\t\tthis.handlers = handlers;\n\t\tthis.killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;\n\t}\n\n\t/** Bounded tail of the server's stderr. Empty when the server has been quiet. */\n\tget stderr(): string {\n\t\treturn this.stderrTail;\n\t}\n\n\tget running(): boolean {\n\t\treturn this.child !== undefined && !this.exited;\n\t}\n\n\t/**\n\t * Spawn the server process. Throws synchronously only on an invalid\n\t * configuration; a spawn failure surfaces through `onExit`, so callers have\n\t * one failure path instead of two.\n\t */\n\tstart(): void {\n\t\tif (this.child) throw new Error(\"MCP stdio transport already started\");\n\t\tconst env = this.options.inheritEnv === false ? { ...this.options.env } : { ...process.env, ...this.options.env };\n\t\tconst child = spawn(this.options.command, [...(this.options.args ?? [])], {\n\t\t\tcwd: this.options.cwd,\n\t\t\tenv,\n\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\twindowsHide: true,\n\t\t}) as ChildProcessWithoutNullStreams;\n\t\tthis.child = child;\n\n\t\tchild.stdout.setEncoding(\"utf8\");\n\t\tchild.stdout.on(\"data\", (chunk: string) => {\n\t\t\tfor (const decoded of this.decoder.push(chunk)) {\n\t\t\t\tif (decoded.message) this.handlers.onMessage(decoded.message);\n\t\t\t\telse if (decoded.error) this.handlers.onDecodeError?.(decoded.error);\n\t\t\t}\n\t\t});\n\n\t\tchild.stderr.setEncoding(\"utf8\");\n\t\tchild.stderr.on(\"data\", (chunk: string) => {\n\t\t\tthis.stderrTail = `${this.stderrTail}${chunk}`.slice(-MAX_STDERR_TAIL_CHARS);\n\t\t});\n\n\t\t// A stdin EPIPE after the server exits is expected, not an error worth throwing.\n\t\tchild.stdin.on(\"error\", () => {});\n\t\tchild.on(\"error\", (error: Error) => {\n\t\t\tthis.stderrTail = `${this.stderrTail}${error.message}\\n`.slice(-MAX_STDERR_TAIL_CHARS);\n\t\t\tthis.settleExit(null, null);\n\t\t});\n\t\tchild.on(\"exit\", (code, signal) => this.settleExit(code, signal));\n\t}\n\n\t/** Write one message. Returns `false` when the server is no longer writable. */\n\tsend(message: JsonRpcMessage): boolean {\n\t\tconst child = this.child;\n\t\tif (!child || this.exited || !child.stdin.writable) return false;\n\t\ttry {\n\t\t\tchild.stdin.write(encodeMessage(message));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Terminate the server: SIGTERM, then SIGKILL after the grace period. */\n\tclose(): void {\n\t\tconst child = this.child;\n\t\tif (!child || this.exited) return;\n\t\ttry {\n\t\t\tchild.stdin.end();\n\t\t} catch {\n\t\t\t// Already closed.\n\t\t}\n\t\ttry {\n\t\t\tchild.kill(\"SIGTERM\");\n\t\t} catch {\n\t\t\t// Already gone.\n\t\t}\n\t\tif (this.killTimer !== undefined) return;\n\t\tthis.killTimer = setTimeout(() => {\n\t\t\tthis.killTimer = undefined;\n\t\t\ttry {\n\t\t\t\tchild.kill(\"SIGKILL\");\n\t\t\t} catch {\n\t\t\t\t// Already gone.\n\t\t\t}\n\t\t}, this.killGraceMs);\n\t\tthis.killTimer.unref?.();\n\t}\n\n\tprivate settleExit(code: number | null, signal: string | null): void {\n\t\tif (this.exited) return;\n\t\tthis.exited = true;\n\t\tif (this.killTimer !== undefined) {\n\t\t\tclearTimeout(this.killTimer);\n\t\t\tthis.killTimer = undefined;\n\t\t}\n\t\tthis.decoder.reset();\n\t\tthis.handlers.onExit({ code, signal });\n\t}\n}\n"]}