@orkestrel/mcp 0.0.19 → 0.0.20

package/dist/src/server/index.cjs

@@ -10,6 +10,7 @@ let node_https = require("node:https");
 let _orkestrel_websocket = require("@orkestrel/websocket");
 let _orkestrel_process_server = require("@orkestrel/process/server");
 let _orkestrel_process = require("@orkestrel/process");
+let node_stream = require("node:stream");
 //#region src/server/constants.ts
 /**
 * The Streamable-HTTP transport header that carries the MCP session id. When a {@link
@@ -87,7 +88,7 @@ var DEFAULT_MCP_SESSION_TTL = 3e5;
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Create a readable stream from its pull and cancellation behaviours.
+* 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
@@ -100,12 +101,12 @@ function createReadableStream(pull, cancel) {
 	});
 }
 /**
-* Pump a controlled held-open exchange onto an open SSE stream — one `data:` event per
+* Pumps a controlled held-open exchange onto an open SSE stream — one `data:` event per
 * notification in order, then the terminating response — and END the exchange however the
 * pump leaves.
 *
 * @remarks
-* The Streamable-HTTP twin of {@link import('@src/core').sendStream}, and it owns exactly what
+* 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
 * 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
@@ -113,7 +114,7 @@ function createReadableStream(pull, cancel) {
 * The exchange is released BEFORE the body ends, so the slot is already back when the response
 * completes.
 *
-* Total (§14) — never throws and never rejects. A held-open SSE response has already sent its
+* Total — never throws and never rejects. A held-open SSE response has already sent its
 * headers and part of its body, so there is no failure the transport could still convert into
 * a different answer; the honest end of a broken stream is a closed one, and the fault itself
 * is already legible on `server.emitter`'s `error` event, which is where a contained fault
@@ -195,7 +196,7 @@ function allowsOrigin(request, options) {
 	return options?.origins?.includes(parsed.origin) ?? false;
 }
 /**
-* Read the request's `mcp-session-id` header — the session id a stateful transport
+* Reads the request's `mcp-session-id` header — the session id a stateful transport
 * validates, or `undefined` when absent.
 *
 * @remarks
@@ -213,7 +214,7 @@ function readSessionHeader(request) {
 	return id === null ? void 0 : id;
 }
 /**
-* Read the request's `Last-Event-ID` header — the SSE resume cursor a client sends when it
+* Reads the request's `Last-Event-ID` header — the SSE resume cursor a client sends when it
 * reconnects to the resumable `GET {path}` stream, or `undefined` when absent.
 *
 * @remarks
@@ -231,7 +232,7 @@ function readLastEventId(request) {
 	return id === null ? void 0 : id;
 }
 /**
-* Build the stateful transport's "unknown session" rejection — an HTTP `404` carrying a
+* Builds the stateful transport's "unknown session" rejection — an HTTP `404` carrying a
 * JSON-RPC error body.
 *
 * @remarks
@@ -249,16 +250,16 @@ function rejectUnknownSession() {
 	return Response.json((0, _src_core.buildJSONRPCError)(void 0, _src_core.JSONRPC_INVALID_REQUEST, "Session not found"), { status: 404 });
 }
 /**
-* Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
+* 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} via
+* 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, §14). It reuses the SAME `SSEParser` the server's `openStream` seam
+* 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
@@ -289,13 +290,13 @@ async function readEventStream(response) {
 	return messages;
 }
 /**
-* Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
+* 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 (§14): malformed JSON or a non-message value yields `undefined`, never throws.
+* 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`
@@ -308,13 +309,13 @@ function decodeEvent(data) {
 	}
 }
 /**
-* Read the path (without the query string) of a raw `node:http` protocol-upgrade request —
+* 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
-* (`'/mcp?x=1'`), narrowed with `isString` (§14, never `as`) and defaulting to `'/'` for an
-* absent target; it is parsed against a dummy base (only the pathname matters for the upgrade
+* (`'/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
 * configured `path` to decide whether to claim the socket. Total — never throws on an
 * adversarial / absent target.
@@ -327,7 +328,7 @@ function upgradeRequestPath(request) {
 	return new URL(target, "http://localhost").pathname;
 }
 /**
-* Fold one more chunk of raw stdio bytes into a newline-framed buffer — the shared
+* Folds one more chunk of raw stdio bytes into a newline-framed buffer — the shared
 * line-framing step both stdio transports (client and server) read their inbound
 * newline-delimited JSON-RPC messages through.
 *
@@ -352,19 +353,20 @@ function extractLines(buffer, chunk) {
 	};
 }
 /**
-* Decode and deliver each complete newline-framed line onto a {@link
+* Decodes and delivers each complete newline-framed line onto a {@link
 * MCPClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
-* transports (client and server) run their {@link extractLines} output through.
+* 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` (§14 — total, never throws). Pure w.r.t. its own state — the emit is
+* emits `error` (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 (from {@link extractLines}) to decode and deliver
+* @param lines - The complete lines to decode and deliver
 */
 function dispatchLines(emitter, lines) {
 	for (const line of lines) {
@@ -378,17 +380,17 @@ function dispatchLines(emitter, lines) {
 	}
 }
 /**
-* Bridge a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
+* Bridges a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
 * WebSocket SERVER transports already implement) into the environment-agnostic
-* {@link import('@src/core').MCPTransportInterface} port — the adapter
+* {@link import('@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 two factories used to hand-roll identically now
+* 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 via `transport.send` (the SAME `JSON.stringify` the underlying
+* 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
@@ -406,24 +408,24 @@ function dispatchLines(emitter, lines) {
 * decode rather than after it. Removing the cost means giving `MCPTransportInterface` a
 * message-shaped face beside its string one, which every transport would then carry.
 *
-* @remarks Per {@link import('@src/core').MCPTransportInterface}, `listen`/`closed`
+* @remarks Per {@link import('@orkestrel/mcp').MCPTransportInterface}, `listen`/`closed`
 * each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
-* Since the underlying `transport.emitter` is ADD-based (`on` subscribes, never
+* 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 CURRENTLY registered (`undefined` while
+* 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 (e.g. `undefined`) is dropped by
+* @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, since both round-trip through `JSON.stringify`
+* 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('@src/core').MCPTransportInterface} `bindServer` can drive
+* @returns An {@link import('@orkestrel/mcp').MCPTransportInterface} `bindServer` can drive
 *
 * @example
 * ```ts
-* import { bindServer } from '@src/core'
+* import { bindServer } from '@orkestrel/mcp'
 *
 * const transport = new StdioServerTransport(process.stdin, process.stdout)
 * bindServer(mcp, bridgeMessageTransport(transport))
@@ -459,7 +461,7 @@ function bridgeMessageTransport(transport) {
 //#endregion
 //#region src/server/inferers.ts
 /**
-* Infer the first required MCP HTTP header that is missing or mismatched.
+* Infers the first required MCP HTTP header that is missing or mismatched.
 *
 * @remarks
 * A modern request derives its protocol, method, and tools/call-only name expectations from
@@ -540,7 +542,7 @@ function inferHeaderIssue(request, reference) {
 	};
 }
 /**
-* Infer the legacy revision an `initialize` request negotiates.
+* Infers the legacy revision an `initialize` request negotiates.
 *
 * @remarks
 * A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
@@ -556,7 +558,7 @@ function inferLegacyVersion(request) {
 	return _src_core.MCP_PROTOCOL_VERSION;
 }
 /**
-* Infer the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
+* Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
 *
 * @remarks
 * Notifications are accepted with `202`. Legacy response envelopes retain uniform `200`
@@ -578,7 +580,7 @@ function inferStatus(response, era) {
 //#endregion
 //#region src/server/transports/HTTPDisconnect.ts
 /**
-* Compose one incoming HTTP request lifetime with one MCP-owned SSE response lifetime.
+* 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
@@ -592,7 +594,8 @@ function inferStatus(response, era) {
 *
 * {@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.
+* 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.
 * It supplies no handler or session policy.
 *
 * The keepalive interval is a BUDGET, sanitized like every other numeric knob in this package:
@@ -617,9 +620,10 @@ var HTTPDisconnect = class {
 	#interval;
 	#signal;
 	#timer;
+	#bridged = false;
 	#pulling = false;
 	/**
-	* Create the lifecycle composition for one request and its future SSE response.
+	* Creates the lifecycle composition for one request and its future SSE response.
 	*
 	* @param signal - The incoming request signal
 	* @param options - Optional keepalive `interval` in milliseconds; an invalid value falls back
@@ -640,7 +644,7 @@ var HTTPDisconnect = class {
 		return this.#signal;
 	}
 	/**
-	* Bridge one open SSE response through cancellation-aware byte forwarding and keepalives.
+	* Bridges one open SSE response through cancellation-aware byte forwarding and keepalives.
 	*
 	* Consumer cancellation, a read failure while forwarding, and a keepalive tick that finds the
 	* SSE stream already closed each abort {@link signal}; consumer cancellation also cancels the
@@ -649,9 +653,12 @@ var HTTPDisconnect = class {
 	*
 	* @param stream - The open SSE stream whose response will be consumed by the HTTP writer
 	* @returns A one-use response preserving status, status text, headers, and SSE body bytes
-	* @throws When the supplied SSE response has no body
+	* @throws When this disconnect has already bridged a stream, or the supplied SSE response
+	*   has no body
 	*/
 	bridge(stream) {
+		if (this.#bridged) throw new Error("MCP SSE response is already bridged");
+		this.#bridged = true;
 		const response = stream.response;
 		const body = response.body;
 		if (body === null) throw new Error("MCP SSE response has no body");
@@ -705,7 +712,7 @@ var HTTPDisconnect = class {
 //#endregion
 //#region src/server/handlers.ts
 /**
-* Create the Streamable-HTTP POST handler used by `createMCPRoutes`.
+* Creates the Streamable-HTTP POST handler used by `createMCPRoutes`.
 *
 * @remarks
 * Modern requests require matching protocol/method headers and a matching name header only
@@ -731,7 +738,7 @@ var HTTPDisconnect = class {
 * import { createToolManager } from '@orkestrel/tool'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
-* const handler = createMCPPostHandler(createMCPLegacy(mcp), { streaming: true })
+* const handler = createMCPPostHandler(createMCPLegacy(mcp), { streaming: true }) // answers `initialize` too; pass `mcp` alone for modern-only
 * await handler(new Request('http://localhost/mcp', {
 * 	method: 'POST',
 * 	body: '{"jsonrpc":"2.0","method":"ping","id":1}',
@@ -806,12 +813,12 @@ function createMCPPostHandler(mcp, options) {
 * - **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` (e.g. an `Authorization`
+*   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('@src/core').MCPClientInterface} subscribes
+*   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 via the
+*   `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`
@@ -829,10 +836,15 @@ function createMCPPostHandler(mcp, options) {
 *   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()`.
-* - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
+* - **`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 reply is dropped, never asserted; a `fetch` /
 *   decode failure surfaces on the `error` event rather than escaping `send`.
-* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
+* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
 *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
 *
 * @example
@@ -848,8 +860,10 @@ var HTTPClientTransport = class {
 	#headers;
 	#fetch;
 	#timeout;
+	#pending = /* @__PURE__ */ new Set();
 	#session = void 0;
 	#protocol = void 0;
+	#closed = false;
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter();
 		this.#url = options.url;
@@ -866,8 +880,19 @@ var HTTPClientTransport = class {
 	get duplex() {
 		return false;
 	}
-	async start() {}
+	async start() {
+		this.#closed = false;
+	}
 	async send(message) {
+		const request = new AbortController();
+		this.#pending.add(request);
+		try {
+			await this.#exchange(message, request.signal);
+		} finally {
+			this.#pending.delete(request);
+		}
+	}
+	async #exchange(message, signal) {
 		let response;
 		try {
 			response = await this.#fetch(this.#url, {
@@ -880,7 +905,7 @@ var HTTPClientTransport = class {
 					...this.#headers
 				},
 				body: JSON.stringify(message),
-				...this.#timeout === void 0 ? {} : { signal: AbortSignal.timeout(this.#timeout) }
+				signal: this.#timeout === void 0 ? signal : AbortSignal.any([signal, AbortSignal.timeout(this.#timeout)])
 			});
 		} catch (error) {
 			this.#emitter.emit("error", error);
@@ -891,6 +916,10 @@ var HTTPClientTransport = class {
 		await this.#deliver(response);
 	}
 	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");
 	}
@@ -938,8 +967,8 @@ var HTTPClientTransport = class {
 * 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
 * resumable GET-SSE channel — a private `#events` `Map` + a monotone `#counter`, with
-* `capacity` / `ttl` eviction, NOT a separate store), and the set of currently OPEN
-* server→client SSE streams (a resumable `GET {path}` registers via `attach`, unregisters via
+* `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
@@ -959,7 +988,7 @@ var HTTPClientTransport = class {
 *   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` (§21).** The log lives in ONE insertion-ordered
+* - **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`
@@ -973,8 +1002,8 @@ var HTTPClientTransport = class {
 *   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
-*   (AGENTS §16).
+*   `Date.now()` — so a test drives TTL eviction with an elapsed clock rather than a real
+*   timer.
 *
 * @example
 * ```ts
@@ -1055,7 +1084,7 @@ var MCPSession = class {
 * {@link import('./WebSocketClientTransport.js').WebSocketClientTransport} reuses.
 *
 * @remarks
-* - **Reuses `MCPClientTransportInterface` (§21).** It IS the same generic carrier the HTTP
+* - **Reuses `MCPClientTransportInterface`.** It IS the same generic carrier the HTTP
 *   client transport implements — `emitter` (`message` / `close` / `error`), `start`,
 *   `send`, `close` — so the WebSocket server and client both speak ONE transport contract,
 *   no near-duplicate sibling interface. `session` is `undefined` (the stateless v1; a
@@ -1064,22 +1093,27 @@ var MCPSession = class {
 * - **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
 *   well-formed {@link JSONRPCMessage} is re-emitted on this transport's `message` event (the
-*   parsed envelope the {@link import('@src/core').MCPServerInterface} pump dispatches), while
-*   a non-JSON or non-message frame is surfaced on `error` and DROPPED, never thrown (§14). It
+*   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
 *   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, so a closed connection drops silently rather than throwing.
-* - **`close()`** closes the underlying socket (the RFC 6455 close handshake) and fires the
-*   transport's `close` event (idempotent — a second `close`, or a socket-driven close, emits
-*   once).
-* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the emitter
+* - **`close()`** removes the subscriptions `start()` installed on the socket, closes the
+*   underlying socket (the RFC 6455 close handshake), and fires the transport's `close` event
+*   (idempotent — a second `close`, or a socket-driven close, emits once). 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
 *   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.
 */
 var WebSocketServerTransport = class {
 	#emitter;
 	#socket;
+	#frame = (text) => this.#receive(text);
+	#ending = () => this.#onClose();
+	#failure = (error) => this.#emitter.emit("error", error);
 	#started = false;
 	#closed = false;
 	constructor(socket) {
@@ -1096,9 +1130,9 @@ var WebSocketServerTransport = class {
 	async start() {
 		if (this.#started || this.#closed) return;
 		this.#started = true;
-		this.#socket.emitter.on("message", (text) => this.#receive(text));
-		this.#socket.emitter.on("close", () => this.#onClose());
-		this.#socket.emitter.on("error", (error) => this.#emitter.emit("error", error));
+		this.#socket.emitter.on("message", this.#frame);
+		this.#socket.emitter.on("close", this.#ending);
+		this.#socket.emitter.on("error", this.#failure);
 	}
 	async send(message) {
 		this.#socket.send(JSON.stringify(message));
@@ -1106,6 +1140,7 @@ var WebSocketServerTransport = class {
 	async close() {
 		if (this.#closed) return;
 		this.#closed = true;
+		this.#release();
 		this.#socket.close();
 		this.#emitter.emit("close");
 	}
@@ -1127,8 +1162,14 @@ var WebSocketServerTransport = class {
 	#onClose() {
 		if (this.#closed) return;
 		this.#closed = true;
+		this.#release();
 		this.#emitter.emit("close");
 	}
+	#release() {
+		this.#socket.emitter.off("message", this.#frame);
+		this.#socket.emitter.off("close", this.#ending);
+		this.#socket.emitter.off("error", this.#failure);
+	}
 };
 //#endregion
 //#region src/server/transports/WebSocketClientTransport.ts
@@ -1146,7 +1187,8 @@ var WebSocketServerTransport = class {
 *   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 §5.3) and bridges its `message`.
+*   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
@@ -1155,15 +1197,18 @@ var WebSocketServerTransport = class {
 *   `start()` calls still resolve; exactly one socket is ever bound.
 * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and narrowed
 *   with `parseJSONRPCMessage` — a {@link JSONRPCMessage} re-emits on this transport's `message`
-*   event (the reply the {@link import('@src/core').MCPClientInterface} correlates by `id`); a
-*   non-JSON / non-message frame surfaces on `error` and is dropped (§14). The socket's `close`
+*   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.
-* - **`close()`** closes the underlying socket and fires `close` (idempotent).
+* - **`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
+*   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 via `node:https`). Either reaches the same endpoint.
-* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
+*   → TLS through `node:https`). Either reaches the same endpoint.
+* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
 *   the emitter isolates a listener throw (a buggy observer never corrupts the transport);
 *   `error` is a DOMAIN event (a transport-level fault).
 *
@@ -1178,7 +1223,11 @@ var WebSocketClientTransport = class {
 	#emitter;
 	#url;
 	#headers;
+	#frame = (text) => this.#receive(text);
+	#ending = () => this.#onClose();
+	#failure = (error) => this.#emitter.emit("error", error);
 	#socket = void 0;
+	#request = void 0;
 	#closed = false;
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter();
@@ -1195,8 +1244,28 @@ var WebSocketClientTransport = class {
 	async start() {
 		if (this.#socket !== void 0) return;
 		this.#closed = false;
-		const url = this.#httpURL();
-		const key = (0, node_crypto.randomBytes)(16).toString("base64");
+		try {
+			await this.#connect(this.#httpURL(), (0, node_crypto.randomBytes)(16).toString("base64"));
+		} finally {
+			this.#request = void 0;
+		}
+	}
+	async send(message) {
+		const socket = this.#socket;
+		if (socket === void 0) throw new Error("WebSocket transport is not connected");
+		socket.send(JSON.stringify(message));
+	}
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#request?.destroy();
+		const socket = this.#socket;
+		this.#release();
+		this.#socket = void 0;
+		if (socket !== void 0) socket.close();
+		this.#emitter.emit("close");
+	}
+	async #connect(url, key) {
 		const secure = url.protocol === "https:";
 		const send = secure ? node_https.request : node_http.request;
 		await new Promise((resolve, reject) => {
@@ -1213,6 +1282,7 @@ var WebSocketClientTransport = class {
 					...this.#headers
 				}
 			});
+			this.#request = request;
 			request.on("upgrade", (response, socket, head) => {
 				const accept = response.headers["sec-websocket-accept"];
 				if (!(0, _orkestrel_contract.isString)(accept) || accept !== (0, _orkestrel_websocket.computeWebSocketAccept)(key)) {
@@ -1237,27 +1307,27 @@ var WebSocketClientTransport = class {
 				response.resume();
 				reject(/* @__PURE__ */ new Error(`WebSocket upgrade declined with status ${response.statusCode ?? 0}`));
 			});
-			request.on("error", (error) => reject(error instanceof Error ? error : new Error(String(error))));
+			request.on("error", (error) => {
+				if (this.#closed) {
+					resolve();
+					return;
+				}
+				reject(error instanceof Error ? error : new Error(String(error)));
+			});
 			request.end();
 		});
 	}
-	async send(message) {
-		const socket = this.#socket;
-		if (socket === void 0) throw new Error("WebSocket transport is not connected");
-		socket.send(JSON.stringify(message));
+	#bind(ws) {
+		ws.emitter.on("message", this.#frame);
+		ws.emitter.on("close", this.#ending);
+		ws.emitter.on("error", this.#failure);
 	}
-	async close() {
-		if (this.#closed) return;
-		this.#closed = true;
+	#release() {
 		const socket = this.#socket;
-		this.#socket = void 0;
-		if (socket !== void 0) socket.close();
-		this.#emitter.emit("close");
-	}
-	#bind(ws) {
-		ws.emitter.on("message", (text) => this.#receive(text));
-		ws.emitter.on("close", () => this.#onClose(ws));
-		ws.emitter.on("error", (error) => this.#emitter.emit("error", error));
+		if (socket === void 0) return;
+		socket.emitter.off("message", this.#frame);
+		socket.emitter.off("close", this.#ending);
+		socket.emitter.off("error", this.#failure);
 	}
 	#receive(text) {
 		let parsed;
@@ -1274,9 +1344,10 @@ var WebSocketClientTransport = class {
 		}
 		this.#emitter.emit("message", message);
 	}
-	#onClose(socket) {
-		if (this.#closed || this.#socket !== socket) return;
+	#onClose() {
+		if (this.#closed) return;
 		this.#closed = true;
+		this.#release();
 		this.#socket = void 0;
 		this.#emitter.emit("close");
 	}
@@ -1305,19 +1376,21 @@ var WebSocketClientTransport = class {
 * - **Inbound (`message`).** Standard output is drained eagerly through the supervisor's
 *   `readline`-framed `lines` iterable, so a multi-byte UTF-8 sequence split across two reads is
 *   decoded whole and a final line written without a trailing newline still arrives. Each framed
-*   line is decoded and delivered via the shared {@link dispatchLines} helper — a well-formed
-*   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (§14, never throws).
+*   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
 *   host reports the line handled rather than the moment the write is queued. The supervisor never
 *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, and for a write
 *   that failed — so a `false` answer REJECTS here with the same not-connected error a transport
 *   that was never started raises. A dead peer surfaces at the caller instead of vanishing.
-* - **`close()`** terminates the child through the supervisor's bounded `SIGTERM` → grace →
-*   `SIGKILL` group-kill, awaits its observed exit, tears down the supervisor, and fires `close`
-*   once (idempotent). On a POSIX host the child leads its own process group, so the group-kill
-*   reaches its grandchildren rather than orphaning them.
-* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
+* - **`close()`** releases this transport's line pump without waiting for the child's stdout
+*   iterator, then runs the supervisor's bounded `SIGTERM` → grace → `SIGKILL` group-kill and
+*   teardown before firing `close` once (idempotent). A descendant can retain an inherited stdout
+*   pipe after the child exits; the pump's release barrier keeps that substrate limit from keeping
+*   this transport's `close()` pending. On a POSIX host the child leads its own process group, so
+*   the group-kill reaches its grandchildren rather than orphaning them.
+* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
 *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
 *   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
 *   own listener-error channel.
@@ -1335,6 +1408,8 @@ var StdioClientTransport = class {
 	#args;
 	#env;
 	#process = void 0;
+	#release = Promise.withResolvers();
+	#pumping = Promise.resolve();
 	#closed = false;
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter();
@@ -1352,6 +1427,7 @@ var StdioClientTransport = class {
 	async start() {
 		if (this.#process !== void 0) return;
 		this.#closed = false;
+		this.#release = Promise.withResolvers();
 		const child = new _orkestrel_process_server.Process({
 			command: {
 				file: this.#command,
@@ -1365,7 +1441,7 @@ var StdioClientTransport = class {
 		this.#process = child;
 		child.emitter.on("error", (cause) => this.#emitter.emit("error", cause));
 		child.exit.then(() => this.#onExit(child));
-		this.#pump(child);
+		this.#pumping = this.#pump(child, this.#release.promise);
 	}
 	async send(message) {
 		const child = this.#process;
@@ -1375,14 +1451,20 @@ var StdioClientTransport = class {
 		if (this.#closed) return;
 		this.#closed = true;
 		const child = this.#process;
+		const pumping = this.#pumping;
+		this.#release.resolve();
 		this.#process = void 0;
 		if (child !== void 0) await child.destroy();
+		await pumping;
 		this.#emitter.emit("close");
 	}
-	async #pump(child) {
-		for await (const line of child.lines) {
+	async #pump(child, release) {
+		const iterator = child.lines[Symbol.asyncIterator]();
+		while (true) {
+			const next = await Promise.race([iterator.next(), release]);
+			if (next === void 0 || next.done) return;
 			if (this.#process !== child) return;
-			dispatchLines(this.#emitter, [line]);
+			dispatchLines(this.#emitter, [next.value]);
 		}
 	}
 	#onExit(child) {
@@ -1403,22 +1485,31 @@ var StdioClientTransport = class {
 * import('./WebSocketServerTransport.js').WebSocketServerTransport}.
 *
 * @remarks
-* - **Reuses `MCPClientTransportInterface` (§21).** The same generic carrier the HTTP
+* - **Reuses `MCPClientTransportInterface`.** 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
 *   chunk is folded through the shared {@link extractLines} line-framing helper
 *   (buffering a partial trailing line across reads), and every complete line is
-*   decoded and delivered via the shared {@link dispatchLines} helper — a
+*   decoded and delivered through the shared {@link dispatchLines} helper — a
 *   well-formed {@link JSONRPCMessage} re-emits on `message`, a malformed line
-*   emits `error` (§14, never throws). `input`'s `close` bridges to this
+*   emits `error` (never throws). `input`'s `close` bridges to this
 *   transport's `close`.
 * - **Outbound (`send`).** `send(message)` writes one newline-terminated
 *   `JSON.stringify`d line to `output`.
-* - **`close()`** fires this transport's `close` (idempotent) — the injected streams
-*   are owned by the caller (typically `process.stdin`/`process.stdout`, which must
-*   never be closed out from under the process) and are not torn down here.
-* - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
+* - **`close()`** removes this transport's input subscriptions 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
+*   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
+*   read starts with `readableFlowing === null` and is left non-flowing (`false`), because Node
+*   exposes no public operation that restores `null` after data consumption starts. Attaching a
+*   later `data` listener does not resume that stream; the caller must call `resume()` before the
+*   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
 *   fault), distinct from the emitter's own listener-error channel.
 */
@@ -1426,9 +1517,13 @@ var StdioServerTransport = class {
 	#emitter;
 	#input;
 	#output;
+	#data = (chunk) => this.#receive(chunk.toString());
+	#ending = () => this.#onClose();
+	#failure = (error) => this.#emitter.emit("error", error);
 	#buffer = "";
 	#started = false;
 	#closed = false;
+	#flowing = false;
 	constructor(input, output) {
 		this.#emitter = new _orkestrel_emitter.Emitter();
 		this.#input = input;
@@ -1444,9 +1539,10 @@ var StdioServerTransport = class {
 	async start() {
 		if (this.#started || this.#closed) return;
 		this.#started = true;
-		this.#input.on("data", (chunk) => this.#receive(chunk.toString()));
-		this.#input.on("close", () => this.#onClose());
-		this.#input.on("error", (error) => this.#emitter.emit("error", error));
+		this.#flowing = this.#input instanceof node_stream.Readable && this.#input.readableFlowing === true;
+		this.#input.on("data", this.#data);
+		this.#input.on("close", this.#ending);
+		this.#input.on("error", this.#failure);
 	}
 	async send(message) {
 		this.#output.write(`${JSON.stringify(message)}\n`);
@@ -1454,6 +1550,7 @@ var StdioServerTransport = class {
 	async close() {
 		if (this.#closed) return;
 		this.#closed = true;
+		this.#release();
 		this.#emitter.emit("close");
 	}
 	#receive(chunk) {
@@ -1464,13 +1561,20 @@ var StdioServerTransport = class {
 	#onClose() {
 		if (this.#closed) return;
 		this.#closed = true;
+		this.#release();
 		this.#emitter.emit("close");
 	}
+	#release() {
+		this.#input.removeListener("data", this.#data);
+		this.#input.removeListener("close", this.#ending);
+		this.#input.removeListener("error", this.#failure);
+		if (!this.#flowing && this.#input.listenerCount("data") === 0) this.#input.pause();
+	}
 };
 //#endregion
 //#region src/server/factories.ts
 /**
-* Adapt the installed server token primitives to the host-neutral MCP continuation port.
+* Adapts the installed server token primitives to the host-neutral MCP continuation port.
 *
 * @param secret - Current signing secret or `[current, ...older]` rotation list
 * @returns A continuation port that seals and opens opaque canonical state strings
@@ -1486,8 +1590,8 @@ function createMCPContinuation(secret) {
 	};
 }
 /**
-* Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
-* {@link MCPDispatcherInterface} (the `@src/core` dispatch boundary) on the fetch-standard router
+* 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(...)`.
 *
@@ -1510,7 +1614,7 @@ function createMCPContinuation(secret) {
 *
 * When `streaming` is enabled (the default) and the client `Accept`s `text/event-stream`,
 * the `200` reply is framed as a Streamable-HTTP SSE response (one `data:` event carrying
-* the JSON-RPC envelope, then the stream ends) via `@orkestrel/server`'s generic
+* 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.
 *
 * **Sessions are a SEPARATE, plug-and-play middleware.** `createMCPRoutes` mints / reads no
@@ -1532,11 +1636,12 @@ function createMCPContinuation(secret) {
 *
 * @example
 * ```ts
-* import { createMCPLegacy, createMCPServer, createToolManager } from '@src/core'
-* import { createMCPRoutes } from '@src/server'
+* import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+* import { createMCPRoutes } from '@orkestrel/mcp/server'
+* import { createToolManager } from '@orkestrel/tool'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
-* const routes = createMCPRoutes(createMCPLegacy(mcp)) // both eras; pass `mcp` for modern only
+* const routes = createMCPRoutes(createMCPLegacy(mcp)) // answers `initialize` too; pass `mcp` alone for modern-only
 * ```
 */
 function createMCPRoutes(mcp, options) {
@@ -1548,7 +1653,7 @@ function createMCPRoutes(mcp, options) {
 	}];
 }
 /**
-* Create the HTTP CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+* Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
 * — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
 * over `fetch`. The egress mirror of {@link createMCPRoutes}.
 *
@@ -1556,9 +1661,9 @@ function createMCPRoutes(mcp, options) {
 * 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
-* plain JSON envelope or a Streamable-HTTP SSE `data:` event, decoded via `@orkestrel/sse`),
+* 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` (e.g. an `Authorization` bearer) to reach a guarded
+* 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
 * `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
@@ -1567,13 +1672,13 @@ function createMCPRoutes(mcp, options) {
 *
 * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
 *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
-*   (ms, applied via `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
+*   (ms, applied with `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
 * @returns A working {@link MCPClientTransportInterface} over `fetch`
 *
 * @example
 * ```ts
-* import { createMCPClient } from '@src/core'
-* import { createHTTPClientTransport } from '@src/server'
+* import { createMCPClient } from '@orkestrel/mcp'
+* import { createHTTPClientTransport } from '@orkestrel/mcp/server'
 *
 * const client = createMCPClient({
 * 	transport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),
@@ -1586,7 +1691,7 @@ function createHTTPClientTransport(options) {
 	return new HTTPClientTransport(options);
 }
 /**
-* Create 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.
 *
@@ -1601,11 +1706,11 @@ function createHTTPClientTransport(options) {
 *   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, echoing the `subprotocol`, default
-*   {@link MCP_WEBSOCKET_SUBPROTOCOL} `'mcp'`, and sends UNMASKED frames), wraps it in a
+*   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
 *   {@link WebSocketServerTransport}, and pipes it through the core {@link
-*   import('@src/core').MCPTransportInterface} port via {@link
-*   import('./helpers.js').bridgeMessageTransport} + {@link import('@src/core').bindServer}:
+*   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
 *   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
@@ -1630,19 +1735,24 @@ function createHTTPClientTransport(options) {
 *
 * @example
 * ```ts
-* import { createMCPServer, createToolManager } from '@src/core'
-* import { createWebSocketServer } from '@src/server'
+* import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+* import { createWebSocketServer } from '@orkestrel/mcp/server'
+* import { createToolManager } from '@orkestrel/tool'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
-* server.upgrade(createWebSocketServer(mcp, { emitter: server.emitter })) // ws://…/mcp
+* // Claims the MCP upgrade at ws://…/mcp:
+* server.upgrade(createWebSocketServer(createMCPLegacy(mcp), { emitter: server.emitter })) // answers `initialize` too; pass `mcp` alone for modern-only
 * ```
 */
 function createWebSocketServer(mcp, options) {
 	const path = options.path ?? "/mcp";
 	const subprotocol = options.subprotocol ?? "mcp";
-	const live = /* @__PURE__ */ new Set();
+	const live = /* @__PURE__ */ new Map();
 	options.emitter.on("stop", () => {
-		for (const transport of live) transport.close();
+		for (const [transport, unbind] of live) {
+			unbind();
+			transport.close();
+		}
 	});
 	return (request, socket, head) => {
 		const upgrade = request.headers["upgrade"];
@@ -1652,21 +1762,26 @@ function createWebSocketServer(mcp, options) {
 		if (!(0, _orkestrel_contract.isString)(key)) return false;
 		const version = request.headers["sec-websocket-version"];
 		if (!(0, _orkestrel_contract.isString)(version) || version !== _orkestrel_websocket.WEBSOCKET_VERSION) return false;
+		const offer = request.headers["sec-websocket-protocol"];
+		const protocol = (0, _orkestrel_contract.isString)(offer) && offer.split(",").some((candidate) => candidate.trim() === subprotocol) ? subprotocol : void 0;
 		const transport = new WebSocketServerTransport((0, _orkestrel_websocket.createNodeWebSocket)({
 			socket,
 			key,
 			head,
-			protocol: subprotocol
+			...protocol === void 0 ? {} : { protocol }
 		}));
-		live.add(transport);
-		transport.emitter.on("close", () => live.delete(transport));
-		(0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
+		const unbind = (0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
+		live.set(transport, unbind);
+		transport.emitter.on("close", () => {
+			live.delete(transport);
+			unbind();
+		});
 		transport.start();
 		return true;
 	};
 }
 /**
-* Create the WebSocket CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+* 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
 * egress mirror of {@link createWebSocketServer} and the WebSocket sibling of {@link
 * createHTTPClientTransport}.
@@ -1675,11 +1790,11 @@ function createWebSocketServer(mcp, options) {
 * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`) performs
 * the RFC 6455 client handshake against `options.url` (accepting a `ws://` / `wss://` or an
 * `http://` / `https://` URL — a `ws(s)` scheme is converted to `http(s)` for the underlying
-* upgrade request), validates the `Sec-WebSocket-Accept` (via `@orkestrel/websocket`'s
+* upgrade request), validates the `Sec-WebSocket-Accept` (with `@orkestrel/websocket`'s
 * `computeWebSocketAccept`), and opens a persistent bidirectional frame channel; each JSON-RPC
 * message the client `send`s is written as one masked text frame, and each decoded reply is
 * surfaced on the transport's `message` event for the client's id correlation. Add
-* `options.headers` (e.g. an `Authorization` bearer) to reach a guarded server.
+* `options.headers` (for example, an `Authorization` bearer) to reach a guarded server.
 *
 * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional `headers`
 *   merged onto the upgrade request; see {@link WebSocketClientTransportOptions}
@@ -1687,8 +1802,8 @@ function createWebSocketServer(mcp, options) {
 *
 * @example
 * ```ts
-* import { createMCPClient } from '@src/core'
-* import { createWebSocketClientTransport } from '@src/server'
+* import { createMCPClient } from '@orkestrel/mcp'
+* import { createWebSocketClientTransport } from '@orkestrel/mcp/server'
 *
 * const client = createMCPClient({
 * 	transport: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
@@ -1701,7 +1816,7 @@ function createWebSocketClientTransport(options) {
 	return new WebSocketClientTransport(options);
 }
 /**
-* Create the stdio CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+* Creates the stdio CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
 * — a {@link MCPClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
 * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
 * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
@@ -1721,8 +1836,8 @@ function createWebSocketClientTransport(options) {
 *
 * @example
 * ```ts
-* import { createMCPClient } from '@src/core'
-* import { createStdioClientTransport } from '@src/server'
+* import { createMCPClient } from '@orkestrel/mcp'
+* import { createStdioClientTransport } from '@orkestrel/mcp/server'
 *
 * const client = createMCPClient({
 * 	transport: createStdioClientTransport({ command: 'node', args: ['./server.js'] }),
@@ -1735,16 +1850,16 @@ function createStdioClientTransport(options) {
 	return new StdioClientTransport(options);
 }
 /**
-* Create 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}.
 *
 * @remarks
 * 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('@src/core').MCPTransportInterface} port
-* via {@link import('./helpers.js').bridgeMessageTransport} + {@link
-* import('@src/core').bindServer}: each inbound REQUEST runs through `mcp.dispatch`, and
+* 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
 * 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
@@ -1757,21 +1872,24 @@ function createStdioClientTransport(options) {
 *
 * @example
 * ```ts
-* import { createMCPServer, createToolManager } from '@src/core'
-* import { createStdioServer } from '@src/server'
+* import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+* import { createStdioServer } from '@orkestrel/mcp/server'
+* import { createToolManager } from '@orkestrel/tool'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
-* createStdioServer(mcp).start() // an MCP client now connects over this process's stdio
+* // An MCP client now connects over this process's stdio:
+* createStdioServer(createMCPLegacy(mcp)).start() // answers `initialize` too; pass `mcp` alone for modern-only
 * ```
 */
 function createStdioServer(mcp, options) {
 	const transport = new StdioServerTransport(options?.input ?? process.stdin, options?.output ?? process.stdout);
-	(0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
+	const unbind = (0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
 	return {
 		start() {
 			transport.start();
 		},
 		stop() {
+			unbind();
 			transport.close();
 		}
 	};
@@ -1779,9 +1897,9 @@ function createStdioServer(mcp, options) {
 //#endregion
 //#region src/server/middlewares.ts
 /**
-* Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
+* 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
-* via `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any
+* with `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any
 * 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.
 *
@@ -1790,11 +1908,11 @@ function createStdioServer(mcp, options) {
 * `path` (default {@link DEFAULT_MCP_PATH}); a request to any other path passes straight
 * through (`next()`).
 *
-* A modern-shaped POST also passes straight through via `next()`, ignoring any session id.
+* A modern-shaped POST also passes straight through with `next()`, ignoring any session id.
 * The remaining behavior is the legacy session layer:
 *
 * - **`POST {path}`.** Buffers `const text = await request.text()` (so the downstream route
-*   can re-read it via a freshly-built forwarded `Request`). Resolves a session via {@link
+*   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`)
@@ -1809,7 +1927,7 @@ function createStdioServer(mcp, options) {
 *   a `DELETE` arriving while the request was suspended is not undone.
 * - **`GET {path}`.** Resolves the session the same way (no mint — only `initialize` mints);
 *   an invalid / unknown id is the same `404`. A valid session opens the resumable
-*   server→client stream via `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
+*   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
 *   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.
@@ -1833,12 +1951,14 @@ function createStdioServer(mcp, options) {
 *
 * @example
 * ```ts
-* import { createMCPServer, createToolManager } from '@src/core'
-* import { createMCPRoutes, createMCPSession } from '@src/server'
+* import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+* import { createMCPRoutes, createMCPSession } from '@orkestrel/mcp/server'
+* import { createToolManager } from '@orkestrel/tool'
 *
 * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
 * router.use(createMCPSession({ ttl: 60_000 })) // stateful: mint + validate + resumable GET / DELETE
-* router.add(createMCPRoutes(mcp)) // the route stays session-agnostic
+* // The route stays session-agnostic:
+* router.add(createMCPRoutes(createMCPLegacy(mcp))) // answers `initialize` too; pass `mcp` alone for modern-only
 * ```
 */
 function createMCPSession(options) {