@orkestrel/mcp 0.0.18 → 0.0.19

package/dist/src/server/index.d.cts

@@ -1231,22 +1231,29 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
  *
  * @remarks
- * - **Spawns the server.** `start()` runs `node:child_process`'s `spawn(options.command,
- *   options.args, { env: options.env, stdio: ['pipe', 'pipe', 'inherit'] })` — the
- *   child's `stdin`/`stdout` are piped for the JSON-RPC channel, its `stderr` inherits
- *   the parent's (diagnostics pass through, never parsed as protocol).
- * - **Inbound (`message`).** Each `stdout` chunk is folded through the shared
- *   {@link extractLines} line-framing helper (buffering a partial trailing line
- *   across reads); every complete line is decoded and delivered via the shared
- *   {@link dispatchLines} helper — a well-formed {@link JSONRPCMessage} emits
- *   `message`, a malformed line emits `error` (§14, never throws). The child's
- *   `close` bridges to this transport's `close`.
- * - **Outbound (`send`).** `send(message)` writes one newline-terminated
- *   `JSON.stringify`d line to the child's `stdin`.
- * - **`close()`** kills the child process and fires `close` (idempotent).
+ * - **Composes `@orkestrel/process`.** `start()` builds one supervised
+ *   {@link import('@orkestrel/process/server').Process} with `writable: true`, so the child's
+ *   `stdin`/`stdout` are the JSON-RPC channel and its `stderr` is retained as bounded evidence
+ *   rather than parsed as protocol. The supervisor owns spawn, framing, and termination.
+ * - **Inbound (`message`).** Standard output is drained eagerly through the supervisor's
+ *   `readline`-framed `lines` iterable, so a multi-byte UTF-8 sequence split across two reads is
+ *   decoded whole and a final line written without a trailing newline still arrives. Each framed
+ *   line is decoded and delivered via the shared {@link dispatchLines} helper — a well-formed
+ *   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (§14, never throws).
+ * - **Outbound (`send`).** `send(message)` writes one newline-terminated `JSON.stringify`d line
+ *   through the supervisor's `send` and AWAITS its answer, so this promise settles only after the
+ *   host reports the line handled rather than the moment the write is queued. The supervisor never
+ *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, and for a write
+ *   that failed — so a `false` answer REJECTS here with the same not-connected error a transport
+ *   that was never started raises. A dead peer surfaces at the caller instead of vanishing.
+ * - **`close()`** terminates the child through the supervisor's bounded `SIGTERM` → grace →
+ *   `SIGKILL` group-kill, awaits its observed exit, tears down the supervisor, and fires `close`
+ *   once (idempotent). On a POSIX host the child leads its own process group, so the group-kill
+ *   reaches its grandchildren rather than orphaning them.
  * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
- *   fault), distinct from the emitter's own listener-error channel.
+ *   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
+ *   own listener-error channel.
  *
  * @example
  * ```ts
@@ -1273,11 +1280,11 @@ export declare class StdioClientTransport implements MCPClientTransportInterface
  * @remarks
  * - `command` — the executable to spawn (e.g. `'node'`, `'./my-mcp-server'`). REQUIRED.
  * - `args` — the command-line arguments passed to `command`; defaults to none.
