@orkestrel/mcp 0.0.35 → 0.0.37

package/dist/src/server/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_process = require("@orkestrel/process");
 let _src_core = require("../core/index.cjs");
 let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_server = require("@orkestrel/server");
@@ -7,10 +8,19 @@ let _orkestrel_websocket = require("@orkestrel/websocket");
 let node_crypto = require("node:crypto");
 let node_http = require("node:http");
 let node_https = require("node:https");
+let node_readline = require("node:readline");
 let _orkestrel_process_server = require("@orkestrel/process/server");
-let _orkestrel_process = require("@orkestrel/process");
 let node_stream = require("node:stream");
 //#region src/server/constants.ts
+/**
+* Sets the bound in milliseconds for a stdio server to exit after the client ends its input.
+*
+* @remarks
+* Gives EOF cleanup half the process supervisor's 5,000 ms signal grace before escalation gets
+* its existing full window. This bounds the MCP lifecycle's reasonable-time wait without spending
+* another full signal grace before termination. Pending input flushes share this bound.
+*/
+var MCP_STDIO_GRACE = _orkestrel_process.PROCESS_GRACE / 2;
 /** Names the reverse-proxy response header controlling buffering of an SSE response. */
 var SSE_BUFFERING_HEADER = "x-accel-buffering";
 /** Names the `X-Accel-Buffering` value that disables reverse-proxy buffering. */
