@orkestrel/mcp 0.0.27 → 0.0.29

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.
+* 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,12 +51,12 @@ 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
 * Ten seconds. The load-bearing property is the ordering, not the magnitude: this bound stays
-* BELOW {@link import('@orkestrel/mcp').DEFAULT_MCP_REQUEST_TIMEOUT}, so a write the child never
+* below {@link import('@orkestrel/mcp').DEFAULT_MCP_REQUEST_TIMEOUT}, so a write the child never
 * reads fails as an undeliverable message while the request that carried it is still open,
 * rather than being masked by that request's own deadline expiring first. Override per
 * transport with `delivery`; an explicit `0` there removes the bound.
@@ -99,48 +65,17 @@ 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
+* notification in order, then the terminating response — and end the exchange however the
 * pump leaves.
 *
 * @remarks
 * The Streamable-HTTP twin of {@link import('@orkestrel/mcp').sendStream}, and it owns exactly what
-* that owns. The `finally` releases the exchange on EVERY exit — the normal terminal, a
+* 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
+* The exchange is released before the body ends, so the slot is already back when the response
 * completes.
 *
 * Total — never throws and never rejects. A held-open SSE response has already sent its
@@ -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;
@@ -267,7 +202,7 @@ function readLastEventId(request) {
 * @remarks
 * 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
+* 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
@@ -279,70 +214,11 @@ 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.
 *
 * @remarks
-* A `node:http` {@link import('node:http').IncomingMessage}'s `url` is the request TARGET
+* A `node:http` {@link import('node:http').IncomingMessage}'s `url` is the request target
 * (`'/mcp?x=1'`), narrowed with `isString` (never `as`) and defaulting to `'/'` for an
 * absent target; it is parsed against a placeholder base (only the pathname matters for the upgrade
 * decision) and the `pathname` returned. The upgrade handler compares this against its
@@ -363,7 +239,7 @@ function upgradeRequestPath(request) {
 *
 * @remarks
 * Concatenates `buffer` (the carried-forward partial line from the previous call)
-* with `chunk`, splits on `'\n'`, and returns every COMPLETE line (a `'\r'` trailing
+* with `chunk`, splits on `'\n'`, and returns every complete line (a `'\r'` trailing
 * a line, from a CRLF-framed peer, is trimmed) plus the final, possibly-empty
 * fragment as the new `remainder` — the caller threads it back in as the next call's
 * `buffer`. A chunk containing no `'\n'` yields no lines and the whole (buffer +
@@ -388,12 +264,12 @@ function extractLines(buffer, chunk) {
 * The completion callback is the writable channel's backpressure boundary. A callback error and
 * a synchronous `write` throw reject the returned promise with the original value.
 *
-* That callback is the ONLY thing that settles the promise: this helper holds no timer and no
+* That callback is the only thing that settles the promise: this helper holds no timer and no
 * abort, so an output that neither confirms nor fails the write parks the promise for as long as
 * the caller-owned stream holds the callback. A caller wanting a bound races this promise against
 * one it owns — {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
 * registers such a bound per send and rejects it on `close()`, so closing the transport settles
-* the CALLER's `send` while the abandoned write stays with the stream that still holds its
+* the caller's `send` while the abandoned write stays with the stream that still holds its
 * callback, reachable from nothing the transport retains.
 *
 * @param output - The writable stream that receives the line
@@ -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,12 +426,46 @@ 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
 * The custom-header half of the standard-header seam {@link inferHeaderIssue} owns, and it
-* takes the SERVED definition's projections rather than a header issue: SEP-2243 scopes the
-* rule to the `Mcp-Param-*` names the server's OWN tool definitions annotate, so a name no
+* takes the served definition's projections rather than a header issue: SEP-2243 scopes the
+* rule to the `Mcp-Param-*` names the server's own tool definitions annotate, so a name no
 * parameter claims is another party's header and travels through untouched.
 *
 * For each recognized parameter the body's value at the parameter's own property path fixes
@@ -700,7 +516,7 @@ function inferParameterRefusal(request, parameters, values) {
 *
 * @remarks
 * A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
-* request selects the newest supported legacy revision. The read is deliberately the SAME one
+* request selects the newest supported legacy revision. The read is deliberately the same one
 * {@link import('@orkestrel/mcp').buildInitializeResult} performs — `isMCPLegacyVersion` over
 * the requested revision — because the session version this pins and the version that result
 * echoes must be the one value. Routing through `inferVersion` cannot do it: that inferer is
@@ -736,27 +552,27 @@ 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.
 *
 * @remarks
-* The composed {@link signal} observes request abort and EVERY way this response can end
+* 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,
+* Graceful upstream completion is the one terminal that does not abort: the body 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:
-* a second {@link bridge} call THROWS rather than arming a second keepalive over one lifecycle.
+* a second {@link bridge} call throws rather than arming a second keepalive over one lifecycle.
 * It supplies no handler or session policy.
 *
-* The keepalive interval is a BUDGET, sanitized like every other numeric knob in this package:
+* 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
@@ -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);
@@ -877,7 +706,7 @@ var HTTPDisconnect = class {
 * method carrying a named target — `tools/call` and `prompts/get` against `params.name`,
 * `resources/read` against `params.uri` — with a Base64-sentinel value decoded before the
 * comparison; a missing, mismatched, or invalidly encoded value returns HTTP `400` + `-32020`.
-* A protocol header naming a MODERN revision holds the request to that revision whatever shape
+* A protocol header naming a modern revision holds the request to that revision whatever shape
 * its body arrived in, so a body with no parsable modern `_meta` returns HTTP `400` + `-32602`.
 * Headerless `initialize` is accepted, while every other headerless request needs a live legacy
 * session to supply its pinned version. A legacy-shaped request carrying a protocol header is
@@ -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,244 +824,43 @@ 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.
+* 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
-* session `id`, its OWN bounded, replayable log of pushed server→client messages (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
 * server→client SSE streams (a resumable `GET {path}` registers through `attach`, unregisters through
 * `detach` on disconnect). Still a small entity (not a record), built minimal + extensible.
 *
-* - **`push` is the server-initiated primitive.** It APPENDS the message to the log (assigning
-*   a monotone base36 event id) and FANS it out to every attached stream as one `id:`-tagged
-*   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
+* - **`push` is the server-initiated primitive.** It appends the message to the log (assigning
+*   a monotone base36 event id) and fans it out to every attached stream as one `id:`-tagged
+*   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).
+*   identical id (the log assigns it once).
 *
 * - **`replay(afterId)` is strictly-after.** It returns every retained log entry whose id sorts
-*   AFTER `afterId` in append order — the missed-events list the `GET {path}` handler writes
-*   before attaching the stream for live pushes. The decision for an UNKNOWN / already-evicted
+*   after `afterId` in append order — the missed-events list the `GET {path}` handler writes
+*   before attaching the stream for live pushes. The decision for an unknown / already-evicted
 *   `afterId` (the client's cursor fell off the back of the capacity window, or never existed):
-*   replay NOTHING. Replaying the whole retained log would re-deliver events the client never
-*   lost (its cursor is OLDER than everything retained); returning `[]` lets the handler then
+*   replay nothing. Replaying the whole retained log would re-deliver events the client never
+*   lost (its cursor is older than everything retained); returning `[]` lets the handler then
 *   stream only the fresh pushes that follow `attach` — the spec-sane resume.
 *
-* - **Bounded, append-ordered, plain `Map`.** The log lives in ONE insertion-ordered
-*   `Map<id, entry>` — insertion order IS append order IS id order, so `replay` and capacity
-*   eviction both walk the map directly. NO database mirror — the log is process-local
+* - **Bounded, append-ordered, plain `Map`.** The log lives in one insertion-ordered
+*   `Map<id, entry>` — insertion order is append order is id order, so `replay` and capacity
+*   eviction both walk the map directly. No database mirror — the log is process-local
 *   transport mechanics, not durable state. `push` first drops every entry older than `ttl`
 *   (lazy TTL — no background timer, the middleware's lazy-window idiom), appends, then evicts
-*   the OLDEST entries until at most `capacity` remain; `replay` also runs the lazy TTL sweep
+*   the oldest entries until at most `capacity` remain; `replay` also runs the lazy TTL sweep
 *   first, so a stale entry is never replayed.
 *
 * - **No transport coupling beyond the SSE seam.** It holds session state + the generic {@link
@@ -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,30 +948,30 @@ 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,
+*   `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
+*   a non-JSON or non-message frame is surfaced on `error` and dropped, never thrown. It
 *   also bridges the socket's `close` → this transport's `close`, and the socket's `error`.
 * - **Outbound (`send`).** `send(message)` writes one text frame
 *   (`nodeWs.send(JSON.stringify(message))`). The underlying wrapper no-ops a write on a
 *   non-open socket and confirms nothing, so this bridge answers a closed channel from its own
 *   state and the socket's `readyState`: a `send` after `close()`, after the peer's close, or on
-*   a socket that is not `OPEN` REJECTS with `WebSocket transport is not connected` rather than
+*   a socket that is not `OPEN` rejects with `WebSocket transport is not connected` rather than
 *   resolving on a frame nobody wrote. `bindServer` catches that rejection and routes it to the
 *   dispatcher's `error` event, and it aborts every in-flight request the moment this transport's
 *   `close` fires — so a peer that disconnects mid-request is answered by no write at all.
@@ -1352,9 +980,9 @@ 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.
+*   domain event (a transport-level fault), distinct from the emitter's listener-error channel.
 */
 var WebSocketServerTransport = class {
 	#emitter;
@@ -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,49 +1039,49 @@ 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
 *   RFC 6455 client handshake: it opens a `node:http`(`s`) `GET` carrying `Connection: Upgrade`
 *   / `Upgrade: websocket` / a random `Sec-WebSocket-Key` / `Sec-WebSocket-Version: 13` /
 *   `Sec-WebSocket-Protocol: mcp` (plus any `options.headers`), awaits the client `'upgrade'`
-*   event, and VALIDATES `Sec-WebSocket-Accept === computeWebSocketAccept(key)` (the D2 helper)
-*   — a mismatch (or a non-`101` response, or a request error) REJECTS `start()` and the socket
+*   event, and validates `Sec-WebSocket-Accept === computeWebSocketAccept(key)` (the D2 helper)
+*   — 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 RFC 6455 §5.3) and bridges its
+*   head })` (client mode — no key → frames are masked per RFC 6455 §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
+*   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.
 * - **Outbound (`send`).** `send(message)` writes one masked text frame. A socket write is not
-*   confirmed, so this transport answers a closed channel from its own state AND the socket's
+*   confirmed, so this transport answers a closed channel from its own state and the socket's
 *   `readyState`: a `send` with no bound socket — before `start()`, after `close()`, or after the
-*   peer ended the socket — and a `send` on a bound socket that is not `OPEN` both REJECT with
+*   peer ended the socket — and a `send` on a bound socket that is not `OPEN` both reject with
 *   `WebSocket transport is not connected`. It neither drops the message nor queues it for a
 *   connection this transport is not holding — the browser face queues a pre-open send, and this
 *   one, holding no connection to flush it onto, rejects that too.
 * - **`close()`** unsubscribes from the socket, closes it, and fires `close` (idempotent). An
-*   upgrade still on the wire is DESTROYED, so a `close()` during the handshake ends the
+*   upgrade still on the wire is destroyed, so a `close()` during the handshake ends the
 *   transport at once instead of waiting for a peer that may never answer — the suspended
 *   `start()` resolves, because the close is the outcome its caller asked for.
 * - **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).
+*   `error` is a domain event (a transport-level fault).
 *
 * @example
 * ```ts
@@ -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
@@ -1634,14 +1237,14 @@ var WebSocketClientTransport = class {
 *   line is decoded and delivered through the shared {@link dispatchLines} helper — a well-formed
 *   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (never throws).
 * - **Outbound (`send`).** `send(message)` writes one newline-terminated `JSON.stringify`d line
-*   through the supervisor's `send` and AWAITS its answer, so this promise settles only after the
+*   through the supervisor's `send` and awaits its answer, so this promise settles only after the
 *   host reports the line handled rather than the moment the write is queued. The supervisor never
 *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, for a write
 *   that failed, or for one that remained unconfirmed through `delivery`. A call made without a
 *   live child rejects as not connected; a `false` answer from a live child rejects as unable to
 *   deliver. The supervisor does not disclose which cause produced that answer.
 * - **`close()`** runs the supervisor's bounded termination and teardown, then fires `close` once
-*   (idempotent). That teardown reaches the child's TERMINAL MOMENT, where the supervisor freezes
+*   (idempotent). That teardown reaches the child's terminal moment, where the supervisor freezes
 *   `evidence`, ends `lines`, and settles `exit` together, so this transport needs no release of
 *   its own to get its line pump back: the stream ends under the pump rather than throwing at it.
 *   A line the supervisor had already framed behind the one being delivered is dropped rather than
@@ -1654,15 +1257,15 @@ var WebSocketClientTransport = class {
 *   child's own process group `SIGTERM`, waits the grace window, then `SIGKILL`s through the same
 *   route, so the kill reaches grandchildren rather than orphaning them, while Windows ends the
 *   tree with `taskkill /F /T`, which nothing in the child can intercept.
-* - **Evidence.** `evidence` reports that retained stderr tail off the HELD child — its live tail
+* - **Evidence.** `evidence` reports that retained stderr tail off the held child — its live tail
 *   while the child runs, and the value the supervisor froze at that child's terminal moment
 *   afterwards. The reference is held past that moment and replaced only by the next `start()`,
 *   which is what keeps a post-`close()` read stable without a private copy: the frozen value
 *   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
-*   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
+* - **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
 *   listener-error channel.
@@ -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
@@ -1807,7 +1409,7 @@ var StdioClientTransport = class {
 * - **`close()`** removes this transport's input and output subscriptions, rejects every
 *   pending send, and fires its `close`
 *   event (idempotent). It pauses the input only when the caller was not already reading
-*   it at `start` (`readableFlowing !== true`) AND no `data` listener remains once this
+*   it at `start` (`readableFlowing !== true`) and no `data` listener remains once this
 *   transport's own is removed — so a process holding `process.stdin` can exit, and a
 *   caller's own flow is never stopped underneath it. The transport preserves flowing versus
 *   non-flowing state and restores every caller-owned listener. A Node stream that had never been
@@ -1817,8 +1419,8 @@ 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
-*   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
+* - **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.
 */
 var StdioServerTransport = class {
@@ -1923,20 +1525,101 @@ 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 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
 * hand to `router.add(...)`.
 *
 * @remarks
-* A SINGLE `POST {path}` route — `createMCPRoutes` is STATELESS. The handler reads its own
+* A single `POST {path}` route — `createMCPRoutes` is stateless. The handler reads its own
 * request body (its own JSON parse try/catch), so it works with or without a session
 * middleware mounted in front. It draws a sharp line between TRANSPORT-level and
 * DISPATCH-level outcomes:
 *
 * - A **transport** failure — a malformed JSON body, or a parsed value that is not a
-*   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.
+*   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.
@@ -1948,16 +1631,16 @@ 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
-* import('./middlewares.js').createMCPSession} IN FRONT — it owns the same `path`, mints +
+* **Sessions are a separate, plug-and-play middleware.** `createMCPRoutes` mints / reads no
+* session id. To make the transport stateful, mount {@link
+* import('./middlewares.js').createMCPSession} in front — it owns the same `path`, mints +
 * validates the `mcp-session-id`, and serves the resumable `GET {path}` + `DELETE {path}`,
 * leaving this route to dispatch the validated `POST`.
 *
-* This is MECHANISM, not policy: compose auth / rate-limiting (and the session middleware)
-* IN FRONT as ordinary middleware; the optional `origin` group carries the deployment's shared
+* This is mechanism, not policy: compose auth / rate-limiting (and the session middleware)
+* in front as ordinary middleware; the optional `origin` group carries the deployment's shared
 * allowlist or explicitly delegates validation to an upstream layer.
 *
 * @typeParam TState - The consumer's opaque per-request state type
@@ -1986,27 +1669,32 @@ 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
+* Creates the HTTP client transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
+* — 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
+* both `application/json` and `text/event-stream` (the server answers with either — a
 * plain JSON envelope or a Streamable-HTTP SSE `data:` event, decoded with `@orkestrel/sse`),
 * and the reply is surfaced on the transport's `message` event for the client's id
 * correlation. Add `options.headers` (for example, an `Authorization` bearer) to reach a guarded
-* server. `start` / `close` hold no connection; against a STATEFUL server it captures the
+* server. `start` / `close` hold no connection; against a stateful server it captures the
 * `mcp-session-id` from `initialize` and echoes it on later requests. It also captures
 * the initialize result's `protocolVersion` and sends `mcp-protocol-version` alone on each
 * subsequent legacy request. Modern requests derive protocol and method headers directly
 * from the message, plus a name header only for `tools/call`.
 *
-* @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
+* @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
@@ -2024,7 +1712,7 @@ function createHTTPClientTransport(options) {
 	return new HTTPClientTransport(options);
 }
 /**
-* Creates the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
+* Creates the MCP WebSocket transport ingress — an {@link UpgradeHandler} that exposes a
 * transport-agnostic {@link MCPDispatcherInterface} over a WebSocket, the WebSocket mirror of
 * {@link createMCPRoutes}. Register it on the spine's upgrade seam.
 *
@@ -2036,16 +1724,16 @@ function createHTTPClientTransport(options) {
 *   socket to the next handler (or destroys an unclaimed one): the `Upgrade` header is not
 *   `websocket`, the request path is not `options.path` (default {@link DEFAULT_MCP_PATH},
 *   `'/mcp'`), the `Sec-WebSocket-Key` is absent, or the `Sec-WebSocket-Version` is not `13`.
-*   A decline NEVER writes to the socket (it is not yet ours) — the spine owns the unclaimed
+*   A decline never writes to the socket (it is not yet ours) — the spine owns the unclaimed
 *   outcome.
 * - **Claims (returns `true`)** otherwise: it builds `createNodeWebSocket({ socket, key, head,
 *   protocol })` (SERVER mode → writes the `101` handshake, selects the configured subprotocol
-*   only when the client's offer contains it, and sends UNMASKED frames), wraps it in a
+*   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}:
-*   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
+*   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
 *   escaping the (async) message pump.
 * - **Closes on the spine's `stop`.** It holds every socket it claimed and, on `options.emitter`'s
@@ -2056,12 +1744,12 @@ function createHTTPClientTransport(options) {
 *   then have the connection cut mid-protocol. A socket the peer already dropped is gone from
 *   the set (its transport's `close` removes it), and closing a dead one is a no-op either way.
 *
-* It is MECHANISM, not policy: compose an auth guard IN FRONT by registering an upgrade
-* handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
+* It is mechanism, not policy: compose an auth guard in front by registering an upgrade
+* 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 MCPDispatcherInterface} to expose over WebSocket
-* @param options - The spine's `emitter` (REQUIRED — the `stop` event this ingress closes its
+* @param options - The spine's `emitter` (required — the `stop` event this ingress closes its
 *   sockets on), plus 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
@@ -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);
@@ -2114,8 +1802,8 @@ 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
+* Creates the WebSocket client transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
+* — 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}.
 *
@@ -2129,9 +1817,9 @@ function createWebSocketServer(mcp, options) {
 * surfaced on the transport's `message` event for the client's id correlation. Add
 * `options.headers` (for example, an `Authorization` bearer) to reach a guarded server.
 *
-* @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional `headers`
+* @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
@@ -2149,8 +1837,8 @@ function createWebSocketClientTransport(options) {
 	return new WebSocketClientTransport(options);
 }
 /**
-* Creates the stdio CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
-* — a {@link StdioClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+* Creates the stdio client transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
+* — a {@link StdioClientTransportInterface} 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}.
 *
@@ -2167,7 +1855,7 @@ function createWebSocketClientTransport(options) {
 * waits before the `send` rejects. An omitted `delivery` selects {@link
 * import('./constants.js').DEFAULT_MCP_DELIVERY}; an explicit `0` removes the bound.
 *
-* @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
+* @param options - `command` (the executable to spawn; required), optional `args`,
 *   optional `env`, and an optional `delivery` bound in milliseconds on an unconfirmed
 *   `stdin` write; see {@link StdioClientTransportOptions}
 * @returns A working {@link StdioClientTransportInterface} over a child process's stdio,
@@ -2189,7 +1877,7 @@ function createStdioClientTransport(options) {
 	return new StdioClientTransport(options);
 }
 /**
-* Creates the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
+* Creates the MCP stdio transport ingress — pumps a transport-agnostic {@link
 * MCPDispatcherInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
 * injected stream pair), the stdio mirror of {@link createWebSocketServer}.
 *
@@ -2197,9 +1885,9 @@ 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
-* 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
+* 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
 * surfaces on `mcp.emitter`'s `error` event rather than escaping the (async) message
 * pump.
@@ -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();
@@ -2240,7 +1928,7 @@ function createStdioServer(mcp, options) {
 * Creates the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
 * that fronts a session-agnostic {@link import('./factories.js').createMCPRoutes}. Compose it
 * with `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any
-* other closure-scoped stateful middleware. Has NO dependency on `@orkestrel/middleware` — the
+* other closure-scoped stateful middleware. Has no dependency on `@orkestrel/middleware` — the
 * session store, mint-on-`initialize`, and resumable stream are all native to this package.
 *
 * @remarks
@@ -2253,39 +1941,41 @@ function createStdioServer(mcp, options) {
 *
 * - **`POST {path}`.** Buffers `const text = await request.text()` (so the downstream route
 *   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
+*   readSessionHeader}: a valid id touches the entry and sets `context.state.session`; an
+*   absent / unknown id whose (guarded) body parses to an `initialize` request ({@link
+*   isInitializeRequest}) mints a fresh {@link MCPSession} (`crypto.randomUUID()`, the `session`
+*   options group) and sets `context.state.session`; neither → {@link rejectUnknownSession}
+*   (`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
+*   forwards a fresh `Request` carrying the buffered `text` (`next(forwarded)`) — never the
 *   already-consumed original — so the route re-reads the same body, and stamps the response
-*   with {@link MCP_SESSION_HEADER}. The entry's `touched` instant is read AFTER that
-*   downstream response, because it means the LAST ACCESS: a request slower than `ttl` would
+*   with {@link MCP_SESSION_HEADER}. 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 through `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
-*   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) BEFORE
+*   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.
 * - **`DELETE {path}`.** Resolves the session; a valid id deletes it from the store and answers
 *   `204`; an invalid / unknown id is the same `404`.
 *
-* It is MECHANISM, not policy, and ADDITIVE: omit it entirely for the stateless default
+* It is mechanism, not policy, and additive: omit it entirely for the stateless default
 * ({@link import('./factories.js').createMCPRoutes}'s only behavior). The `path` MUST match the
 * `createMCPRoutes` `path` it fronts. The WebSocket transport is inherently one session per
-* connection (the socket IS the session), so this middleware does not apply to it.
+* connection (the socket is the session), so this middleware does not apply to it.
 *
 * @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