@orkestrel/mcp 0.0.27 → 0.0.28

package/dist/src/server/index.js

@@ -1,7 +1,6 @@
-import { createSSEParser } from "@orkestrel/sse";
-import { JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, MCP_HANDSHAKE_VERSION, MCP_HEADER_MISMATCH, MCP_LOOKUP_PAGES, MCP_META_VERSION, MCP_MISSING_CAPABILITY, MCP_PARAM_PREFIX, MCP_UNSUPPORTED_VERSION, SUPPORTED_LEGACY_PROTOCOL_VERSIONS, bindServer, buildHeaderParameters, buildHeaderProjection, buildJSONRPCError, decodeSentinel, encodeSentinel, extractToolSchema, inferRequestVersion, isInitializeRequest, isJSONRPCInvocation, isJSONRPCResponse, isMCPLegacyVersion, isMCPModernVersion, isMCPVersion, isModernRequest, parseJSONRPCMessage, parseRequestContext, renderHeaderValue } from "../core/index.js";
-import { isArray, isRecord, isString, sanitizeBudget } from "@orkestrel/contract";
-import { openStream, signToken, verifyToken } from "@orkestrel/server";
+import { HTTPClientTransport, JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, MCP_HANDSHAKE_VERSION, MCP_HEADER_MISMATCH, MCP_LOOKUP_PAGES, MCP_META_VERSION, MCP_METHOD_HEADER, MCP_MISSING_CAPABILITY, MCP_NAME_HEADER, MCP_PARAM_PREFIX, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_UNSUPPORTED_VERSION, MCP_WEBSOCKET_SUBPROTOCOL, SUPPORTED_LEGACY_PROTOCOL_VERSIONS, bindServer, buildHeaderParameters, buildJSONRPCError, decodeEvent, decodeSentinel, deliverMessage, extractToolSchema, inferRequestEra, isInitializeRequest, isJSONRPCInvocation, isMCPLegacyVersion, isMCPModernVersion, isModernRequest, parseJSONRPCMessage, parseRequestContext, renderHeaderValue } from "../core/index.js";
+import { isRecord, isString, parseJSON, sanitizeBudget } from "@orkestrel/contract";
+import { createStream, signToken, verifyToken } from "@orkestrel/server";
 import { Emitter } from "@orkestrel/emitter";
 import { WEBSOCKET_READY_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
 import { randomBytes } from "node:crypto";
@@ -11,35 +10,14 @@ import { Process } from "@orkestrel/process/server";
 import { PROCESS_GRACE } from "@orkestrel/process";
 import { Readable } from "node:stream";
 //#region src/server/constants.ts
-/**
-* The Streamable-HTTP transport header that carries the MCP session id. When a {@link
-* import('./middlewares.js').createMCPSession} middleware is mounted, it SETS this header on
-* the `initialize` response (the minted id) and READS it on every subsequent request
-* (validating the session); the stateless `createMCPRoutes` default neither sets nor reads it.
-*/
-var MCP_SESSION_HEADER = "mcp-session-id";
-/**
-* The Streamable-HTTP transport header carrying the negotiated MCP protocol version
-* on every post-initialize client request.
-*
-* @remarks
-* Required by MCP 2025-06-18 after initialization. Both HTTP client transports
-* capture the initialize result's `protocolVersion` and send it on subsequent
-* requests; `createMCPRoutes` rejects a present unsupported value before dispatch.
-*/
-var MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
-/** The modern Streamable-HTTP request header carrying the JSON-RPC method name. */
-var MCP_METHOD_HEADER = "mcp-method";
-/** The modern Streamable-HTTP request header carrying a named method's target. */
-var MCP_NAME_HEADER = "mcp-name";
-/** The reverse-proxy response header controlling buffering of an SSE response. */
+/** Names the reverse-proxy response header controlling buffering of an SSE response. */
 var SSE_BUFFERING_HEADER = "x-accel-buffering";
-/** The `X-Accel-Buffering` value that disables reverse-proxy buffering. */
+/** Names the `X-Accel-Buffering` value that disables reverse-proxy buffering. */
 var SSE_BUFFERING_DISABLED = "no";
-/** The default request path `createMCPRoutes` mounts the transport's `POST` route at. */
+/** Names the default request path `createMCPRoutes` mounts the transport's `POST` route at. */
 var DEFAULT_MCP_PATH = "/mcp";
 /**
-* The default interval in milliseconds between SSE keepalive comments on held-open MCP
+* Sets the default interval in milliseconds between SSE keepalive comments on held-open MCP
 * responses.
 *
 * @remarks
@@ -47,34 +25,22 @@ var DEFAULT_MCP_PATH = "/mcp";
 * client detection and staying comfortably inside common intermediary idle windows.
 */
 var DEFAULT_MCP_KEEPALIVE_INTERVAL = 15e3;
-/** The comment text written by the held-open MCP response keepalive. */
+/** Names the comment text written by the held-open MCP response keepalive. */
 var SSE_KEEPALIVE_COMMENT = "keepalive";
 /**
-* The WebSocket subprotocol the MCP-over-WebSocket transports negotiate — sent by the
-* client in `Sec-WebSocket-Protocol`, echoed by the server in its `101` handshake.
-*
-* @remarks
-* `createWebSocketServer` echoes it in the upgrade response and `createWebSocketClientTransport`
-* requests it, so an MCP WebSocket endpoint is distinguishable from any other WebSocket on the
-* same path. The default WebSocket upgrade path is {@link DEFAULT_MCP_PATH} (the same `'/mcp'`
-* the HTTP transport mounts at) — the upgrade is selected by the `Upgrade: websocket` header,
-* not a separate path.
-*/
-var MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
-/**
-* The default capacity of a session's FOLDED resumable event log (the per-{@link
+* Sets the default capacity of a session's FOLDED resumable event log (the per-{@link
 * import('./MCPSession.js').MCPSession} replay log) — the maximum number of pushed
 * server→client messages retained for replay before the OLDEST is evicted.
 *
 * @remarks
 * Bounds the replay log's memory: only the most-recent {@link DEFAULT_MCP_SESSION_CAPACITY}
 * pushes are retained, so a client reconnecting with a `Last-Event-ID` older than that window
-* replays nothing (its cursor fell off the back). Override per `createMCPSession`'s `capacity`
-* for a deeper / shallower window.
+* replays nothing (its cursor fell off the back). Override through the `session` group of
+* `createMCPSession`'s options (`session.capacity`) for a deeper / shallower window.
 */
 var DEFAULT_MCP_SESSION_CAPACITY = 1024;
 /**
-* The default per-event idle lifetime (ms) of a session's folded resumable event log — an
+* Sets the default per-event idle lifetime (ms) of a session's folded resumable event log — an
 * entry older than this is lazily evicted on the next access (no background timer), bounding
 * how far back a reconnecting client may replay.
 *
@@ -85,7 +51,7 @@ var DEFAULT_MCP_SESSION_CAPACITY = 1024;
 */
 var DEFAULT_MCP_SESSION_TTL = 3e5;
 /**
-* The default bound in milliseconds on one unconfirmed write to a stdio client transport's
+* Sets the default bound in milliseconds on one unconfirmed write to a stdio client transport's
 * child `stdin` — the `delivery` a `createStdioClientTransport` caller who supplies none gets.
 *
 * @remarks
@@ -99,37 +65,6 @@ var DEFAULT_MCP_DELIVERY = 1e4;
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Builds the error for a non-success HTTP response that carried no JSON-RPC message.
-*
-* @param response - The response whose status is reported
-* @param type - The response's content type, or an empty string when absent
-* @returns An error naming the HTTP status and unsupported response shape
-*
-* @example
-* ```ts
-* const error = buildResponseError(new Response('', { status: 500 }), '')
-* ```
-*/
-function buildResponseError(response, type) {
-	if (type.includes("application/json")) return /* @__PURE__ */ new Error(`HTTP ${response.status} response contained an application/json body that was not a JSON-RPC message`);
-	if (type.includes("text/event-stream")) return /* @__PURE__ */ new Error(`HTTP ${response.status} response contained a text/event-stream body without a JSON-RPC message`);
-	const shape = type === "" ? "a body without a content type" : `an unsupported '${type}' body`;
-	return /* @__PURE__ */ new Error(`HTTP ${response.status} response contained ${shape}`);
-}
-/**
-* Creates a readable stream from its pull and cancellation behaviours.
-*
-* @param pull - The behaviour that supplies the stream's next chunk
-* @param cancel - The behaviour that releases the stream after consumer cancellation
-* @returns A readable stream backed by the supplied behaviours
-*/
-function createReadableStream(pull, cancel) {
-	return new ReadableStream({
-		pull,
-		cancel
-	});
-}
-/**
 * Pumps 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.
@@ -157,7 +92,7 @@ function createReadableStream(pull, cancel) {
 * ```ts
 * const answer = await mcp.dispatch(invocation, { signal: disconnect.signal })
 * if (answer !== undefined && Symbol.asyncIterator in answer) {
-* 	const sse = openStream()
+* 	const sse = createStream()
 * 	queueMicrotask(() => void sendEventStream(answer, sse))
 * }
 * ```
@@ -179,7 +114,7 @@ async function sendEventStream(stream, sse) {
 	}
 }
 /**
-* Whether the request's `Accept` header opts into a Server-Sent-Events response.
+* Checks whether the request's `Accept` header opts into a Server-Sent-Events response.
 *
 * @remarks
 * Reads the fetch-standard `Request.headers.get('accept')` and returns `true` when it
@@ -189,7 +124,7 @@ async function sendEventStream(stream, sse) {
 * — an absent / unmatched header returns `false`.
 *
 * @param request - The fetch-standard `Request`
-* @returns `true` when the client `Accept`s `text/event-stream`, else `false`
+* @returns True if the client `Accept`s `text/event-stream`; false otherwise
 */
 function acceptsEventStream(request) {
 	const accept = request.headers.get("accept");
@@ -197,7 +132,7 @@ function acceptsEventStream(request) {
 	return accept.toLowerCase().includes("text/event-stream");
 }
 /**
-* Whether an HTTP request satisfies the endpoint's origin gate.
+* Checks whether an HTTP request satisfies the endpoint's origin gate.
 *
 * @remarks
 * Validation is enabled by default. A request without `Origin` is allowed. A canonical origin
@@ -208,7 +143,7 @@ function acceptsEventStream(request) {
 *
 * @param request - The fetch-standard request to validate
 * @param options - Shared origin validation and delegation options
-* @returns `true` when the request may reach MCP dispatch
+* @returns True if the request may reach MCP dispatch; false otherwise
 */
 function allowsOrigin(request, options) {
 	if (options?.enabled === false) return true;
@@ -279,65 +214,6 @@ function rejectUnknownSession() {
 	return Response.json(buildJSONRPCError(void 0, JSONRPC_INVALID_REQUEST, "Session not found"), { status: 404 });
 }
 /**
-* Decodes a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
-* carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.
-*
-* @remarks
-* Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({
-* stream: true })` (handling a multi-byte char split across reads) and `@orkestrel/sse`'s
-* {@link SSEParserInterface} (handling a partial line / in-progress event split across
-* reads), then narrows each dispatched event's `data` to a {@link JSONRPCMessage} with
-* `parseJSONRPCMessage` (so a non-message / non-JSON `data:` event is DROPPED, never
-* thrown — total). It reuses the SAME `SSEParser` the server's `openStream` seam
-* serializes against, so the wire round-trips. A `null` body (no stream) yields no
-* messages; the {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}
-* reads a request/response SSE reply (the server sends one `data:` event then ends), so
-* this drains to completion.
-*
-* @param response - The SSE `fetch` Response to decode (its `body` is read to completion)
-* @returns Every {@link JSONRPCMessage} the stream carried, in order
-*/
-async function readEventStream(response) {
-	const body = response.body;
-	if (body === null) return [];
-	const reader = body.getReader();
-	const decoder = new TextDecoder();
-	const parser = createSSEParser();
-	const messages = [];
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			for (const event of parser.parse(decoder.decode(value, { stream: true }))) {
-				const message = decodeEvent(event.data);
-				if (message !== void 0) messages.push(message);
-			}
-		}
-	} finally {
-		reader.releaseLock();
-	}
-	return messages;
-}
-/**
-* Decodes one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
-* when it is not one — the per-event step {@link readEventStream} folds over.
-*
-* @remarks
-* `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the event's
-* `data`) inside a try/catch and narrows the parsed value with `parseJSONRPCMessage`.
-* Total: malformed JSON or a non-message value yields `undefined`, never throws.
-*
-* @param data - One SSE event's `data` payload
-* @returns The decoded {@link JSONRPCMessage}, or `undefined`
-*/
-function decodeEvent(data) {
-	try {
-		return parseJSONRPCMessage(JSON.parse(data));
-	} catch {
-		return;
-	}
-}
-/**
 * Reads the path (without the query string) of a raw `node:http` protocol-upgrade request —
 * the `createWebSocketServer` upgrade-path match.
 *
@@ -419,16 +295,17 @@ function writeLine(output, line) {
 }
 /**
 * Decodes and delivers each complete newline-framed line onto a {@link
-* MCPClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
+* 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.
 *
 * @remarks
-* A blank line is skipped (a stray trailing newline). Every other line is decoded
-* with {@link decodeEvent} (`JSON.parse` + `parseJSONRPCMessage`, guarded); a
-* well-formed {@link JSONRPCMessage} emits `message`, a malformed / non-message line
-* emits `error` (total, never throws). Pure w.r.t. its own state — the emit is
-* the caller-owned side effect.
+* A blank line is skipped (a stray trailing newline). Every other line runs through the
+* shared {@link import('@orkestrel/mcp').deliverMessage} fold, the one inbound decode every
+* transport in this package shares: a well-formed {@link JSONRPCMessage} emits `message`,
+* unparsable text emits the caught parse error, and a well-formed non-message line emits
+* `error` naming a non-JSON-RPC stdio line (total, never throws). Pure w.r.t. its own state
+* — the emit is the caller-owned side effect.
 *
 * @param emitter - The transport's {@link EmitterInterface} to emit `message` / `error` onto
 * @param lines - The complete lines to decode and deliver
@@ -436,93 +313,9 @@ function writeLine(output, line) {
 function dispatchLines(emitter, lines) {
 	for (const line of lines) {
 		if (line.length === 0) continue;
-		const message = decodeEvent(line);
-		if (message === void 0) {
-			emitter.emit("error", /* @__PURE__ */ new Error("non-JSON-RPC stdio line"));
-			continue;
-		}
-		emitter.emit("message", message);
+		deliverMessage(emitter, line, "non-JSON-RPC stdio line");
 	}
 }