@@ -298,7 +308,7 @@ function writeLine(output, line) {
 * Decodes and delivers each complete newline-framed line onto a {@link
 * MCPMessageTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
 * transports run their framed lines through: the server transport frames with {@link
-* extractLines}, the client transport takes its lines from the process supervisor.
+* extractLines}, the client transport frames the supervisor's stdout with Node's `readline`.
 *
 * @remarks
 * A blank line is skipped (a stray trailing newline). Every other line runs through the
@@ -362,8 +372,8 @@ function inferHeaderTarget(request) {
 * {@link import('@orkestrel/mcp').decodeSentinel} before the comparison, so a peer that had
 * to encode its value still matches; a sentinel whose payload is invalid decodes to nothing
 * and therefore mismatches, which is how an invalid header value is refused. A legacy request
-* body requires a protocol header after initialization. Messages name the expected value but
-* never echo the client-supplied one.
+* body requires a protocol header except for `initialize` and an id-bearing legacy `ping`.
+* Messages name the expected value but never echo the client-supplied one.
 *
 * The expectation a live session supplies is a different rule over a different input, so it
 * is {@link inferSessionHeaderIssue} rather than a second arm of this one.
@@ -381,7 +391,7 @@ function inferHeaderTarget(request) {
 function inferHeaderIssue(request, invocation) {
 	const protocol = request.headers.get(_src_core.MCP_PROTOCOL_VERSION_HEADER);
 	if (!(0, _src_core.isModernRequest)(invocation)) {
-		if ((0, _src_core.isInitializeRequest)(invocation) || protocol !== null) return void 0;
+		if ((0, _src_core.isInitializeRequest)(invocation) || (0, _src_core.isPingRequest)(invocation) || protocol !== null) return void 0;
 		return {
 			header: "MCP-Protocol-Version",
 			reason: "missing",
@@ -709,8 +719,8 @@ var HTTPDisconnect = class {
 * comparison; a missing, mismatched, or invalidly encoded value returns HTTP `400` + `-32020`.
 * A protocol header naming a modern revision holds the request to that revision whatever shape
 * its body arrived in, so a body with no parsable modern `_meta` returns HTTP `400` + `-32602`.
-* Headerless `initialize` is accepted, while every other headerless request needs a live legacy
-* session to supply its pinned version. A legacy-shaped request carrying a protocol header is
+* Headerless `initialize` and id-bearing legacy `ping` are accepted; other headerless requests
+* need a live legacy session to supply its pinned version. A legacy-shaped request carrying a protocol header is
 * otherwise admitted only for a legacy revision; a revision this server does not implement
 * returns HTTP `400` + `-32022` whose `supported` names the legacy revisions this door accepts.
 * A present origin must occur in `origin.origins` unless validation is
@@ -720,6 +730,8 @@ var HTTPDisconnect = class {
 * handler through `MCPDispatchOptions.signal`. After every transport validation and immediately
 * before dispatch, the optional synchronous `caller` extractor reads front-middleware state; a
 * defined value is added to `MCPDispatchOptions`, while `undefined` is omitted.
+* For legacy `initialize`, the dispatch response is recorded as `initialization` before
+* JSON or SSE framing only when consumer state is an object with `'session' in context.state`.
 *
 * @typeParam TState - The consumer's opaque per-request route state type
 * @param mcp - The transport-agnostic MCP dispatcher to dispatch through
@@ -812,6 +824,9 @@ function createMCPPostHandler(mcp, options) {
 			queueMicrotask(() => void sendEventStream(response, stream));
 			return disconnect.bridge(stream);
 		}
+		if (era === "legacy" && invocation.method === "initialize" && (0, _orkestrel_contract.isObject)(context?.state) && "session" in context.state) {
+			if (!Reflect.set(context.state, "initialization", response)) throw new Error("MCP initialization state is not writable");
+		}
 		const status = inferStatus(response, era);
 		if (response === void 0) return new Response(null, { status });
 		if (status === 200 && streaming && acceptsEventStream(request)) {
@@ -1229,32 +1244,37 @@ var WebSocketClientTransport = class {
 *
 * @remarks
 * - **Composes `@orkestrel/process`.** `start()` builds one supervised
-*   {@link import('@orkestrel/process/server').Process} with `writable: true`, so the child's
+*   {@link import('@orkestrel/process/server').Supervisor} 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
+*   rather than parsed as protocol. The supervisor owns spawn and termination.
+* - **Inbound (`message`).** Standard output is drained eagerly through Node's `readline`,
+*   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 through the shared {@link dispatchLines} helper — a well-formed
 *   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (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
+*   through the supervisor's `deliver` 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, for a write
 *   that failed, or for one that remained unconfirmed through `delivery`. A call made without a
 *   live child rejects as not connected; a `false` answer from a live child rejects as unable to
 *   deliver. The supervisor does not disclose which cause produced that answer.
-* - **`close()`** runs the supervisor's bounded termination and teardown, then fires `close` once
-*   (idempotent). That teardown reaches the child's terminal moment, where the supervisor freezes
-*   `evidence`, ends `lines`, and settles `exit` together, so this transport needs no release of
-*   its own to get its line pump back: the stream ends under the pump rather than throwing at it.
-*   A line the supervisor had already framed behind the one being delivered is dropped rather than
+* - **`close()`** ends the child's input and waits up to {@link MCP_STDIO_GRACE} for native exit,
+*   including any pending input flush. Only after that wait does the supervisor terminate a child
+*   that remains alive. Teardown freezes `evidence`, closes the reader, and settles `exit`, then
+*   fires `close` once (idempotent).
+*   A child that exits on input end within the grace receives no termination signal, so it must
+*   end its own child processes on input end; only escalation reaches its process tree.
+*   If an `MCPClient` request `timeout` is shorter than the grace and the close outlasts that
+*   timeout, `disconnect()` rejects with `MCP transport close timed out after <timeout>ms`.
+*   The close keeps running, and a later caller joins it while it remains pending.
+*   A line already framed behind the one being delivered is dropped rather than
 *   emitted onto a transport whose teardown has begun. A `close()` issued while that teardown runs
 *   joins it rather than opening a second one, so it resolves only after `close` has fired, and a
 *   `start()` issued while it runs waits behind the same barrier, so lifetimes never overlap. A
 *   descendant can retain an inherited stdout pipe after the child exits; the supervisor's `drain`
-*   bound cuts that wait off, so this transport's `close()` settles within that bound rather than
-*   on the descendant. The termination itself belongs to the host: a POSIX host signals the
+*   bound cuts that wait off independently of the input grace. Escalation belongs to the host:
+*   a POSIX host signals the
 *   child's own process group `SIGTERM`, waits the grace window, then `SIGKILL`s through the same
 *   route, so the kill reaches grandchildren rather than orphaning them, while Windows ends the
 *   tree with `taskkill /F /T`, which nothing in the child can intercept.
@@ -1316,7 +1336,7 @@ var StdioClientTransport = class {
 		}
 		if (this.#process !== void 0 && !this.#closed) return;
 		this.#closed = false;
-		const child = new _orkestrel_process_server.Process({
+		const child = new _orkestrel_process_server.Supervisor({
 			command: {
 				file: this.#command,
 				arguments: [...this.#args],
@@ -1326,11 +1346,23 @@ var StdioClientTransport = class {
 			grace: _orkestrel_process.PROCESS_GRACE,
 			delivery: this.#delivery,
 			writable: true
+		}, {
+			chunk: () => void 0,
+			fault: (cause) => this.#emitter.emit("error", cause),
+			close: () => reader.close(),
+			terminal: () => void 0,
+			teardown: () => reader.close()
+		});
+		const reader = (0, node_readline.createInterface)({
+			input: child.stdout,
+			crlfDelay: Infinity
 		});
 		this.#process = child;
-		child.emitter.on("error", (cause) => this.#emitter.emit("error", cause));
+		reader.on("line", (line) => {
+			if (this.#closed || this.#process !== child) return;
+			dispatchLines(this.#emitter, [line]);
+		});
 		child.exit.then((exit) => this.#onExit(child, exit));
-		this.#pump(child);
 	}
 	/**
 	* Sends one newline-delimited JSON-RPC message to the live child.
@@ -1345,7 +1377,7 @@ var StdioClientTransport = class {
 	async send(message) {
 		const child = this.#closed ? void 0 : this.#process;
 		if (child === void 0) throw new Error("stdio transport is not connected");
-		if (!await child.send(JSON.stringify(message))) throw new Error("stdio transport could not deliver the message");
+		if (!await child.deliver(Buffer.from(`${JSON.stringify(message)}\n`, "utf8"))) throw new Error("stdio transport could not deliver the message");
 	}
 	async close() {
 		if (this.#closed && this.#closing === void 0) return;
@@ -1357,17 +1389,19 @@ var StdioClientTransport = class {
 		this.#closed = true;
 		const child = this.#process;
 		if (child !== void 0) {
+			const expired = Promise.withResolvers();
+			const timer = setTimeout(expired.resolve, MCP_STDIO_GRACE);
+			try {
+				child.end();
+				await Promise.race([child.ending, expired.promise]);
+			} finally {
+				clearTimeout(timer);
+			}
 			await child.destroy();
 			this.#report(await child.exit);
 		}
 		this.#emitter.emit("close");
 	}
-	async #pump(child) {
-		for await (const line of child.lines) {
-			if (this.#closed || this.#process !== child) return;
-			dispatchLines(this.#emitter, [line]);
-		}
-	}
 	#onExit(child, exit) {
 		if (this.#process !== child) return;
 		if (this.#closed) return;
@@ -1945,14 +1979,20 @@ function createStdioServer(mcp, options) {
 *   readSessionHeader}: a valid id touches the entry and sets `context.state.session`; an
 *   absent / unknown id whose (guarded) body parses to an `initialize` request ({@link
 *   isInitializeRequest}) mints a fresh {@link MCPSession} (`crypto.randomUUID()`, the `session`
-*   options group) and sets `context.state.session`; neither → {@link rejectUnknownSession}
+*   options group) and sets `context.state.session`. An id-bearing legacy `ping` with no
+*   session header passes through without session state, a supplied protocol header, or a
+*   response stamp. Other unresolved requests → {@link rejectUnknownSession}
 *   (`404`). The
 *   minted entry pins the negotiated legacy revision, which is supplied to a later headerless
 *   live-session request. It then
 *   forwards a fresh `Request` carrying the buffered `text` (`next(forwarded)`) — never the
 *   already-consumed original — so the route re-reads the same body, and stamps the response
-*   with {@link MCP_SESSION_HEADER}. The entry's `touched` instant is read after that
-*   downstream response, because it means the last access: a request slower than `ttl` would
+*   with {@link MCP_SESSION_HEADER}. A candidate entry is stored and advertised only when
+*   `context.state.initialization` carries a result. An `initialize` that would mint a session
+*   stores none and advertises none when refused; a live session's header is returned unchanged.
+*   The POST handler records that dispatch response before JSON or SSE framing.
+*   The entry's `touched` instant is read after the downstream response, because it
+*   means the last access: a request slower than `ttl` would
 *   otherwise store a session that is already expired, and the write-back RE-ASKS the store, so
 *   a `DELETE` arriving while the request was suspended is not undone.
 * - **`GET {path}`.** Resolves the session the same way (no mint — only `initialize` mints);
@@ -2070,7 +2110,13 @@ function createMCPSession(options) {
 					version: inferLegacyVersion(parsed)
 				};
 				entry = created;
-			} else return rejectUnknownSession();
+			} else if (id === void 0 && (0, _src_core.isPingRequest)(parsed)) return next(new Request(context.url, {
+				method: "POST",
+				headers: request.headers,
+				body: text,
+				signal: request.signal
+			}));
+			else return rejectUnknownSession();
 		}
 		if (!Reflect.set(context.state, "session", entry.session)) throw new Error("MCP session state is not writable");
 		const headers = new Headers(request.headers);
@@ -2089,7 +2135,7 @@ function createMCPSession(options) {
 			signal: request.signal
 		}));
 		if (created !== void 0) {
-			if (!response.ok) return response;
+			if (!response.ok || context.state.initialization?.result === void 0) return response;
 			store.set(created.session.id, {
 				...created,
 				touched: clock()
@@ -2110,6 +2156,7 @@ exports.DEFAULT_MCP_SESSION_CAPACITY = DEFAULT_MCP_SESSION_CAPACITY;
 exports.DEFAULT_MCP_SESSION_TTL = DEFAULT_MCP_SESSION_TTL;
 exports.HTTPDisconnect = HTTPDisconnect;
 exports.MCPSession = MCPSession;
+exports.MCP_STDIO_GRACE = MCP_STDIO_GRACE;
 exports.SSE_BUFFERING_DISABLED = SSE_BUFFERING_DISABLED;
 exports.SSE_BUFFERING_HEADER = SSE_BUFFERING_HEADER;
 exports.SSE_KEEPALIVE_COMMENT = SSE_KEEPALIVE_COMMENT;