- * - `env` — the environment variables for the spawned child, passed straight to
- *   `node:child_process`'s `spawn`; when OMITTED the child inherits the full
- *   `process.env` (the `spawn` default), when PROVIDED it REPLACES the inherited
- *   environment entirely (`spawn` semantics) — a caller wanting to extend rather
- *   than replace spreads `process.env` into `env` themselves.
+ * - `env` — environment variable overrides MERGED over the parent `process.env` for the
+ *   spawned child (the composed `@orkestrel/process` supervisor's merge semantics): when
+ *   OMITTED the child inherits the full `process.env`, when PROVIDED each named key overrides
+ *   the inherited value while every unlisted key is still inherited. This transport cannot
+ *   REPLACE the inherited environment entirely — the supervisor always merges over the parent.
  */
 export declare interface StdioClientTransportOptions {
     readonly command: string;

package/dist/src/server/index.d.ts

@@ -1231,22 +1231,29 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
  *
  * @remarks
- * - **Spawns the server.** `start()` runs `node:child_process`'s `spawn(options.command,
- *   options.args, { env: options.env, stdio: ['pipe', 'pipe', 'inherit'] })` — the
- *   child's `stdin`/`stdout` are piped for the JSON-RPC channel, its `stderr` inherits
- *   the parent's (diagnostics pass through, never parsed as protocol).
- * - **Inbound (`message`).** Each `stdout` chunk is folded through the shared
- *   {@link extractLines} line-framing helper (buffering a partial trailing line
- *   across reads); every complete line is decoded and delivered via the shared
- *   {@link dispatchLines} helper — a well-formed {@link JSONRPCMessage} emits
- *   `message`, a malformed line emits `error` (§14, never throws). The child's
- *   `close` bridges to this transport's `close`.
- * - **Outbound (`send`).** `send(message)` writes one newline-terminated
- *   `JSON.stringify`d line to the child's `stdin`.
- * - **`close()`** kills the child process and fires `close` (idempotent).
+ * - **Composes `@orkestrel/process`.** `start()` builds one supervised
+ *   {@link import('@orkestrel/process/server').Process} with `writable: true`, so the child's
+ *   `stdin`/`stdout` are the JSON-RPC channel and its `stderr` is retained as bounded evidence
+ *   rather than parsed as protocol. The supervisor owns spawn, framing, and termination.
+ * - **Inbound (`message`).** Standard output is drained eagerly through the supervisor's
+ *   `readline`-framed `lines` iterable, so a multi-byte UTF-8 sequence split across two reads is
+ *   decoded whole and a final line written without a trailing newline still arrives. Each framed
+ *   line is decoded and delivered via the shared {@link dispatchLines} helper — a well-formed
+ *   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (§14, never throws).
+ * - **Outbound (`send`).** `send(message)` writes one newline-terminated `JSON.stringify`d line
+ *   through the supervisor's `send` and AWAITS its answer, so this promise settles only after the
+ *   host reports the line handled rather than the moment the write is queued. The supervisor never
+ *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, and for a write
+ *   that failed — so a `false` answer REJECTS here with the same not-connected error a transport
+ *   that was never started raises. A dead peer surfaces at the caller instead of vanishing.
+ * - **`close()`** terminates the child through the supervisor's bounded `SIGTERM` → grace →
+ *   `SIGKILL` group-kill, awaits its observed exit, tears down the supervisor, and fires `close`
+ *   once (idempotent). On a POSIX host the child leads its own process group, so the group-kill
+ *   reaches its grandchildren rather than orphaning them.
  * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
- *   fault), distinct from the emitter's own listener-error channel.
+ *   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
+ *   own listener-error channel.
  *
  * @example
  * ```ts
@@ -1273,11 +1280,11 @@ export declare class StdioClientTransport implements MCPClientTransportInterface
  * @remarks
  * - `command` — the executable to spawn (e.g. `'node'`, `'./my-mcp-server'`). REQUIRED.
  * - `args` — the command-line arguments passed to `command`; defaults to none.
- * - `env` — the environment variables for the spawned child, passed straight to
- *   `node:child_process`'s `spawn`; when OMITTED the child inherits the full
- *   `process.env` (the `spawn` default), when PROVIDED it REPLACES the inherited
- *   environment entirely (`spawn` semantics) — a caller wanting to extend rather
- *   than replace spreads `process.env` into `env` themselves.
+ * - `env` — environment variable overrides MERGED over the parent `process.env` for the
+ *   spawned child (the composed `@orkestrel/process` supervisor's merge semantics): when
+ *   OMITTED the child inherits the full `process.env`, when PROVIDED each named key overrides
+ *   the inherited value while every unlisted key is still inherited. This transport cannot
+ *   REPLACE the inherited environment entirely — the supervisor always merges over the parent.
  */
 export declare interface StdioClientTransportOptions {
     readonly command: string;

package/dist/src/server/index.js

@@ -7,7 +7,8 @@ import { randomBytes } from "node:crypto";
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
 import { WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
-import { spawn } from "node:child_process";
+import { Process } from "@orkestrel/process/server";
+import { PROCESS_GRACE } from "@orkestrel/process";
 //#region src/server/constants.ts
 /**
 * The Streamable-HTTP transport header that carries the MCP session id. When a {@link
@@ -1296,22 +1297,29 @@ var WebSocketClientTransport = class {
 * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
 *
 * @remarks
-* - **Spawns the server.** `start()` runs `node:child_process`'s `spawn(options.command,
-*   options.args, { env: options.env, stdio: ['pipe', 'pipe', 'inherit'] })` — the
-*   child's `stdin`/`stdout` are piped for the JSON-RPC channel, its `stderr` inherits
-*   the parent's (diagnostics pass through, never parsed as protocol).
-* - **Inbound (`message`).** Each `stdout` chunk is folded through the shared
-*   {@link extractLines} line-framing helper (buffering a partial trailing line
-*   across reads); every complete line is decoded and delivered via the shared
-*   {@link dispatchLines} helper — a well-formed {@link JSONRPCMessage} emits
-*   `message`, a malformed line emits `error` (§14, never throws). The child's
-*   `close` bridges to this transport's `close`.
-* - **Outbound (`send`).** `send(message)` writes one newline-terminated
-*   `JSON.stringify`d line to the child's `stdin`.
-* - **`close()`** kills the child process and fires `close` (idempotent).
+* - **Composes `@orkestrel/process`.** `start()` builds one supervised
+*   {@link import('@orkestrel/process/server').Process} with `writable: true`, so the child's
+*   `stdin`/`stdout` are the JSON-RPC channel and its `stderr` is retained as bounded evidence
+*   rather than parsed as protocol. The supervisor owns spawn, framing, and termination.
+* - **Inbound (`message`).** Standard output is drained eagerly through the supervisor's
+*   `readline`-framed `lines` iterable, so a multi-byte UTF-8 sequence split across two reads is
+*   decoded whole and a final line written without a trailing newline still arrives. Each framed
+*   line is decoded and delivered via the shared {@link dispatchLines} helper — a well-formed
+*   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (§14, never throws).
+* - **Outbound (`send`).** `send(message)` writes one newline-terminated `JSON.stringify`d line
+*   through the supervisor's `send` and AWAITS its answer, so this promise settles only after the
+*   host reports the line handled rather than the moment the write is queued. The supervisor never
+*   rejects — it answers `false` for a channel that was closed, destroyed, or ended, and for a write
+*   that failed — so a `false` answer REJECTS here with the same not-connected error a transport
+*   that was never started raises. A dead peer surfaces at the caller instead of vanishing.
+* - **`close()`** terminates the child through the supervisor's bounded `SIGTERM` → grace →
+*   `SIGKILL` group-kill, awaits its observed exit, tears down the supervisor, and fires `close`
+*   once (idempotent). On a POSIX host the child leads its own process group, so the group-kill
+*   reaches its grandchildren rather than orphaning them.
 * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
 *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
-*   fault), distinct from the emitter's own listener-error channel.
+*   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
+*   own listener-error channel.
 *
 * @example
 * ```ts
@@ -1325,8 +1333,7 @@ var StdioClientTransport = class {
 	#command;
 	#args;
 	#env;
-	#child = void 0;
-	#buffer = "";
+	#process = void 0;
 	#closed = false;
 	constructor(options) {
 		this.#emitter = new Emitter();
@@ -1342,44 +1349,45 @@ var StdioClientTransport = class {
 		return true;
 	}
 	async start() {
-		if (this.#child !== void 0) return;
+		if (this.#process !== void 0) return;
 		this.#closed = false;
-		this.#buffer = "";
-		const child = spawn(this.#command, [...this.#args], {
-			env: this.#env,
-			stdio: [
-				"pipe",
-				"pipe",
-				"inherit"
-			]
+		const child = new Process({
+			command: {
+				file: this.#command,
+				arguments: [...this.#args],
+				...this.#env === void 0 ? {} : { environment: this.#env }
+			},
+			workspace: process.cwd(),
+			grace: PROCESS_GRACE,
+			writable: true
 		});
-		this.#child = child;
-		child.stdout.on("data", (chunk) => this.#receive(chunk.toString()));
-		child.on("close", () => this.#onClose(child));
-		child.on("error", (error) => this.#emitter.emit("error", error));
+		this.#process = child;
+		child.emitter.on("error", (cause) => this.#emitter.emit("error", cause));
+		child.exit.then(() => this.#onExit(child));
+		this.#pump(child);
 	}
 	async send(message) {
-		const child = this.#child;
-		if (child === void 0) throw new Error("stdio transport is not connected");
-		child.stdin.write(`${JSON.stringify(message)}\n`);
+		const child = this.#process;
+		if (!(child === void 0 ? false : await child.send(JSON.stringify(message)))) throw new Error("stdio transport is not connected");
 	}
 	async close() {
 		if (this.#closed) return;
 		this.#closed = true;
-		const child = this.#child;
-		this.#child = void 0;
-		if (child !== void 0) child.kill();
+		const child = this.#process;
+		this.#process = void 0;
+		if (child !== void 0) await child.destroy();
 		this.#emitter.emit("close");
 	}
-	#receive(chunk) {
-		const { lines, remainder } = extractLines(this.#buffer, chunk);
-		this.#buffer = remainder;
-		dispatchLines(this.#emitter, lines);
+	async #pump(child) {
+		for await (const line of child.lines) {
+			if (this.#process !== child) return;
+			dispatchLines(this.#emitter, [line]);
+		}
 	}
-	#onClose(child) {
-		if (this.#closed || this.#child !== child) return;
+	#onExit(child) {
+		if (this.#closed || this.#process !== child) return;
 		this.#closed = true;
-		this.#child = void 0;
+		this.#process = void 0;
 		this.#emitter.emit("close");
 	}
 };