-/**
-* Bridges a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
-* WebSocket SERVER transports already implement) into the environment-agnostic
-* {@link import('@orkestrel/mcp').MCPTransportInterface} port — the adapter
-* {@link import('./factories.js').createStdioServer} and {@link
-* import('./factories.js').createWebSocketServer} pipe through `bindServer`, so the
-* request/reply/error pump those factories used to hand-roll identically now
-* lives ONCE in the core binder.
-*
-* @remarks
-* `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
-* and writes it through `transport.send` (the same `JSON.stringify` the underlying
-* transport already performs, so the wire bytes are unchanged). `listen` filters
-* `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('@orkestrel/mcp').MCPTransportInterface}, `listen`/`closed`
-* each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
-* Because the underlying `transport.emitter` is ADD-based (`on` subscribes, never
-* replaces), this bridge installs ONE stable emitter listener per event on first use
-* and re-routes it to whichever handler is active (`undefined` while
-* none is), so rebinding never double-dispatches.
-*
-* @remarks A response whose `result` serializes away (for example, `undefined`) is dropped by
-* the message validators on the wire's decode side — an asymmetry the stdio/WS carrier
-* shares with the streamable-HTTP face, because both round-trip through `JSON.stringify`
-* / `JSON.parse` before re-validation.
-*
-* @param transport - The message-channel transport to bridge (stdio or WebSocket)
-* @returns An {@link import('@orkestrel/mcp').MCPTransportInterface} `bindServer` can drive
-*
-* @example
-* ```ts
-* import { bindServer } from '@orkestrel/mcp'
-*
-* const transport = new StdioServerTransport(process.stdin, process.stdout)
-* bindServer(mcp, bridgeMessageTransport(transport))
-* ```
-*/
-function bridgeMessageTransport(transport) {
-	let onMessage;
-	let onClosed;
-	transport.emitter.on("message", (message) => {
-		if (!isJSONRPCInvocation(message)) return;
-		onMessage?.(JSON.stringify(message));
-	});
-	transport.emitter.on("close", () => {
-		onClosed?.();
-	});
-	return {
-		async send(message) {
-			const decoded = decodeEvent(message);
-			if (decoded === void 0) return;
-			await transport.send(decoded);
-		},
-		listen(handler) {
-			onMessage = handler;
-		},
-		closed(handler) {
-			onClosed = handler;
-		},
-		async close() {
-			await transport.close();
-		}
-	};
-}
 //#endregion
 //#region src/server/inferers.ts
 /**
@@ -559,7 +352,7 @@ function inferHeaderTarget(request) {
 	}
 }
 /**
-* Infers the first required MCP HTTP header that is missing or mismatched.
+* Infers the first required MCP HTTP header a request's own body contradicts.
 *
 * @remarks
 * A modern request derives its protocol, method, and name expectations from the JSON-RPC body,
@@ -568,12 +361,14 @@ 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, while a supplied legacy session
-* version additionally diagnoses a header that disagrees with the active session. Messages
-* name the expected value but never echo the client-supplied one.
+* body requires a protocol header after initialization. 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.
 *
 * @param request - The HTTP request carrying the headers
-* @param reference - The parsed invocation body, or the active legacy session version
+* @param invocation - The parsed invocation body the expectations are derived from
 * @returns The first header issue, or `undefined` when the applicable headers agree
 *
 * @example
@@ -582,30 +377,17 @@ function inferHeaderTarget(request) {
 * issue?.header // 'Mcp-Method' when that field is absent or mismatched
 * ```
 */
