@orkestrel/mcp 0.0.12 → 0.0.13

package/dist/src/server/index.js

@@ -1,7 +1,7 @@
 import { createSSEParser } from "@orkestrel/sse";
-import { JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, MCP_HEADER_MISMATCH, MCP_META_VERSION, MCP_MISSING_CAPABILITY, MCP_PROTOCOL_VERSION, MCP_UNSUPPORTED_VERSION, SUPPORTED_PROTOCOL_VERSIONS, bindServer, buildJSONRPCError, inferEra, inferVersion, isInitializeRequest, isJSONRPCRequest, isJSONRPCResponse, isMCPVersion, isModernRequest, parseJSONRPCMessage, parseRequestContext } from "../core/index.js";
-import { isRecord, isString } from "@orkestrel/contract";
-import { openStream } from "@orkestrel/server";
+import { JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, MCP_HEADER_MISMATCH, MCP_META_VERSION, MCP_MISSING_CAPABILITY, MCP_PROTOCOL_VERSION, MCP_UNSUPPORTED_VERSION, SUPPORTED_PROTOCOL_VERSIONS, bindServer, buildJSONRPCError, inferEra, inferRequestVersion, inferVersion, isInitializeRequest, isJSONRPCInvocation, isJSONRPCResponse, isMCPVersion, isModernRequest, parseJSONRPCMessage, parseRequestContext } from "../core/index.js";
+import { isRecord, isString, sanitizeBudget } from "@orkestrel/contract";
+import { openStream, signToken, verifyToken } from "@orkestrel/server";
 import { Emitter } from "@orkestrel/emitter";
 import { randomBytes } from "node:crypto";
 import { request } from "node:http";