-function inferHeaderIssue(request, reference) {
+function inferHeaderIssue(request, invocation) {
 	const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
-	if (isString(reference)) {
-		if (protocol === null) return {
-			header: "MCP-Protocol-Version",
-			reason: "missing",
-			message: `Required MCP-Protocol-Version header is missing; the active session uses '${reference}'.`
-		};
-		if (protocol !== reference) return {
-			header: "MCP-Protocol-Version",
-			reason: "mismatched",
-			message: `MCP-Protocol-Version header does not match the active session version '${reference}'.`
-		};
-		return;
-	}
-	if (!isModernRequest(reference)) {
-		if (isInitializeRequest(reference) || protocol !== null) return void 0;
+	if (!isModernRequest(invocation)) {
+		if (isInitializeRequest(invocation) || protocol !== null) return void 0;
 		return {
 			header: "MCP-Protocol-Version",
 			reason: "missing",
 			message: `Required MCP-Protocol-Version header is missing; this server offers '${MCP_HANDSHAKE_VERSION}'.`
 		};
 	}
-	const message = reference;
+	const message = invocation;
 	const version = (isRecord(message.params?.["_meta"]) ? message.params["_meta"] : void 0)?.[MCP_META_VERSION];
 	if (!isString(version)) return void 0;
 	if (protocol === null) return {
@@ -644,6 +426,40 @@ function inferHeaderIssue(request, reference) {
 	};
 }
 /**
+* Infers the protocol header issue an active legacy session's pinned revision diagnoses.
+*
+* @remarks
+* The session layer's rule, distinct from the body-derived one {@link inferHeaderIssue} owns:
+* a live legacy session pinned its revision at `initialize`, so every later request on that
+* session must name the same one. An absent header reads as `missing`, which the session
+* middleware answers by SUPPLYING the pinned revision rather than refusing; a present header
+* naming another revision reads as `mismatched` and is refused. The message names the session's
+* revision and never echoes the client-supplied value.
+*
+* @param request - The HTTP request carrying the headers
+* @param version - The legacy revision the active session pinned at `initialize`
+* @returns The protocol header issue, or `undefined` when the header agrees
+*
+* @example
+* ```ts
+* const issue = inferSessionHeaderIssue(request, '2025-06-18')
+* issue?.reason // 'missing' when the request carries no protocol header
+* ```
+*/
+function inferSessionHeaderIssue(request, version) {
+	const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
+	if (protocol === null) return {
+		header: "MCP-Protocol-Version",
+		reason: "missing",
+		message: `Required MCP-Protocol-Version header is missing; the active session uses '${version}'.`
+	};
+	if (protocol !== version) return {
+		header: "MCP-Protocol-Version",
+		reason: "mismatched",
+		message: `MCP-Protocol-Version header does not match the active session version '${version}'.`
+	};
+}
+/**
 * Infers the refusal one `tools/call` earns for a `Mcp-Param-*` header the body contradicts.
 *
 * @remarks
@@ -736,7 +552,7 @@ function inferStatus(response, era) {
 	return 200;
 }
 //#endregion
-//#region src/server/transports/HTTPDisconnect.ts
+//#region src/server/HTTPDisconnect.ts
 /**
 * Composes one incoming HTTP request lifetime with one MCP-owned SSE response lifetime.
 *
@@ -765,10 +581,10 @@ function inferStatus(response, era) {
 * @example
 * ```ts
 * import { HTTPDisconnect } from '@orkestrel/mcp/server'
-* import { openStream } from '@orkestrel/server'
+* import { createStream } from '@orkestrel/server'
 *
 * const disconnect = new HTTPDisconnect(request.signal, { interval: 15_000 })
-* const stream = openStream()
+* const stream = createStream()
 * const response = disconnect.bridge(stream)
 * ```
 */
@@ -777,6 +593,9 @@ var HTTPDisconnect = class {
 	#lifecycle = new AbortController();
 	#interval;
 	#signal;
+	#pull = (controller) => this.#pump(controller);
+	#cancel = (reason) => this.#discard(reason);
+	#reader;
 	#timer;
 	#bridged = false;
 	#pulling = false;
@@ -793,8 +612,8 @@ var HTTPDisconnect = class {
 		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 signal aborted by the incoming request, or by any end of this response that
+	* is not its graceful completion.
 	*
 	* @returns The composed lifecycle signal
 	*/
@@ -820,7 +639,7 @@ var HTTPDisconnect = class {
 		const response = stream.response;
 		const body = response.body;
 		if (body === null) throw new Error("MCP SSE response has no body");
-		const reader = body.getReader();
+		this.#reader = body.getReader();
 		this.#timer = setInterval(() => {
 			if (stream.closed) {
 				if (!this.#pulling) this.#abort();
@@ -832,29 +651,39 @@ var HTTPDisconnect = class {
 		});
 		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.#release();
-					controller.close();
-				} else controller.enqueue(chunk.value);
-			} catch (error) {
-				this.#abort();
-				controller.error(error);
-			} finally {
-				this.#pulling = false;
-			}
-		}, async (reason) => {
-			this.#abort();
-			await reader.cancel(reason);
+		return new Response(new ReadableStream({
+			pull: this.#pull,
+			cancel: this.#cancel
 		}), {
 			status: response.status,
 			statusText: response.statusText,
 			headers: response.headers
 		});
 	}
+	async #pump(controller) {
+		const reader = this.#reader;
+		if (reader === void 0) {
+			controller.close();
+			return;
+		}
+		this.#pulling = true;
+		try {
+			const chunk = await reader.read();
+			if (chunk.done) {
+				this.#release();
+				controller.close();
+			} else controller.enqueue(chunk.value);
+		} catch (error) {
+			this.#abort();
+			controller.error(error);
+		} finally {
+			this.#pulling = false;
+		}
+	}
+	async #discard(reason) {
+		this.#abort();
+		await this.#reader?.cancel(reason);
+	}
 	#release() {
 		if (this.#timer !== void 0) {
 			clearInterval(this.#timer);
@@ -921,15 +750,11 @@ function createMCPPostHandler(mcp, options) {
 		} catch {
 			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(void 0, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
-		}
+		const parsed = parseJSON(text);
+		if (parsed === void 0) return Response.json(buildJSONRPCError(void 0, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
 		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 era = inferRequestEra(invocation);
 		const id = invocation.id;
 		const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
 		if (era === "modern" || isMCPModernVersion(protocol)) {
@@ -981,7 +806,7 @@ function createMCPPostHandler(mcp, options) {
 			...caller === void 0 ? {} : { caller }
 		});
 		if (response !== void 0 && Symbol.asyncIterator in response) {
-			const stream = openStream();
+			const stream = createStream();
 			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
 			queueMicrotask(() => void sendEventStream(response, stream));
 			return disconnect.bridge(stream);
@@ -989,7 +814,7 @@ function createMCPPostHandler(mcp, options) {
 		const status = inferStatus(response, era);
 		if (response === void 0) return new Response(null, { status });
 		if (status === 200 && streaming && acceptsEventStream(request)) {
-			const stream = openStream();
+			const stream = createStream();
 			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
 			stream.write({ data: JSON.stringify(response) });
 			stream.end();
@@ -999,215 +824,14 @@ function createMCPPostHandler(mcp, options) {
 	};
 }
 //#endregion
-//#region src/server/transports/HTTPClientTransport.ts
-/**
-* The HTTP CLIENT transport for the Model Context Protocol — a
-* {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server over
-* `fetch`, the egress mirror of the server's `createMCPRoutes`.
-*
-* @remarks
-* - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
-*   message to `options.url` with `content-type: application/json` and an
-*   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
-*   answer with either framing) — plus any `options.headers` (for example, an `Authorization`
-*   bearer). It then decodes the reply and emits each decoded {@link JSONRPCMessage} on
-*   the `message` event the {@link import('@orkestrel/mcp').MCPClientInterface} subscribes
-*   to.
-* - **Both reply framings.** A `200` with an `application/json` body is parsed with
-*   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded with the
-*   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} ({@link
-*   readEventStream}) — the inverse of the server's `openStream` seam, so the wire
-*   round-trips. A `202`
-*   Accepted (a notification) carries no body and emits nothing.
-* - **Session and protocol headers.** `start()` is a no-op (a
-*   request/response transport opens no long-lived connection). The
-*   `mcp-session-id` response header, when a STATEFUL server sends one (on
-*   `initialize`), is captured into `session` and then ECHOED as the
-*   `mcp-session-id` request header on every SUBSEQUENT request — so an
-*   `MCPClient` passes a stateful server's session validation. The
-*   initialize result's `protocolVersion` is likewise captured, but only
-*   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` alone on
-*   subsequent legacy requests. Modern requests instead derive protocol and method
-*   headers from the message, plus the name header only for `tools/call` — carried in the
-*   protocol's Base64 sentinel form whenever the tool name cannot ride as plain ASCII.
-*   Before initialize returns, neither captured legacy header is sent.
-*   `close()` clears the captured protocol so a reconnect's `initialize`
-*   POST is headerless; the captured `session` persists across `close()`.
-* - **`close()` releases what is in flight.** Every `fetch` this transport still has open is
-*   ABORTED, which cancels the response body a `send` is reading — an SSE reply the server
-*   never ends would otherwise outlive the transport, with nothing left able to reach it. The
-*   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
-*   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
-* - **Total at the boundary.** Every reply is narrowed (`parseJSONRPCMessage`,
-*   the SSE decoder). A non-message success reply is dropped, never asserted. A non-success
-*   reply that carries no valid JSON-RPC message rejects `send` with its HTTP status and body
-*   shape. A valid JSON-RPC error body is emitted at any HTTP status. A `fetch` / decode failure
-*   on a success response surfaces on the `error` event rather than escaping `send`.
-* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
-*   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
-*
-* @example
-* ```ts
-* const transport = new HTTPClientTransport({ url: 'http://localhost:3000/mcp' })
-* const client = new MCPClient({ transport })
-* await client.connect()
-* ```
-*/
-var HTTPClientTransport = class {
-	#emitter;
-	#url;
-	#headers;
-	#fetch;
-	#timeout;
-	#pending = /* @__PURE__ */ new Set();
-	#parameters = /* @__PURE__ */ new Map();
-	#stamps = /* @__PURE__ */ new WeakMap();
-	#session = void 0;
-	#protocol = void 0;
-	#generation = 0;
-	#closed = false;
-	constructor(options) {
-		this.#emitter = new Emitter();
-		this.#url = options.url;
-		this.#headers = options.headers ?? {};
-		this.#fetch = options.fetch ?? globalThis.fetch;
-		this.#timeout = options.timeout;
-	}
-	get emitter() {
-		return this.#emitter;
-	}
-	get session() {
-		return this.#session;
-	}
-	get duplex() {
-		return false;
-	}
-	async start() {
-		this.#closed = false;
-	}
-	async send(message) {
-		this.#stamp(message);
-		const request = new AbortController();
-		this.#pending.add(request);
-		try {
-			await this.#exchange(message, request.signal);
-		} finally {
-			this.#pending.delete(request);
-		}
-	}
-	#stamp(message) {
-		if (!isModernRequest(message) || message.method !== "tools/list") return;
-		if (message.params?.["cursor"] === void 0) this.#generation += 1;
-		this.#stamps.set(message, this.#generation);
-	}
-	async #exchange(message, signal) {
-		let response;
-		try {
-			response = await this.#fetch(this.#url, {
-				method: "POST",
-				headers: {
-					"content-type": "application/json",
-					accept: "application/json, text/event-stream",
-					...this.#session === void 0 ? {} : { [MCP_SESSION_HEADER]: this.#session },
-					...this.#buildHeaders(message),
-					...this.#headers
-				},
-				body: JSON.stringify(message),
-				signal: this.#timeout === void 0 ? signal : AbortSignal.any([signal, AbortSignal.timeout(this.#timeout)])
-			});
-		} catch (error) {
-			this.#emitter.emit("error", error);
-			return;
-		}
-		const session = response.headers.get(MCP_SESSION_HEADER);
-		if (session !== null) this.#session = session;
-		await this.#deliver(response, message);
-	}
-	async close() {
-		if (this.#closed) return;
-		this.#closed = true;
-		for (const request of this.#pending) request.abort();
-		this.#pending.clear();
-		this.#protocol = void 0;
-		this.#emitter.emit("close");
-	}
-	#buildHeaders(message) {
-		if (isModernRequest(message)) {
-			const version = inferRequestVersion(message);
-			const name = message.params?.["name"];
-			return {
-				...version === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: version },
-				[MCP_METHOD_HEADER]: message.method,
-				...message.method === "tools/call" && isString(name) ? {
-					[MCP_NAME_HEADER]: encodeSentinel(name),
-					...buildHeaderProjection(this.#parameters.get(name) ?? [], message.params?.["arguments"])
-				} : {}
-			};
-		}
-		return this.#protocol === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol };
-	}
-	async #deliver(response, sent) {
-		if (response.status === 202) return;
-		const type = response.headers.get("content-type") ?? "";
-		let messages = [];
-		let failure;
-		try {
-			if (type.includes("text/event-stream")) messages = await readEventStream(response);
-			else if (type.includes("application/json")) {
-				const message = parseJSONRPCMessage(await response.json());
-				if (message !== void 0) messages = [message];
-			}
-		} catch (error) {
-			failure = { error };
-		}
-		for (const message of messages) this.#capture(message, sent);
-		if (!response.ok && messages.length === 0) throw buildResponseError(response, type);
-		if (failure !== void 0) this.#emitter.emit("error", failure.error);
-	}
-	#capture(message, sent) {
-		if (isJSONRPCResponse(message) && isRecord(message.result) && isMCPVersion(message.result["protocolVersion"])) this.#protocol = message.result["protocolVersion"];
-		this.#emitter.emit("message", this.#select(message, sent));
-	}
-	#select(message, sent) {
-		if (!isModernRequest(sent) || sent.method !== "tools/list") return message;
-		if (!isJSONRPCResponse(message) || message.error !== void 0) return message;
-		const result = message.result;
-		const listed = isRecord(result) ? result["tools"] : void 0;
-		if (!isRecord(result) || !isArray(listed)) return message;
-		const current = this.#stamps.get(sent) === this.#generation;
-		if (current && sent.params?.["cursor"] === void 0) this.#parameters.clear();
-		const kept = [];
-		for (const tool of listed) {
-			if (!isRecord(tool) || !isString(tool["name"])) {
-				kept.push(tool);
-				continue;
-			}
-			const parameters = buildHeaderParameters(tool["inputSchema"]);
-			if (parameters === void 0) {
-				this.#emitter.emit("error", /* @__PURE__ */ new Error(`MCP tool '${tool["name"]}' is excluded from tools/list: its inputSchema carries an invalid x-mcp-header annotation`));
-				continue;
-			}
-			if (current) this.#parameters.set(tool["name"], parameters);
-			kept.push(tool);
-		}
-		return {
-			...message,
-			result: {
-				...result,
-				tools: kept
-			}
-		};
-	}
-};
-//#endregion
 //#region src/server/MCPSession.ts
 /**
-* One MCP transport session — the per-session entity a {@link
+* Represents one MCP transport session — the per-session entity a {@link
 * import('./middlewares.js').createMCPSession} middleware owns, keyed by its `id`, carrying the
 * resumable server→client push channel with its bounded replay log FOLDED IN.
 *
 * @remarks
-* The single session entity (the old `SessionState` + `EventStore` merged): it holds the
+* One entity carries the whole session: it holds the
 * session `id`, its OWN bounded, replayable log of pushed server→client messages (the
 * resumable GET-SSE channel — a private `#events` `Map` + a monotone `#counter`, with
 * `capacity` / `ttl` eviction, not a separate store), and the set of open
@@ -1219,7 +843,7 @@ var HTTPClientTransport = class {
 *   SSE event (`stream.write({ id, data })`). A push with NO attached stream is still logged,
 *   so a client that connects (or reconnects with a `Last-Event-ID`) LATER replays it from the
 *   log. A `write` to a closed stream is a safe no-op (the {@link
-*   `@orkestrel/server`'s `openStream` contract), so a just-disconnected stream that
+*   `@orkestrel/server`'s `createStream` contract), so a just-disconnected stream that
 *   has not yet been `detach`ed never throws. A replayed event and the live one carry the
 *   IDENTICAL id (the log assigns it once).
 *
@@ -1244,9 +868,10 @@ var HTTPClientTransport = class {
 *   The middleware opens the stream (the spine seam) and registers it here; this class only
 *   serializes a message onto the already-open streams.
 *
-* - **Injected clock.** `push` / `replay` accept an optional `now` (epoch ms), defaulting to
-*   `Date.now()` — so a test drives TTL eviction with an elapsed clock rather than a real
-*   timer.
+* - **Injected clock.** {@link import('./types.js').MCPSessionOptions.clock} supplies the
+*   epoch-ms clock the lazy TTL sweep reads, defaulting to `Date.now` — so a test drives TTL
+*   eviction with an elapsed clock rather than a real timer, and the middleware that mints a
+*   session hands its own clock down instead of leaving the log on wall-clock time.
 *
 * @example
 * ```ts
@@ -1262,11 +887,13 @@ var MCPSession = class {
 	#streams = /* @__PURE__ */ new Set();
 	#capacity;
 	#ttl;
+	#clock;
 	#counter = 0;
 	constructor(id, options) {
 		this.#id = id;
 		this.#capacity = options?.capacity ?? 1024;
 		this.#ttl = options?.ttl ?? 3e5;
+		this.#clock = options?.clock ?? Date.now;
 	}
 	get id() {
 		return this.#id;
@@ -1277,8 +904,8 @@ var MCPSession = class {
 	detach(stream) {
 		this.#streams.delete(stream);
 	}
-	push(message, now = Date.now()) {
-		const id = this.#append(message, now);
+	push(message) {
+		const id = this.#append(message);
 		const data = JSON.stringify(message);
 		for (const stream of this.#streams) stream.write({
 			id,
@@ -1286,15 +913,16 @@ var MCPSession = class {
 		});
 		return id;
 	}
-	replay(afterId, now = Date.now()) {
-		this.#evict(now);
+	replay(afterId) {
+		this.#evict(this.#clock());
 		const out = [];
 		let found = false;
 		for (const entry of this.#events.values()) if (found) out.push(entry);
 		else if (entry.id === afterId) found = true;
 		return found ? out : [];
 	}
-	#append(message, now) {
+	#append(message) {
+		const now = this.#clock();
 		this.#evict(now);
 		this.#counter += 1;
 		const id = this.#counter.toString(36);
@@ -1320,21 +948,21 @@ var MCPSession = class {
 //#endregion
 //#region src/server/transports/WebSocketServerTransport.ts
 /**
-* The per-connection JSON-RPC-over-WebSocket SERVER bridge — wraps a
-* {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
-* {@link MCPClientTransportInterface}, the bidirectional JSON-RPC message channel
+* Wraps a {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
+* {@link MCPMessageTransportInterface} — the per-connection JSON-RPC-over-WebSocket SERVER
+* bridge, the bidirectional JSON-RPC message channel
 * `createWebSocketServer` pumps `mcp.dispatch` over and the egress mirror's
 * {@link import('./WebSocketClientTransport.js').WebSocketClientTransport} reuses.
 *
 * @remarks
-* - **Reuses `MCPClientTransportInterface`.** It IS the same generic carrier the HTTP
+* - **Reuses `MCPMessageTransportInterface`.** 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
 *   session id is the deferred sessions tier). The name keeps the role explicit even though
 *   the shape is shared.
 * - **Inbound (`message`).** `start()` subscribes to the socket's `message` event; each text
-*   frame is `JSON.parse`d inside a try/catch and narrowed with `parseJSONRPCMessage` — a
+*   frame runs through the shared `deliverMessage` fold (parse, then narrow) — a
 *   well-formed {@link JSONRPCMessage} is re-emitted on this transport's `message` event (the
 *   parsed envelope the {@link import('@orkestrel/mcp').MCPServerInterface} pump dispatches), while
 *   a non-JSON or non-message frame is surfaced on `error` and DROPPED, never thrown. It
@@ -1352,7 +980,7 @@ var MCPSession = class {
 *   (idempotent — a second `close`, or a socket-driven close, emits once). A frame that arrives
 *   between that release and the peer's close echo reaches nothing: the socket-driven close path
 *   releases the same way, so a closed transport is never subscribed to a live socket.
-* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the emitter
+* - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); 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.
 */
@@ -1394,19 +1022,7 @@ var WebSocketServerTransport = class {
 		this.#emitter.emit("close");
 	}
 	#receive(text) {
-		let parsed;
-		try {
-			parsed = JSON.parse(text);
-		} catch (error) {
-			this.#emitter.emit("error", error);
-			return;
-		}
-		const message = parseJSONRPCMessage(parsed);
-		if (message === void 0) {
-			this.#emitter.emit("error", /* @__PURE__ */ new Error("non-JSON-RPC WebSocket frame"));
-			return;
-		}
-		this.#emitter.emit("message", message);
+		deliverMessage(this.#emitter, text, "non-JSON-RPC WebSocket frame");
 	}
 	#onClose() {
 		if (this.#closed) return;
@@ -1423,10 +1039,10 @@ var WebSocketServerTransport = class {
 //#endregion
 //#region src/server/transports/WebSocketClientTransport.ts
 /**
-* The WebSocket CLIENT transport for the Model Context Protocol — a
-* {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket, the
+* Drives a REMOTE MCP server over a WebSocket — a CLIENT
+* {@link MCPMessageTransportInterface} for the Model Context Protocol, the
 * egress mirror of {@link import('./factories.js').createWebSocketServer} and the WebSocket
-* sibling of {@link import('./HTTPClientTransport.js').HTTPClientTransport}.
+* sibling of {@link import('@orkestrel/mcp').HTTPClientTransport}.
 *
 * @remarks
 * - **Persistent bidirectional channel (unlike the HTTP transport).** `start()` performs the
@@ -1444,8 +1060,8 @@ var WebSocketServerTransport = class {
 *   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`
+* - **Inbound (`message`).** Each decoded text frame runs through the shared `deliverMessage`
+*   fold (parse, then narrow) — a {@link JSONRPCMessage} re-emits on this transport's `message`
 *   event (the reply the {@link import('@orkestrel/mcp').MCPClientInterface} correlates by `id`); a
 *   non-JSON / non-message frame surfaces on `error` and is dropped. The socket's `close`
 *   / `error` bridge to this transport's events.
@@ -1463,7 +1079,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 through `node:https`). Either reaches the same endpoint.
-* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
+* - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); every emit
 *   the emitter isolates a listener throw (a buggy observer never corrupts the transport);
 *   `error` is a DOMAIN event (a transport-level fault).
 *
@@ -1500,7 +1116,7 @@ var WebSocketClientTransport = class {
 		if (this.#socket !== void 0) return;
 		this.#closed = false;
 		try {
-			await this.#connect(this.#httpURL(), randomBytes(16).toString("base64"));
+			await this.#connect(this.#toHTTPURL(), randomBytes(16).toString("base64"));
 		} finally {
 			this.#request = void 0;
 		}
@@ -1533,7 +1149,7 @@ var WebSocketClientTransport = class {
 					Upgrade: "websocket",
 					"Sec-WebSocket-Key": key,
 					"Sec-WebSocket-Version": WEBSOCKET_VERSION,
-					"Sec-WebSocket-Protocol": "mcp",
+					"Sec-WebSocket-Protocol": MCP_WEBSOCKET_SUBPROTOCOL,
 					...this.#headers
 				}
 			});
@@ -1585,19 +1201,7 @@ var WebSocketClientTransport = class {
 		socket.emitter.off("error", this.#failure);
 	}
 	#receive(text) {
-		let parsed;
-		try {
-			parsed = JSON.parse(text);
-		} catch (error) {
-			this.#emitter.emit("error", error);
-			return;
-		}
-		const message = parseJSONRPCMessage(parsed);
-		if (message === void 0) {
-			this.#emitter.emit("error", /* @__PURE__ */ new Error("non-JSON-RPC WebSocket frame"));
-			return;
-		}
-		this.#emitter.emit("message", message);
+		deliverMessage(this.#emitter, text, "non-JSON-RPC WebSocket frame");
 	}
 	#onClose() {
 		if (this.#closed) return;
@@ -1606,7 +1210,7 @@ var WebSocketClientTransport = class {
 		this.#socket = void 0;
 		this.#emitter.emit("close");
 	}
-	#httpURL() {
+	#toHTTPURL() {
 		const url = new URL(this.#url);
 		if (url.protocol === "ws:") url.protocol = "http:";
 		else if (url.protocol === "wss:") url.protocol = "https:";
@@ -1617,10 +1221,9 @@ var WebSocketClientTransport = class {
 //#endregion
 //#region src/server/transports/StdioClientTransport.ts
 /**
-* The stdio CLIENT transport for the Model Context Protocol — a
-* {@link StdioClientTransportInterface} 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
+* Drives a CHILD PROCESS MCP server over newline-delimited JSON-RPC on `stdin`/`stdout` —
+* a {@link StdioClientTransportInterface}, the stdio sibling of {@link
+* import('@orkestrel/mcp').HTTPClientTransport} and {@link
 * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
 *
 * @remarks
@@ -1661,7 +1264,7 @@ var WebSocketClientTransport = class {
 *   never moves again, so a detached descendant writing to the inherited stderr after the cutoff
 *   cannot grow it. See {@link StdioClientTransportInterface.evidence} for the readings and the
 *   byte bound.
-* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
+* - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); the
 *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
 *   fault, including the child spawn cause the supervisor surfaces and the notice that this
 *   lifetime's `evidence` was cut off at the `drain` bound), distinct from the emitter's own
@@ -1783,15 +1386,14 @@ var StdioClientTransport = class {
 //#endregion
 //#region src/server/transports/StdioServerTransport.ts
 /**
-* 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 MCPClientTransportInterface}, the newline-delimited
-* JSON-RPC channel {@link import('../factories.js').createStdioServer} pumps
-* `mcp.dispatch` over, the stdio mirror of {@link
+* Wraps an injectable readable/writable stream pair (`process.stdin`/`process.stdout` in
+* production, a test double in tests) as a {@link MCPMessageTransportInterface} — 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 `MCPClientTransportInterface`.** The same generic carrier the HTTP
+* - **Reuses `MCPMessageTransportInterface`.** 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
@@ -1817,7 +1419,7 @@ var StdioClientTransport = class {
 *   listener receives data. The injected streams are owned by the caller (typically
 *   `process.stdin`/`process.stdout`), so the transport never destroys, ends, or blanket-clears
 *   them.
-* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
+* - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); the
 *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
 *   fault), distinct from the emitter's own listener-error channel.
 */
@@ -1923,6 +1525,87 @@ function createMCPContinuation(secret) {
 	};
 }
 /**
+* Creates the server-side mirror of
+* {@link import('@orkestrel/mcp').createDuplexClientTransport}: the adapter that bridges a
+* message-channel {@link MCPMessageTransportInterface}
+* (the shape the stdio and WebSocket SERVER transports already implement) onto the
+* environment-agnostic {@link import('@orkestrel/mcp').MCPTransportInterface} port — what
+* {@link createStdioServer} and {@link createWebSocketServer} pipe through `bindServer`, so
+* the request/reply/error pump those factories used to hand-roll identically now lives ONCE
+* in the core binder. {@link import('@orkestrel/mcp').createDuplexClientTransport} adapts the
+* same two contracts the other way.
+*
+* @remarks
+* `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
+* and writes it through `transport.send` (the same `JSON.stringify` the underlying
+* transport already performs, so the wire bytes are unchanged). `listen` filters
+* `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('@orkestrel/mcp').MCPTransportInterface}, `listen`/`closed`
+* each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
+* Because the underlying `transport.emitter` is ADD-based (`on` subscribes, never
+* replaces), this bridge installs ONE stable emitter listener per event on first use
+* and re-routes it to whichever handler is active (`undefined` while
+* none is), so rebinding never double-dispatches.
+*
+* @remarks A response whose `result` serializes away (for example, `undefined`) is dropped by
+* the message validators on the wire's decode side — an asymmetry the stdio/WS carrier
+* shares with the streamable-HTTP face, because both round-trip through `JSON.stringify`
+* / `JSON.parse` before re-validation.
+*
+* @param transport - The message-channel transport to bridge (stdio or WebSocket)
+* @returns An {@link import('@orkestrel/mcp').MCPTransportInterface} `bindServer` can drive
+*
+* @example
+* ```ts
+* import { bindServer } from '@orkestrel/mcp'
+*
+* const transport = new StdioServerTransport(process.stdin, process.stdout)
+* bindServer(mcp, createDuplexServerTransport(transport))
+* ```
+*/
+function createDuplexServerTransport(transport) {
+	let onMessage;
+	let onClosed;
+	transport.emitter.on("message", (message) => {
+		if (!isJSONRPCInvocation(message)) return;
+		onMessage?.(JSON.stringify(message));
+	});
+	transport.emitter.on("close", () => {
+		onClosed?.();
+	});
+	return {
+		async send(message) {
+			const decoded = decodeEvent(message);
+			if (decoded === void 0) return;
+			await transport.send(decoded);
+		},
+		listen(handler) {
+			onMessage = handler;
+		},
+		closed(handler) {
+			onClosed = handler;
+		},
+		async close() {
+			await transport.close();
+		}
+	};
+}
+/**
 * Creates the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
 * {@link MCPDispatcherInterface} (the `@orkestrel/mcp` dispatch boundary) on the fetch-standard router
 * spine, pumping each `POST` body through `mcp.dispatch`. Returns the {@link RouteInput}s to
@@ -1948,7 +1631,7 @@ function createMCPContinuation(secret) {
 * When `streaming` is enabled (the default) and the client `Accept`s `text/event-stream`,
 * the `200` reply is framed as a Streamable-HTTP SSE response (one `data:` event carrying
 * the JSON-RPC envelope, then the stream ends) through `@orkestrel/server`'s generic
-* {@link import('@orkestrel/server').openStream} seam; otherwise it is a plain JSON body.
+* {@link import('@orkestrel/server').createStream} seam; otherwise it is a plain JSON body.
 *
 * **Sessions are a SEPARATE, plug-and-play middleware.** `createMCPRoutes` mints / reads no
 * session id. To make the transport STATEFUL, mount {@link
@@ -1987,10 +1670,15 @@ function createMCPRoutes(mcp, options) {
 }
 /**
 * Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
-* — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
+* — a {@link MCPMessageTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
 * over `fetch`. The egress mirror of {@link createMCPRoutes}.
 *
 * @remarks
+* It returns the core {@link import('@orkestrel/mcp').HTTPClientTransport}, the same class the
+* browser face's `createHTTPClientTransport` returns, because the class touches `fetch`,
+* `Response`, `AbortController`, `AbortSignal`, and `WeakMap` alone.
+*
+* @remarks
 * Hand it to `createMCPClient({ transport })`: each JSON-RPC message the client sends is
 * `POST`ed to `options.url` with `content-type: application/json` and an `Accept` of
 * both `application/json` and `text/event-stream` (the server answers with EITHER — a
@@ -2006,7 +1694,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 with `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
-* @returns A working {@link MCPClientTransportInterface} over `fetch`
+* @returns A working {@link MCPMessageTransportInterface} over `fetch`
 *
 * @example
 * ```ts
@@ -2043,7 +1731,7 @@ function createHTTPClientTransport(options) {
 *   only when the client's offer contains it, and sends UNMASKED frames), wraps it in a
 *   {@link WebSocketServerTransport}, and pipes it through the core {@link
 *   import('@orkestrel/mcp').MCPTransportInterface} port through {@link
-*   import('./helpers.js').bridgeMessageTransport} + {@link import('@orkestrel/mcp').bindServer}:
+*   createDuplexServerTransport} + {@link import('@orkestrel/mcp').bindServer}:
 *   each inbound REQUEST runs through `mcp.dispatch`, and a defined response is written back
 *   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
 *   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
@@ -2079,7 +1767,7 @@ function createHTTPClientTransport(options) {
 */
 function createWebSocketServer(mcp, options) {
 	const path = options.path ?? "/mcp";
-	const subprotocol = options.subprotocol ?? "mcp";
+	const subprotocol = options.subprotocol ?? MCP_WEBSOCKET_SUBPROTOCOL;
 	const live = /* @__PURE__ */ new Map();
 	options.emitter.on("stop", () => {
 		for (const [transport, unbind] of live) {
@@ -2103,7 +1791,7 @@ function createWebSocketServer(mcp, options) {
 			head,
 			...protocol === void 0 ? {} : { protocol }
 		}));
-		const unbind = bindServer(mcp, bridgeMessageTransport(transport));
+		const unbind = bindServer(mcp, createDuplexServerTransport(transport));
 		live.set(transport, unbind);
 		transport.emitter.on("close", () => {
 			live.delete(transport);
@@ -2115,7 +1803,7 @@ function createWebSocketServer(mcp, options) {
 }
 /**
 * Creates the WebSocket CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
-* — a {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
+* — a {@link MCPMessageTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
 * egress mirror of {@link createWebSocketServer} and the WebSocket sibling of {@link
 * createHTTPClientTransport}.
 *
@@ -2131,7 +1819,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 MCPClientTransportInterface} over a WebSocket
+* @returns A working {@link MCPMessageTransportInterface} over a WebSocket
 *
 * @example
 * ```ts
@@ -2197,7 +1885,7 @@ function createStdioClientTransport(options) {
 * Wraps `options.input` (default `process.stdin`) / `options.output` (default
 * `process.stdout`) in a {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
 * and pipes it through the core {@link import('@orkestrel/mcp').MCPTransportInterface} port
-* through {@link import('./helpers.js').bridgeMessageTransport} + {@link
+* through {@link createDuplexServerTransport} + {@link
 * import('@orkestrel/mcp').bindServer}: each inbound REQUEST runs through `mcp.dispatch`, and
 * a defined response is written back as a newline-terminated line — a NOTIFICATION
 * writes nothing, and a non-request message is ignored. A `dispatch` / `send` fault
@@ -2223,7 +1911,7 @@ function createStdioClientTransport(options) {
 */
 function createStdioServer(mcp, options) {
 	const transport = new StdioServerTransport(options?.input ?? process.stdin, options?.output ?? process.stdout);
-	const unbind = bindServer(mcp, bridgeMessageTransport(transport));
+	const unbind = bindServer(mcp, createDuplexServerTransport(transport));
 	return {
 		start() {
 			transport.start();
@@ -2255,8 +1943,9 @@ function createStdioServer(mcp, options) {
 *   can re-read it from a freshly-built forwarded `Request`). Resolves a session through {@link
 *   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()`, `capacity`)
-*   and sets `context.state.session`; neither → {@link rejectUnknownSession} (`404`). The
+*   isInitializeRequest}) MINTS a fresh {@link MCPSession} (`crypto.randomUUID()`, the `session`
+*   options group) and sets `context.state.session`; neither → {@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
@@ -2267,7 +1956,7 @@ function createStdioServer(mcp, options) {
 *   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 through `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
+*   server→client stream through `@orkestrel/server`'s {@link import('@orkestrel/server').createStream}:
 *   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) BEFORE
 *   attaching the stream for live pushes, then attaches; cancellation of the streamed response
 *   body composes with `request.signal` and detaches it. Long-lived — never `end()`ed here.
@@ -2282,10 +1971,11 @@ function createStdioServer(mcp, options) {
 * @typeParam TState - The consumer's `TState`, which MUST extend {@link MCPSessionState} so
 *   the resolved session can be threaded through `context.state.session`
 * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}), `ttl` (idle-session
-*   sweep window, ms — omit for sessions that live until an explicit `DELETE`), `capacity`
-*   (the folded per-session replay-log bound), and `clock` (the deterministic epoch-ms clock;
-*   defaults to `Date.now`), plus the shared `origin` validation options; see
-*   {@link MCPSessionOptions}
+*   sweep window, ms — omit for sessions that live until an explicit `DELETE`), `session`
+*   (the knobs each minted {@link MCPSession} takes — `capacity`, the log's own `ttl`, and its
+*   `clock`), and `clock` (the deterministic epoch-ms clock this middleware keeps its own
+*   bookkeeping on and hands down to a session that names none; defaults to `Date.now`), plus
+*   the shared `origin` validation options; see {@link MCPSessionMiddlewareOptions}
 * @returns A {@link MiddlewareHandler} that mints / validates sessions + serves the resumable
 *   `GET` / `DELETE`
 *
@@ -2303,7 +1993,7 @@ function createStdioServer(mcp, options) {
 */
 function createMCPSession(options) {
 	const path = options?.path ?? "/mcp";
-	const capacity = options?.capacity;
+	const sessionOptions = options?.session ?? {};
 	const ttl = options?.ttl;
 	const clock = options?.clock ?? Date.now;
 	const origin = options?.origin;
@@ -2316,10 +2006,10 @@ function createMCPSession(options) {
 		if (context.method === "POST") {
 			try {
 				text = await request.text();
-				parsed = parseJSONRPCMessage(JSON.parse(text));
 			} catch {
-				parsed = void 0;
+				text = void 0;
 			}
+			parsed = text === void 0 ? void 0 : parseJSONRPCMessage(parseJSON(text));
 			if (text !== void 0 && parsed !== void 0 && isModernRequest(parsed)) return next(new Request(context.url, {
 				method: "POST",
 				headers: request.headers,
@@ -2352,7 +2042,7 @@ function createMCPSession(options) {
 		if (context.method === "GET") {
 			if (entry === void 0) return rejectUnknownSession();
 			const session = entry.session;
-			const stream = openStream();
+			const stream = createStream();
 			const disconnect = new HTTPDisconnect(request.signal, options?.keepalive);
 			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
 			stream.comment("open");
@@ -2371,7 +2061,10 @@ function createMCPSession(options) {
 		if (entry === void 0) {
 			if (parsed !== void 0 && isInitializeRequest(parsed)) {
 				created = {
-					session: new MCPSession(crypto.randomUUID(), capacity !== void 0 ? { capacity } : {}),
+					session: new MCPSession(crypto.randomUUID(), {
+						...sessionOptions,
+						clock: sessionOptions.clock ?? clock
+					}),
 					touched: clock(),
 					version: inferLegacyVersion(parsed)
 				};
@@ -2381,7 +2074,7 @@ function createMCPSession(options) {
 		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);
+			const issue = inferSessionHeaderIssue(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 : void 0;
@@ -2409,6 +2102,6 @@ function createMCPSession(options) {
 	};
 }
 //#endregion
-export { DEFAULT_MCP_DELIVERY, 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, buildResponseError, createHTTPClientTransport, createMCPContinuation, createMCPPostHandler, createMCPRoutes, createMCPSession, createReadableStream, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, inferHeaderIssue, inferHeaderTarget, inferLegacyVersion, inferParameterRefusal, inferStatus, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, sendEventStream, upgradeRequestPath, writeLine };
+export { DEFAULT_MCP_DELIVERY, DEFAULT_MCP_KEEPALIVE_INTERVAL, DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPDisconnect, MCPSession, SSE_BUFFERING_DISABLED, SSE_BUFFERING_HEADER, SSE_KEEPALIVE_COMMENT, StdioClientTransport, StdioServerTransport, WebSocketClientTransport, WebSocketServerTransport, acceptsEventStream, allowsOrigin, createDuplexServerTransport, createHTTPClientTransport, createMCPContinuation, createMCPPostHandler, createMCPRoutes, createMCPSession, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, dispatchLines, extractLines, inferHeaderIssue, inferHeaderTarget, inferLegacyVersion, inferParameterRefusal, inferSessionHeaderIssue, inferStatus, readLastEventId, readSessionHeader, rejectUnknownSession, sendEventStream, upgradeRequestPath, writeLine };
 
 //# sourceMappingURL=index.js.map