@@ -98,6 +98,55 @@ function createReadableStream(pull, cancel) {
 	});
 }
 /**
+* Pump a controlled held-open exchange onto an open SSE stream — one `data:` event per
+* notification in order, then the terminating response — and END the exchange however the
+* pump leaves.
+*
+* @remarks
+* The Streamable-HTTP twin of {@link import('@src/core').sendStream}, and it owns exactly what
+* that owns. The `finally` releases the exchange on EVERY exit — the normal terminal, a
+* producer that threw, a `write` that threw, and an abort alike — because nothing else will:
+* a request whose client vanished cancels nothing by itself, so an exchange this pump walks
+* away from keeps its producer, its request lifetime, and its live subscription slot forever.
+* The exchange is released BEFORE the body ends, so the slot is already back when the response
+* completes.
+*
+* Total (§14) — never throws and never rejects. A held-open SSE response has already sent its
+* headers and part of its body, so there is no failure the transport could still convert into
+* a different answer; the honest end of a broken stream is a closed one, and the fault itself
+* is already legible on `server.emitter`'s `error` event, which is where a contained fault
+* belongs.
+*
+* @param stream - The controlled held-open answer to write out and then end
+* @param sse - The open SSE stream to write each serialized message onto
+* @returns Resolves once the exchange has ended and the SSE body has been closed
+*
+* @example
+* ```ts
+* const answer = await mcp.dispatch(invocation, { signal: disconnect.signal })
+* if (answer !== undefined && Symbol.asyncIterator in answer) {
+* 	const sse = openStream()
+* 	queueMicrotask(() => void sendEventStream(answer, sse))
+* }
+* ```
+*/
+async function sendEventStream(stream, sse) {
+	try {
+		try {
+			let next = await stream.next();
+			while (next.done !== true) {
+				sse.write({ data: JSON.stringify(next.value) });
+				next = await stream.next();
+			}
+			sse.write({ data: JSON.stringify(next.value) });
+		} finally {
+			await stream[Symbol.asyncDispose]();
+		}
+	} catch {} finally {
+		sse.end();
+	}
+}
+/**
 * Whether the request's `Accept` header opts into a Server-Sent-Events response.
 *
 * @remarks
@@ -184,9 +233,9 @@ function readLastEventId(request) {
 * JSON-RPC error body.
 *
 * @remarks
-* Returns `Response.json(buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, 'Session not found'),
-* { status: 404 })`, mirroring `createMCPRoutes`'s `400` transport-failure shape (a
-* JSON-RPC error BODY with a `null` id) but at the session-not-found status. Shared by
+* Returns `Response.json(buildJSONRPCError(undefined, JSONRPC_INVALID_REQUEST, 'Session not
+* found'), { status: 404 })`, mirroring `createMCPRoutes`'s `400` transport-failure shape (a
+* JSON-RPC error BODY with NO id) but at the session-not-found status. Shared by
 * every {@link import('./middlewares.js').createMCPSession} validation site — the
 * non-`initialize` `POST` path, the resumable `GET {path}` open, and the `DELETE {path}`
 * session-end (each a missing / unknown / TTL-evicted id) — so the single `404` envelope
@@ -195,7 +244,7 @@ function readLastEventId(request) {
 * @returns The `404` JSON-RPC error `Response`
 */
 function rejectUnknownSession() {
-	return Response.json(buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, "Session not found"), { status: 404 });
+	return Response.json(buildJSONRPCError(void 0, JSONRPC_INVALID_REQUEST, "Session not found"), { status: 404 });
 }
 /**
 * Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
@@ -302,7 +351,7 @@ function extractLines(buffer, chunk) {
 }
 /**
 * Decode and deliver each complete newline-framed line onto a {@link
-* ClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
+* MCPClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
 * transports (client and server) run their {@link extractLines} output through.
 *
 * @remarks
@@ -327,7 +376,7 @@ function dispatchLines(emitter, lines) {
 	}
 }
 /**
-* Bridge a message-channel {@link ClientTransportInterface} (the shape the stdio and
+* Bridge a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
 * WebSocket SERVER transports already implement) into the environment-agnostic
 * {@link import('@src/core').MCPTransportInterface} port — the adapter
 * {@link import('./factories.js').createStdioServer} and {@link
@@ -339,11 +388,22 @@ function dispatchLines(emitter, lines) {
 * `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
 * and writes it via `transport.send` (the SAME `JSON.stringify` the underlying
 * transport already performs, so the wire bytes are unchanged). `listen` filters
-* `transport`'s `message` event to REQUESTS ONLY — a stray response is ignored,
-* exactly as the prior hand-rolled pumps did — and re-serializes each one back to a
-* string for `bindServer`. `closed` bridges `transport`'s `close` event. `close`
+* `transport`'s `message` event to INVOCATIONS ONLY — requests and notifications, never a
+* stray response, exactly as the prior hand-rolled pumps did — and re-serializes each one
+* back to a string for `bindServer`. `closed` bridges `transport`'s `close` event. `close`
 * closes the underlying `transport`.
 *
+* @remarks A message crossing this bridge is decoded and re-encoded TWICE, and that is
+* ACCEPTED rather than accidental. Inbound: the carrier already parsed the frame into a
+* {@link JSONRPCMessage}, and `listen` re-serializes it so `bindServer` can decode it again
+* under the server's own `limit`. Outbound: `bindServer` serialized the reply, `send` parses
+* it back, and the carrier stringifies it once more. The cost is two extra `JSON.parse` /
+* `JSON.stringify` round trips per message, paid to keep ONE pump in the core binder instead
+* of a hand-rolled one per carrier. It is BOUNDED rather than unbounded because the binder
+* decodes within `server.limit.message`, so an oversized frame is refused before the second
+* decode rather than after it. Removing the cost means giving `MCPTransportInterface` a
+* message-shaped face beside its string one, which every transport would then carry.
+*
 * @remarks Per {@link import('@src/core').MCPTransportInterface}, `listen`/`closed`
 * each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
 * Since the underlying `transport.emitter` is ADD-based (`on` subscribes, never
@@ -371,7 +431,7 @@ function bridgeMessageTransport(transport) {
 	let onMessage;
 	let onClosed;
 	transport.emitter.on("message", (message) => {
-		if (!isJSONRPCRequest(message)) return;
+		if (!isJSONRPCInvocation(message)) return;
 		onMessage?.(JSON.stringify(message));
 	});
 	transport.emitter.on("close", () => {
@@ -406,7 +466,7 @@ function bridgeMessageTransport(transport) {
 * the active session. Messages name the expected value but never echo the client-supplied one.
 *
 * @param request - The HTTP request carrying the headers
-* @param reference - The parsed request body, or the active legacy session version
+* @param reference - The parsed invocation body, or the active legacy session version
 * @returns The first header issue, or `undefined` when the applicable headers agree
 *
 * @example
@@ -484,7 +544,7 @@ function inferHeaderIssue(request, reference) {
 * A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
 * request selects the newest supported legacy revision, matching the core initialize result.
 *
-* @param request - The legacy initialize request
+* @param request - The legacy initialize invocation
 * @returns The negotiated legacy protocol revision
 */
 function inferLegacyVersion(request) {
@@ -516,35 +576,78 @@ function inferStatus(response, era) {
 //#endregion
 //#region src/server/transports/HTTPDisconnect.ts
 /**
-* The HTTP response-disconnect bridge for an MCP SSE stream.
+* Compose one incoming HTTP request lifetime with one MCP-owned SSE response lifetime.
 *
 * @remarks
-* Composes the incoming request signal with a controller owned by the MCP HTTP face. The
-* returned {@link signal} therefore observes both an incomplete request body and cancellation
-* of the streamed response body. {@link bridge} preserves the supplied SSE response while
-* forwarding its body through a cancellation-aware stream. While that response is held open,
-* the bridge writes SSE comment frames at the configured keepalive interval so an idle dead
-* client becomes observable to the HTTP writer. It never decides how an abort changes handler
-* or session state.
+* The composed {@link signal} observes request abort and EVERY way this response can end
+* without one: consumer cancellation of the bridged body, a forwarding failure mid-pump, and a
+* keepalive tick that finds the SSE stream already closed. That last pair is the whole point of
+* the composition — a client that vanishes mid-stream aborts nothing by itself, so unless this
+* object raises the signal on its own failure paths, the handler, the controlled stream, and
+* the producer behind them all keep running for a response that can no longer be written.
+* Graceful upstream completion is the one terminal that does NOT abort: the body simply closes,
+* because the exchange finished rather than ended.
+*
+* {@link bridge} preserves the source response status and headers, forwards its body bytes, and
+* owns keepalive comments plus listener/timer cleanup until upstream completion, request abort,
+* or consumer cancellation. This is a single-response lifecycle object, not a reusable bridge.
+* It supplies no handler or session policy.
+*
+* The keepalive interval is a BUDGET, sanitized like every other numeric knob in this package:
+* anything that is not a positive integer — `0`, a negative, a fractional value, `NaN`,
+* `Infinity` — falls back to {@link DEFAULT_MCP_KEEPALIVE_INTERVAL}, and a larger value clamps
+* to Node's `2_147_483_647` ms timer maximum. None may reach the platform's timer floor, where
+* an idle-liveness tick becomes the polling this package forbids everywhere else.
+*
+* @example
+* ```ts
+* import { HTTPDisconnect } from '@orkestrel/mcp/server'
+* import { openStream } from '@orkestrel/server'
+*
+* const disconnect = new HTTPDisconnect(request.signal, { interval: 15_000 })
+* const stream = openStream()
+* const response = disconnect.bridge(stream)
+* ```
 */
 var HTTPDisconnect = class {
-	#abort = new AbortController();
+	#response = new AbortController();
 	#lifecycle = new AbortController();
 	#interval;
 	#signal;
 	#timer;
+	#pulling = false;
+	/**
+	* Create the lifecycle composition for one request and its future SSE response.
+	*
+	* @param signal - The incoming request signal
+	* @param options - Optional keepalive `interval` in milliseconds; an invalid value falls back
+	*   to {@link DEFAULT_MCP_KEEPALIVE_INTERVAL}, and one above Node's timer maximum clamps to it
+	*/
 	constructor(signal, options) {
-		this.#interval = options?.interval ?? 15e3;
-		this.#signal = AbortSignal.any([signal, this.#abort.signal]);
+		const interval = sanitizeBudget(options?.interval, DEFAULT_MCP_KEEPALIVE_INTERVAL);
+		this.#interval = interval > 0 ? Math.min(interval, 2147483647) : DEFAULT_MCP_KEEPALIVE_INTERVAL;
+		this.#signal = AbortSignal.any([signal, this.#response.signal]);
 	}
+	/**
+	* The signal aborted by the incoming request, or by any end of this response that is not
+	* its graceful completion.
+	*
+	* @returns The composed lifecycle signal
+	*/
 	get signal() {
 		return this.#signal;
 	}
 	/**
-	* Bridge cancellation of an SSE response body into this disconnect signal.
+	* Bridge one open SSE response through cancellation-aware byte forwarding and keepalives.
+	*
+	* Consumer cancellation, a read failure while forwarding, and a keepalive tick that finds the
+	* SSE stream already closed each abort {@link signal}; consumer cancellation also cancels the
+	* upstream reader. Upstream completion closes the returned body without inventing an abort.
+	* Every terminal path clears the keepalive timer and detaches the bridge-owned abort listener.
 	*
 	* @param stream - The open SSE stream whose response will be consumed by the HTTP writer
-	* @returns A response with the same status and headers whose body forwards the SSE bytes
+	* @returns A one-use response preserving status, status text, headers, and SSE body bytes
+	* @throws When the supplied SSE response has no body
 	*/
 	bridge(stream) {
 		const response = stream.response;
@@ -552,28 +655,32 @@ var HTTPDisconnect = class {
 		if (body === null) throw new Error("MCP SSE response has no body");
 		const reader = body.getReader();
 		this.#timer = setInterval(() => {
-			if (stream.closed) this.#stop();
-			else stream.comment(SSE_KEEPALIVE_COMMENT);
+			if (stream.closed) {
+				if (!this.#pulling) this.#abort();
+			} else stream.comment(SSE_KEEPALIVE_COMMENT);
 		}, this.#interval);
-		this.#signal.addEventListener("abort", () => this.#stop(), {
+		this.#signal.addEventListener("abort", () => this.#release(), {
 			once: true,
 			signal: this.#lifecycle.signal
 		});
-		if (this.#signal.aborted || stream.closed) this.#stop();
+		if (this.#signal.aborted) this.#release();
+		else if (stream.closed) this.#abort();
 		return new Response(createReadableStream(async (controller) => {
+			this.#pulling = true;
 			try {
 				const chunk = await reader.read();
 				if (chunk.done) {
-					this.#stop();
+					this.#release();
 					controller.close();
 				} else controller.enqueue(chunk.value);
 			} catch (error) {
-				this.#stop();
+				this.#abort();
 				controller.error(error);
+			} finally {
+				this.#pulling = false;
 			}
 		}, async (reason) => {
-			this.#abort.abort();
-			this.#stop();
+			this.#abort();
 			await reader.cancel(reason);
 		}), {
 			status: response.status,
@@ -581,13 +688,17 @@ var HTTPDisconnect = class {
 			headers: response.headers
 		});
 	}
-	#stop() {
+	#release() {
 		if (this.#timer !== void 0) {
 			clearInterval(this.#timer);
 			this.#timer = void 0;
 		}
 		this.#lifecycle.abort();
 	}
+	#abort() {
+		this.#release();
+		this.#response.abort();
+	}
 };
 //#endregion
 //#region src/server/handlers.ts
@@ -607,18 +718,18 @@ var HTTPDisconnect = class {
 * defined value is added to `MCPDispatchOptions`, while `undefined` is omitted.
 *
 * @typeParam TState - The consumer's opaque per-request route state type
-* @param mcp - The transport-agnostic MCP server to dispatch through
+* @param mcp - The transport-agnostic MCP dispatcher to dispatch through
 * @param options - Optional streaming, origin-validation, SSE keepalive, and caller-extraction options
 * @returns A request handler for the stateless MCP POST route
 *
 * @example
 * ```ts
-* import { createMCPServer } from '@orkestrel/mcp'
+* import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
 * import { createMCPPostHandler } from '@orkestrel/mcp/server'
 * import { createToolManager } from '@orkestrel/tool'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
-* const handler = createMCPPostHandler(mcp, { streaming: true })
+* const handler = createMCPPostHandler(createMCPLegacy(mcp), { streaming: true })
 * await handler(new Request('http://localhost/mcp', {
 * 	method: 'POST',
 * 	body: '{"jsonrpc":"2.0","method":"ping","id":1}',
@@ -634,23 +745,23 @@ function createMCPPostHandler(mcp, options) {
 		try {
 			text = await request.text();
 		} catch {
-			return Response.json(buildJSONRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
+			return Response.json(buildJSONRPCError(void 0, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
 		}
 		let parsed;
 		try {
 			parsed = JSON.parse(text);
 		} catch {
-			return Response.json(buildJSONRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
+			return Response.json(buildJSONRPCError(void 0, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
 		}
-		const rpcRequest = parseJSONRPCMessage(parsed);
-		if (rpcRequest === void 0 || !("method" in rpcRequest)) return Response.json(buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, "Invalid Request"), { status: 400 });
-		const era = isModernRequest(rpcRequest) ? "modern" : "legacy";
-		const id = rpcRequest.id ?? null;
+		const invocation = parseJSONRPCMessage(parsed);
+		if (invocation === void 0 || !("method" in invocation)) return Response.json(buildJSONRPCError(void 0, JSONRPC_INVALID_REQUEST, "Invalid Request"), { status: 400 });
+		const era = isModernRequest(invocation) ? "modern" : "legacy";
+		const id = invocation.id;
 		const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
 		if (era === "modern") {
-			if (parseRequestContext(rpcRequest) === void 0) return Response.json(buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: malformed modern request metadata"), { status: 400 });
+			if (parseRequestContext(invocation) === void 0) return Response.json(buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: malformed modern request metadata"), { status: 400 });
 		}
-		const issue = inferHeaderIssue(request, rpcRequest);
+		const issue = inferHeaderIssue(request, invocation);
 		if (issue !== void 0) return Response.json(buildJSONRPCError(id, MCP_HEADER_MISMATCH, issue.message), { status: 400 });
 		if (era === "legacy") {
 			if (protocol !== null && !isMCPVersion(protocol)) return Response.json(buildJSONRPCError(id, MCP_UNSUPPORTED_VERSION, `Unsupported MCP protocol version '${protocol}'`, {
@@ -660,25 +771,14 @@ function createMCPPostHandler(mcp, options) {
 		}
 		const disconnect = new HTTPDisconnect(request.signal, options?.keepalive);
 		const caller = options?.caller?.(request, context);
-		const response = await mcp.dispatch(rpcRequest, {
+		const response = await mcp.dispatch(invocation, {
 			signal: disconnect.signal,
 			...caller === void 0 ? {} : { caller }
 		});
 		if (response !== void 0 && Symbol.asyncIterator in response) {
 			const stream = openStream();
 			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
-			queueMicrotask(async () => {
-				try {
-					let next = await response.next();
-					while (!next.done) {
-						stream.write({ data: JSON.stringify(next.value) });
-						next = await response.next();
-					}
-					stream.write({ data: JSON.stringify(next.value) });
-				} catch {} finally {
-					stream.end();
-				}
-			});
+			queueMicrotask(() => void sendEventStream(response, stream));
 			return disconnect.bridge(stream);
 		}
 		const status = inferStatus(response, era);
@@ -697,7 +797,7 @@ function createMCPPostHandler(mcp, options) {
 //#region src/server/transports/HTTPClientTransport.ts
 /**
 * The HTTP CLIENT transport for the Model Context Protocol — a
-* {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server over
+* {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server over
 * `fetch`, the egress mirror of the server's `createMCPRoutes`.
 *
 * @remarks
@@ -730,7 +830,7 @@ function createMCPPostHandler(mcp, options) {
 * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
 *   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /
 *   decode failure surfaces on the `error` event rather than escaping `send`.
-* - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); fires
+* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
 *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
 *
 * @example
@@ -761,6 +861,9 @@ var HTTPClientTransport = class {
 	get session() {
 		return this.#session;
 	}
+	get duplex() {
+		return false;
+	}
 	async start() {}
 	async send(message) {
 		let response;
@@ -790,11 +893,11 @@ var HTTPClientTransport = class {
 		this.#emitter.emit("close");
 	}
 	#buildHeaders(message) {
-		if (isJSONRPCRequest(message) && isModernRequest(message)) {
-			const version = (isRecord(message.params?.["_meta"]) ? message.params["_meta"] : void 0)?.[MCP_META_VERSION];
+		if (isModernRequest(message)) {
+			const version = inferRequestVersion(message);
 			const name = message.params?.["name"];
 			return {
-				...isString(version) ? { [MCP_PROTOCOL_VERSION_HEADER]: version } : {},
+				...version === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: version },
 				[MCP_METHOD_HEADER]: message.method,
 				...message.method === "tools/call" && isString(name) ? { [MCP_NAME_HEADER]: name } : {}
 			};
@@ -945,12 +1048,12 @@ var MCPSession = class {
 /**
 * The per-connection JSON-RPC-over-WebSocket SERVER bridge — wraps a
 * {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
-* {@link ClientTransportInterface}, the bidirectional JSON-RPC message channel
+* {@link MCPClientTransportInterface}, the bidirectional JSON-RPC message channel
 * `createWebSocketServer` pumps `mcp.dispatch` over and the egress mirror's
 * {@link import('./WebSocketClientTransport.js').WebSocketClientTransport} reuses.
 *
 * @remarks
-* - **Reuses `ClientTransportInterface` (§21).** It IS the same generic carrier the HTTP
+* - **Reuses `MCPClientTransportInterface` (§21).** It IS the same generic carrier the HTTP
 *   client transport implements — `emitter` (`message` / `close` / `error`), `start`,
 *   `send`, `close` — so the WebSocket server and client both speak ONE transport contract,
 *   no near-duplicate sibling interface. `session` is `undefined` (the stateless v1; a
@@ -968,7 +1071,7 @@ var MCPSession = class {
 * - **`close()`** closes the underlying socket (the RFC 6455 close handshake) and fires the
 *   transport's `close` event (idempotent — a second `close`, or a socket-driven close, emits
 *   once).
-* - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the emitter
+* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the emitter
 *   isolates a listener throw (a buggy observer never corrupts the bridge). `error` is a
 *   DOMAIN event (a transport-level fault), distinct from the emitter's listener-error channel.
 */
@@ -985,6 +1088,9 @@ var WebSocketServerTransport = class {
 		return this.#emitter;
 	}
 	get session() {}
+	get duplex() {
+		return true;
+	}
 	async start() {
 		if (this.#started || this.#closed) return;
 		this.#started = true;
@@ -1026,7 +1132,7 @@ var WebSocketServerTransport = class {
 //#region src/server/transports/WebSocketClientTransport.ts
 /**
 * The WebSocket CLIENT transport for the Model Context Protocol — a
-* {@link ClientTransportInterface} that drives a REMOTE MCP server over a WebSocket, the
+* {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket, the
 * egress mirror of {@link import('./factories.js').createWebSocketServer} and the WebSocket
 * sibling of {@link import('./HTTPClientTransport.js').HTTPClientTransport}.
 *
@@ -1039,6 +1145,12 @@ var WebSocketServerTransport = class {
 *   — a mismatch (or a non-`101` response, or a request error) REJECTS `start()` and the socket
 *   is destroyed. On success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
 *   head })` (CLIENT mode — no key → frames are MASKED per §5.3) and bridges its `message`.
+* - **The arriving socket is RE-ASKED for, never assumed.** `start()` suspends across that
+*   connect and upgrade, so it re-checks the transport's state before installing anything: a
+*   concurrent `start()` that already installed a socket, or a {@link close} that ended the
+*   transport while the handshake was on the wire, both WIN — the socket that arrives late is
+*   DESTROYED and never bound, so no orphan is left re-emitting frames at nobody. Both
+*   `start()` calls still resolve; exactly one socket is ever bound.
 * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and narrowed
 *   with `parseJSONRPCMessage` — a {@link JSONRPCMessage} re-emits on this transport's `message`
 *   event (the reply the {@link import('@src/core').MCPClientInterface} correlates by `id`); a
@@ -1049,7 +1161,7 @@ var WebSocketServerTransport = class {
 * - **URL scheme.** `options.url` accepts a `ws://` / `wss://` URL or an `http://` / `https://`
 *   one; a `ws(s)` scheme is converted to `http(s)` for the underlying upgrade request (`wss`
 *   → TLS via `node:https`). Either reaches the same endpoint.
-* - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); every emit
+* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
 *   the emitter isolates a listener throw (a buggy observer never corrupts the transport);
 *   `error` is a DOMAIN event (a transport-level fault).
 *
@@ -1075,6 +1187,9 @@ var WebSocketClientTransport = class {
 		return this.#emitter;
 	}
 	get session() {}
+	get duplex() {
+		return true;
+	}
 	async start() {
 		if (this.#socket !== void 0) return;
 		this.#closed = false;
@@ -1103,6 +1218,11 @@ var WebSocketClientTransport = class {
 					reject(/* @__PURE__ */ new Error("WebSocket handshake failed: Sec-WebSocket-Accept mismatch"));
 					return;
 				}
+				if (this.#closed || this.#socket !== void 0) {
+					socket.destroy();
+					resolve();
+					return;
+				}
 				const ws = createNodeWebSocket({
 					socket,
 					head
@@ -1134,7 +1254,7 @@ var WebSocketClientTransport = class {
 	}
 	#bind(ws) {
 		ws.emitter.on("message", (text) => this.#receive(text));
-		ws.emitter.on("close", () => this.#onClose());
+		ws.emitter.on("close", () => this.#onClose(ws));
 		ws.emitter.on("error", (error) => this.#emitter.emit("error", error));
 	}
 	#receive(text) {
@@ -1152,8 +1272,8 @@ var WebSocketClientTransport = class {
 		}
 		this.#emitter.emit("message", message);
 	}
-	#onClose() {
-		if (this.#closed) return;
+	#onClose(socket) {
+		if (this.#closed || this.#socket !== socket) return;
 		this.#closed = true;
 		this.#socket = void 0;
 		this.#emitter.emit("close");
@@ -1170,7 +1290,7 @@ var WebSocketClientTransport = class {
 //#region src/server/transports/StdioClientTransport.ts
 /**
 * The stdio CLIENT transport for the Model Context Protocol — a
-* {@link ClientTransportInterface} that drives a CHILD PROCESS MCP server over
+* {@link MCPClientTransportInterface} that drives a CHILD PROCESS MCP server over
 * newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
 * import('./HTTPClientTransport.js').HTTPClientTransport} and {@link
 * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
@@ -1189,7 +1309,7 @@ var WebSocketClientTransport = class {
 * - **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).
-* - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the
+* - **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.
 *
@@ -1218,6 +1338,9 @@ var StdioClientTransport = class {
 		return this.#emitter;
 	}
 	get session() {}
+	get duplex() {
+		return true;
+	}
 	async start() {
 		if (this.#child !== void 0) return;
 		this.#closed = false;
@@ -1232,7 +1355,7 @@ var StdioClientTransport = class {
 		});
 		this.#child = child;
 		child.stdout.on("data", (chunk) => this.#receive(chunk.toString()));
-		child.on("close", () => this.#onClose());
+		child.on("close", () => this.#onClose(child));
 		child.on("error", (error) => this.#emitter.emit("error", error));
 	}
 	async send(message) {
@@ -1253,8 +1376,8 @@ var StdioClientTransport = class {
 		this.#buffer = remainder;
 		dispatchLines(this.#emitter, lines);
 	}
-	#onClose() {
-		if (this.#closed) return;
+	#onClose(child) {
+		if (this.#closed || this.#child !== child) return;
 		this.#closed = true;
 		this.#child = void 0;
 		this.#emitter.emit("close");
@@ -1265,13 +1388,13 @@ var StdioClientTransport = class {
 /**
 * The stdio SERVER transport for the Model Context Protocol — wraps an injectable
 * readable/writable stream pair (`process.stdin`/`process.stdout` in production, a
-* test double in tests) as a {@link ClientTransportInterface}, the newline-delimited
+* test double in tests) as a {@link MCPClientTransportInterface}, the newline-delimited
 * JSON-RPC channel {@link import('../factories.js').createStdioServer} pumps
 * `mcp.dispatch` over, the stdio mirror of {@link
 * import('./WebSocketServerTransport.js').WebSocketServerTransport}.
 *
 * @remarks
-* - **Reuses `ClientTransportInterface` (§21).** The same generic carrier the HTTP
+* - **Reuses `MCPClientTransportInterface` (§21).** The same generic carrier the HTTP
 *   and WebSocket server transports implement — `emitter` (`message` / `close` /
 *   `error`), `start`, `send`, `close`. `session` is `undefined` (the stateless v1).
 * - **Inbound (`message`).** `start()` subscribes to `input`'s `data` event; each
@@ -1286,7 +1409,7 @@ var StdioClientTransport = class {
 * - **`close()`** fires this transport's `close` (idempotent) — the injected streams
 *   are owned by the caller (typically `process.stdin`/`process.stdout`, which must
 *   never be closed out from under the process) and are not torn down here.
-* - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the
+* - **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.
 */
@@ -1306,6 +1429,9 @@ var StdioServerTransport = class {
 		return this.#emitter;
 	}
 	get session() {}
+	get duplex() {
+		return true;
+	}
 	async start() {
 		if (this.#started || this.#closed) return;
 		this.#started = true;
@@ -1335,8 +1461,24 @@ var StdioServerTransport = class {
 //#endregion
 //#region src/server/factories.ts
 /**
+* Adapt the installed server token primitives to the host-neutral MCP continuation port.
+*
+* @param secret - Current signing secret or `[current, ...older]` rotation list
+* @returns A continuation port that seals and opens opaque canonical state strings
+*/
+function createMCPContinuation(secret) {
+	return {
+		seal(value) {
+			return signToken(value, { secret });
+		},
+		open(value) {
+			return verifyToken(value, secret);
+		}
+	};
+}
+/**
 * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
-* {@link MCPServerInterface} (the `@src/core` dispatch core) on the fetch-standard router
+* {@link MCPDispatcherInterface} (the `@src/core` dispatch boundary) on the fetch-standard router
 * spine, pumping each `POST` body through `mcp.dispatch`. Returns the {@link RouteInput}s to
 * hand to `router.add(...)`.
 *
@@ -1347,14 +1489,14 @@ var StdioServerTransport = class {
 * DISPATCH-level outcomes:
 *
 * - A **transport** failure — a malformed JSON body, or a parsed value that is not a
-*   JSON-RPC REQUEST — is an HTTP `400` carrying a JSON-RPC error BODY (`-32700` Parse
-*   error / `-32600` Invalid Request, id `null`).
+*   JSON-RPC INVOCATION — is an HTTP `400` carrying a JSON-RPC error BODY (`-32700` Parse
+*   error / `-32600` Invalid Request), with the `id` it could not read OMITTED.
 * - Modern protocol/method/name headers are validated against the body; a mismatch is
 *   HTTP `400` + `-32020`. Headerless initialize is accepted, a live legacy session supplies
 *   its pinned revision, and every other headerless request is rejected.
 * - Legacy dispatch errors stay IN-BAND at HTTP `200`; modern errors map to `400` for
 *   `-32020` / `-32021` / `-32022` / `-32602`, `404` for `-32601`, and `200` otherwise.
-* - A **notification** (a request with no `id`, which `dispatch` resolves to
+* - A **notification** (an invocation with no `id`, which `dispatch` resolves to
 *   `undefined`) is a `202 Accepted` with no body.
 *
 * When `streaming` is enabled (the default) and the client `Accept`s `text/event-stream`,
@@ -1373,7 +1515,7 @@ var StdioServerTransport = class {
 * allowlist or explicitly delegates validation to an upstream layer.
 *
 * @typeParam TState - The consumer's opaque per-request state type
-* @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over HTTP
+* @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over HTTP
 * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `streaming`
 *   (default `true`), plus shared origin, keepalive, and synchronous caller-extraction options; see
 *   {@link HTTPTransportOptions}
@@ -1381,11 +1523,11 @@ var StdioServerTransport = class {
 *
 * @example
 * ```ts
-* import { createMCPServer, createToolManager } from '@src/core'
+* import { createMCPLegacy, createMCPServer, createToolManager } from '@src/core'
 * import { createMCPRoutes } from '@src/server'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
-* const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
+* const routes = createMCPRoutes(createMCPLegacy(mcp)) // both eras; pass `mcp` for modern only
 * ```
 */
 function createMCPRoutes(mcp, options) {
@@ -1398,7 +1540,7 @@ function createMCPRoutes(mcp, options) {
 }
 /**
 * Create the HTTP CLIENT transport for an {@link import('@src/core').MCPClientInterface}
-* — a {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
+* — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
 * over `fetch`. The egress mirror of {@link createMCPRoutes}.
 *
 * @remarks
@@ -1417,7 +1559,7 @@ function createMCPRoutes(mcp, options) {
 * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
 *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
 *   (ms, applied via `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
-* @returns A working {@link ClientTransportInterface} over `fetch`
+* @returns A working {@link MCPClientTransportInterface} over `fetch`
 *
 * @example
 * ```ts
@@ -1436,7 +1578,7 @@ function createHTTPClientTransport(options) {
 }
 /**
 * Create the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
-* transport-agnostic {@link MCPServerInterface} over a WebSocket, the WebSocket mirror of
+* transport-agnostic {@link MCPDispatcherInterface} over a WebSocket, the WebSocket mirror of
 * {@link createMCPRoutes}. Register it on the spine's upgrade seam.
 *
 * @remarks
@@ -1464,7 +1606,7 @@ function createHTTPClientTransport(options) {
 * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
 * upgrade so it never reaches this pump.
 *
-* @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over WebSocket
+* @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over WebSocket
 * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
 *   (default {@link MCP_WEBSOCKET_SUBPROTOCOL}); see {@link WebSocketServerOptions}
 * @returns An {@link UpgradeHandler} to register with the spine's `upgrade` seam
@@ -1502,7 +1644,7 @@ function createWebSocketServer(mcp, options) {
 }
 /**
 * Create the WebSocket CLIENT transport for an {@link import('@src/core').MCPClientInterface}
-* — a {@link ClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
+* — a {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
 * egress mirror of {@link createWebSocketServer} and the WebSocket sibling of {@link
 * createHTTPClientTransport}.
 *
@@ -1518,7 +1660,7 @@ function createWebSocketServer(mcp, options) {
 *
 * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional `headers`
 *   merged onto the upgrade request; see {@link WebSocketClientTransportOptions}
-* @returns A working {@link ClientTransportInterface} over a WebSocket
+* @returns A working {@link MCPClientTransportInterface} over a WebSocket
 *
 * @example
 * ```ts
@@ -1537,7 +1679,7 @@ function createWebSocketClientTransport(options) {
 }
 /**
 * Create the stdio CLIENT transport for an {@link import('@src/core').MCPClientInterface}
-* — a {@link ClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+* — a {@link MCPClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
 * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
 * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
 *
@@ -1552,7 +1694,7 @@ function createWebSocketClientTransport(options) {
 *
 * @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
 *   and optional `env`; see {@link StdioClientTransportOptions}
-* @returns A working {@link ClientTransportInterface} over a child process's stdio
+* @returns A working {@link MCPClientTransportInterface} over a child process's stdio
 *
 * @example
 * ```ts
@@ -1571,7 +1713,7 @@ function createStdioClientTransport(options) {
 }
 /**
 * Create the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
-* MCPServerInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
+* MCPDispatcherInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
 * injected stream pair), the stdio mirror of {@link createWebSocketServer}.
 *
 * @remarks
@@ -1585,7 +1727,7 @@ function createStdioClientTransport(options) {
 * surfaces on `mcp.emitter`'s `error` event rather than escaping the (async) message
 * pump.
 *
-* @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over stdio
+* @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over stdio
 * @param options - Optional injectable `input` / `output` streams; see
 *   {@link StdioServerOptions}
 * @returns A `{ start(): void; stop(): void }` handle to arm / tear down the pump
@@ -1638,7 +1780,10 @@ function createStdioServer(mcp, options) {
 *   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}.
+*   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
+*   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);
 *   an invalid / unknown id is the same `404`. A valid session opens the resumable
 *   server→client stream via `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
@@ -1740,21 +1885,23 @@ function createMCPSession(options) {
 		}
 		if (context.method !== "POST" || text === void 0) return next();
 		let created;
-		if (entry === void 0) if (parsed !== void 0 && isInitializeRequest(parsed)) {
-			created = {
-				session: new MCPSession(crypto.randomUUID(), capacity !== void 0 ? { capacity } : {}),
-				touched: clock(),
-				version: inferLegacyVersion(parsed)
-			};
-			entry = created;
-		} else return rejectUnknownSession();
+		if (entry === void 0) {
+			if (parsed !== void 0 && isInitializeRequest(parsed)) {
+				created = {
+					session: new MCPSession(crypto.randomUUID(), capacity !== void 0 ? { capacity } : {}),
+					touched: clock(),
+					version: inferLegacyVersion(parsed)
+				};
+				entry = created;
+			} 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);
 		if (parsed === void 0 || !isInitializeRequest(parsed)) {
 			const issue = inferHeaderIssue(request, entry.version);
 			if (issue?.reason === "missing") headers.set(MCP_PROTOCOL_VERSION_HEADER, entry.version);
 			else if (issue !== void 0) {
-				const requestId = parsed !== void 0 && "method" in parsed ? parsed.id ?? null : null;
+				const requestId = parsed !== void 0 && "method" in parsed ? parsed.id : void 0;
 				return Response.json(buildJSONRPCError(requestId, MCP_HEADER_MISMATCH, issue.message), { status: 400 });
 			}
 		}
@@ -1766,13 +1913,19 @@ function createMCPSession(options) {
 		}));
 		if (created !== void 0) {
 			if (!response.ok) return response;
-			store.set(created.session.id, created);
-		}
+			store.set(created.session.id, {
+				...created,
+				touched: clock()
+			});
+		} else if (store.get(entry.session.id) === entry) store.set(entry.session.id, {
+			...entry,
+			touched: clock()
+		});
 		response.headers.set(MCP_SESSION_HEADER, entry.session.id);
 		return response;
 	};
 }
 //#endregion
-export { DEFAULT_MCP_KEEPALIVE_INTERVAL, DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPClientTransport, MCPSession, MCP_METHOD_HEADER, MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, SSE_BUFFERING_DISABLED, SSE_BUFFERING_HEADER, SSE_KEEPALIVE_COMMENT, StdioClientTransport, StdioServerTransport, WebSocketClientTransport, WebSocketServerTransport, acceptsEventStream, allowsOrigin, bridgeMessageTransport, createHTTPClientTransport, createMCPPostHandler, createMCPRoutes, createMCPSession, createReadableStream, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, inferHeaderIssue, inferLegacyVersion, inferStatus, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, upgradeRequestPath };
+export { DEFAULT_MCP_KEEPALIVE_INTERVAL, DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPClientTransport, HTTPDisconnect, MCPSession, MCP_METHOD_HEADER, MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, SSE_BUFFERING_DISABLED, SSE_BUFFERING_HEADER, SSE_KEEPALIVE_COMMENT, StdioClientTransport, StdioServerTransport, WebSocketClientTransport, WebSocketServerTransport, acceptsEventStream, allowsOrigin, bridgeMessageTransport, createHTTPClientTransport, createMCPContinuation, createMCPPostHandler, createMCPRoutes, createMCPSession, createReadableStream, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, inferHeaderIssue, inferLegacyVersion, inferStatus, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, sendEventStream, upgradeRequestPath };
 
 //# sourceMappingURL=index.js.map