@orkestrel/mcp 0.0.11 → 0.0.13

package/dist/src/server/index.d.cts

@@ -1,22 +1,25 @@
-import { ClientTransportEventMap } from '../core/index.ts';
-import { ClientTransportEventMap as ClientTransportEventMap_2 } from '../../core/index.ts';
-import { ClientTransportInterface } from '../core/index.ts';
-import { ClientTransportInterface as ClientTransportInterface_2 } from '../../core/index.ts';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { IncomingMessage } from 'node:http';
-import { JSONRPCMessage } from '../core/index.ts';
-import { JSONRPCMessage as JSONRPCMessage_2 } from '../../core/index.ts';
-import { JSONRPCRequest } from '../core/index.ts';
-import { JSONRPCResponse } from '../core/index.ts';
-import { MCPEra } from '../core/index.ts';
-import { MCPServerInterface } from '../core/index.ts';
-import { MCPTransportInterface } from '../core/index.ts';
-import { MCPVersion } from '../core/index.ts';
+import { JSONRPCInvocation } from '@orkestrel/mcp';
+import { JSONRPCMessage } from '@orkestrel/mcp';
+import { JSONRPCMessage as JSONRPCMessage_2 } from '@orkestrel/mcp';
+import { JSONRPCResponse } from '@orkestrel/mcp';
+import { MCPClientTransportEventMap } from '@orkestrel/mcp';
+import { MCPClientTransportEventMap as MCPClientTransportEventMap_2 } from '@orkestrel/mcp';
+import { MCPClientTransportInterface } from '@orkestrel/mcp';
+import { MCPClientTransportInterface as MCPClientTransportInterface_2 } from '@orkestrel/mcp';
+import { MCPContinuationInterface } from '@orkestrel/mcp';
+import { MCPDispatcherInterface } from '@orkestrel/mcp';
+import { MCPEra } from '@orkestrel/mcp';
+import { MCPStreamControllerInterface } from '@orkestrel/mcp';
+import { MCPTransportInterface } from '@orkestrel/mcp';
+import { MCPVersion } from '@orkestrel/mcp';
 import { MiddlewareHandler } from '@orkestrel/server';
 import { NodeWebSocketInterface } from '@orkestrel/websocket';
 import { RouteContext } from '@orkestrel/router';
 import { RouteInput } from '@orkestrel/router';
 import { StreamInterface } from '@orkestrel/server';
+import { TokenSecret } from '@orkestrel/server';
 import { UpgradeHandler } from '@orkestrel/server';
 
 /**
@@ -51,7 +54,7 @@ export declare function acceptsEventStream(request: Request): boolean;
 export declare function allowsOrigin(request: Request, options?: MCPOriginOptions): boolean;
 
 /**
- * Bridge a message-channel {@link ClientTransportInterface} (the shape the stdio and
+ * Bridge a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
  * WebSocket SERVER transports already implement) into the environment-agnostic
  * {@link import('@src/core').MCPTransportInterface} port — the adapter
  * {@link import('./factories.js').createStdioServer} and {@link
@@ -63,11 +66,22 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
  * `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
  * and writes it via `transport.send` (the SAME `JSON.stringify` the underlying
  * transport already performs, so the wire bytes are unchanged). `listen` filters
- * `transport`'s `message` event to REQUESTS ONLY — a stray response is ignored,
- * exactly as the prior hand-rolled pumps did — and re-serializes each one back to a
- * string for `bindServer`. `closed` bridges `transport`'s `close` event. `close`
+ * `transport`'s `message` event to INVOCATIONS ONLY — requests and notifications, never a
+ * stray response, exactly as the prior hand-rolled pumps did — and re-serializes each one
+ * back to a string for `bindServer`. `closed` bridges `transport`'s `close` event. `close`
  * closes the underlying `transport`.
  *
+ * @remarks A message crossing this bridge is decoded and re-encoded TWICE, and that is
+ * ACCEPTED rather than accidental. Inbound: the carrier already parsed the frame into a
+ * {@link JSONRPCMessage}, and `listen` re-serializes it so `bindServer` can decode it again
+ * under the server's own `limit`. Outbound: `bindServer` serialized the reply, `send` parses
+ * it back, and the carrier stringifies it once more. The cost is two extra `JSON.parse` /
+ * `JSON.stringify` round trips per message, paid to keep ONE pump in the core binder instead
+ * of a hand-rolled one per carrier. It is BOUNDED rather than unbounded because the binder
+ * decodes within `server.limit.message`, so an oversized frame is refused before the second
+ * decode rather than after it. Removing the cost means giving `MCPTransportInterface` a
+ * message-shaped face beside its string one, which every transport would then carry.
+ *
  * @remarks Per {@link import('@src/core').MCPTransportInterface}, `listen`/`closed`
  * each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
  * Since the underlying `transport.emitter` is ADD-based (`on` subscribes, never
@@ -91,11 +105,11 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
  * bindServer(mcp, bridgeMessageTransport(transport))
  * ```
  */
-export declare function bridgeMessageTransport(transport: ClientTransportInterface): MCPTransportInterface;
+export declare function bridgeMessageTransport(transport: MCPClientTransportInterface): MCPTransportInterface;
 
 /**
  * Create the HTTP CLIENT transport for an {@link import('@src/core').MCPClientInterface}
- * — a {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
+ * — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
  * over `fetch`. The egress mirror of {@link createMCPRoutes}.
  *
  * @remarks
@@ -114,7 +128,7 @@ export declare function bridgeMessageTransport(transport: ClientTransportInterfa
  * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
  *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
  *   (ms, applied via `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
- * @returns A working {@link ClientTransportInterface} over `fetch`
+ * @returns A working {@link MCPClientTransportInterface} over `fetch`
  *
  * @example
  * ```ts
@@ -128,7 +142,15 @@ export declare function bridgeMessageTransport(transport: ClientTransportInterfa
  * const tools = await client.tools()
  * ```
  */
-export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): ClientTransportInterface;
+export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): MCPClientTransportInterface;
+
+/**
+ * Adapt the installed server token primitives to the host-neutral MCP continuation port.
+ *
+ * @param secret - Current signing secret or `[current, ...older]` rotation list
+ * @returns A continuation port that seals and opens opaque canonical state strings
+ */
+export declare function createMCPContinuation(secret: TokenSecret): MCPContinuationInterface;
 
 /**
  * Create the Streamable-HTTP POST handler used by `createMCPRoutes`.
@@ -146,29 +168,29 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * defined value is added to `MCPDispatchOptions`, while `undefined` is omitted.
  *
  * @typeParam TState - The consumer's opaque per-request route state type
- * @param mcp - The transport-agnostic MCP server to dispatch through
+ * @param mcp - The transport-agnostic MCP dispatcher to dispatch through
  * @param options - Optional streaming, origin-validation, SSE keepalive, and caller-extraction options
  * @returns A request handler for the stateless MCP POST route
  *
  * @example
  * ```ts
- * import { createMCPServer } from '@orkestrel/mcp'
+ * import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
  * import { createMCPPostHandler } from '@orkestrel/mcp/server'
  * import { createToolManager } from '@orkestrel/tool'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * const handler = createMCPPostHandler(mcp, { streaming: true })
+ * const handler = createMCPPostHandler(createMCPLegacy(mcp), { streaming: true })
  * await handler(new Request('http://localhost/mcp', {
  * 	method: 'POST',
  * 	body: '{"jsonrpc":"2.0","method":"ping","id":1}',
  * }))
  * ```
  */
-export declare function createMCPPostHandler<TState = unknown>(mcp: MCPServerInterface, options?: HTTPHandlerOptions<TState>): (request: Request, context?: RouteContext<string, TState>) => Promise<Response>;
+export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPHandlerOptions<TState>): (request: Request, context?: RouteContext<string, TState>) => Promise<Response>;
 
 /**
  * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
- * {@link MCPServerInterface} (the `@src/core` dispatch core) on the fetch-standard router
+ * {@link MCPDispatcherInterface} (the `@src/core` dispatch boundary) on the fetch-standard router
  * spine, pumping each `POST` body through `mcp.dispatch`. Returns the {@link RouteInput}s to
  * hand to `router.add(...)`.
  *
@@ -179,14 +201,14 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPServerInt
  * DISPATCH-level outcomes:
  *
  * - A **transport** failure — a malformed JSON body, or a parsed value that is not a
- *   JSON-RPC REQUEST — is an HTTP `400` carrying a JSON-RPC error BODY (`-32700` Parse
- *   error / `-32600` Invalid Request, id `null`).
+ *   JSON-RPC INVOCATION — is an HTTP `400` carrying a JSON-RPC error BODY (`-32700` Parse
+ *   error / `-32600` Invalid Request), with the `id` it could not read OMITTED.
  * - Modern protocol/method/name headers are validated against the body; a mismatch is
  *   HTTP `400` + `-32020`. Headerless initialize is accepted, a live legacy session supplies
  *   its pinned revision, and every other headerless request is rejected.
  * - Legacy dispatch errors stay IN-BAND at HTTP `200`; modern errors map to `400` for
  *   `-32020` / `-32021` / `-32022` / `-32602`, `404` for `-32601`, and `200` otherwise.
- * - A **notification** (a request with no `id`, which `dispatch` resolves to
+ * - A **notification** (an invocation with no `id`, which `dispatch` resolves to
  *   `undefined`) is a `202 Accepted` with no body.
  *
  * When `streaming` is enabled (the default) and the client `Accept`s `text/event-stream`,
@@ -205,7 +227,7 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPServerInt
  * allowlist or explicitly delegates validation to an upstream layer.
  *
  * @typeParam TState - The consumer's opaque per-request state type
- * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over HTTP
+ * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over HTTP
  * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `streaming`
  *   (default `true`), plus shared origin, keepalive, and synchronous caller-extraction options; see
  *   {@link HTTPTransportOptions}
@@ -213,14 +235,14 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPServerInt
  *
  * @example
  * ```ts
- * import { createMCPServer, createToolManager } from '@src/core'
+ * import { createMCPLegacy, createMCPServer, createToolManager } from '@src/core'
  * import { createMCPRoutes } from '@src/server'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
+ * const routes = createMCPRoutes(createMCPLegacy(mcp)) // both eras; pass `mcp` for modern only
  * ```
  */
-export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions<TState>): readonly RouteInput<string, TState>[];
+export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPTransportOptions<TState>): readonly RouteInput<string, TState>[];
 
 /**
  * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
@@ -247,7 +269,10 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterfac
  *   live-session request. It then
  *   FORWARDS a fresh `Request` carrying the buffered `text` (`next(forwarded)`) — never the
  *   already-consumed original — so the route re-reads the same body, and stamps the response
- *   with {@link MCP_SESSION_HEADER}.
+ *   with {@link MCP_SESSION_HEADER}. The entry's `touched` instant is read AFTER that
+ *   downstream response, because it means the LAST ACCESS: a request slower than `ttl` would
+ *   otherwise store a session that is already expired, and the write-back RE-ASKS the store, so
+ *   a `DELETE` arriving while the request was suspended is not undone.
  * - **`GET {path}`.** Resolves the session the same way (no mint — only `initialize` mints);
  *   an invalid / unknown id is the same `404`. A valid session opens the resumable
  *   server→client stream via `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
@@ -295,7 +320,7 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
 
 /**
  * Create the stdio CLIENT transport for an {@link import('@src/core').MCPClientInterface}
- * — a {@link ClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+ * — a {@link MCPClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
  * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
  * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
  *
@@ -310,7 +335,7 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
  *
  * @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
  *   and optional `env`; see {@link StdioClientTransportOptions}
- * @returns A working {@link ClientTransportInterface} over a child process's stdio
+ * @returns A working {@link MCPClientTransportInterface} over a child process's stdio
  *
  * @example
  * ```ts
@@ -324,11 +349,11 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
  * const tools = await client.tools()
  * ```
  */
-export declare function createStdioClientTransport(options: StdioClientTransportOptions): ClientTransportInterface;
+export declare function createStdioClientTransport(options: StdioClientTransportOptions): MCPClientTransportInterface;
 
 /**
  * Create the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
- * MCPServerInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
+ * MCPDispatcherInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
  * injected stream pair), the stdio mirror of {@link createWebSocketServer}.
  *
  * @remarks
@@ -342,7 +367,7 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * surfaces on `mcp.emitter`'s `error` event rather than escaping the (async) message
  * pump.
  *
- * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over stdio
+ * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over stdio
  * @param options - Optional injectable `input` / `output` streams; see
  *   {@link StdioServerOptions}
  * @returns A `{ start(): void; stop(): void }` handle to arm / tear down the pump
@@ -356,14 +381,14 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * createStdioServer(mcp).start() // an MCP client now connects over this process's stdio
  * ```
  */
-export declare function createStdioServer(mcp: MCPServerInterface, options?: StdioServerOptions): {
+export declare function createStdioServer(mcp: MCPDispatcherInterface, options?: StdioServerOptions): {
     start(): void;
     stop(): void;
 };
 
 /**
  * Create the WebSocket CLIENT transport for an {@link import('@src/core').MCPClientInterface}
- * — a {@link ClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
+ * — a {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
  * egress mirror of {@link createWebSocketServer} and the WebSocket sibling of {@link
  * createHTTPClientTransport}.
  *
@@ -379,7 +404,7 @@ export declare function createStdioServer(mcp: MCPServerInterface, options?: Std
  *
  * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional `headers`
  *   merged onto the upgrade request; see {@link WebSocketClientTransportOptions}
- * @returns A working {@link ClientTransportInterface} over a WebSocket
+ * @returns A working {@link MCPClientTransportInterface} over a WebSocket
  *
  * @example
  * ```ts
@@ -393,11 +418,11 @@ export declare function createStdioServer(mcp: MCPServerInterface, options?: Std
  * const tools = await client.tools()
  * ```
  */
-export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): ClientTransportInterface;
+export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): MCPClientTransportInterface;
 
 /**
  * Create the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
- * transport-agnostic {@link MCPServerInterface} over a WebSocket, the WebSocket mirror of
+ * transport-agnostic {@link MCPDispatcherInterface} over a WebSocket, the WebSocket mirror of
  * {@link createMCPRoutes}. Register it on the spine's upgrade seam.
  *
  * @remarks
@@ -425,7 +450,7 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
  * upgrade so it never reaches this pump.
  *
- * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over WebSocket
+ * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over WebSocket
  * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
  *   (default {@link MCP_WEBSOCKET_SUBPROTOCOL}); see {@link WebSocketServerOptions}
  * @returns An {@link UpgradeHandler} to register with the spine's `upgrade` seam
@@ -439,7 +464,7 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  * server.upgrade(createWebSocketServer(mcp)) // an MCP client now connects over ws://…/mcp
  * ```
  */
-export declare function createWebSocketServer(mcp: MCPServerInterface, options?: WebSocketServerOptions): UpgradeHandler;
+export declare function createWebSocketServer(mcp: MCPDispatcherInterface, options?: WebSocketServerOptions): UpgradeHandler;
 
 /**
  * Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
@@ -495,7 +520,7 @@ export declare const DEFAULT_MCP_SESSION_TTL = 300000;
 
 /**
  * Decode and deliver each complete newline-framed line onto a {@link
- * ClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
+ * MCPClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
  * transports (client and server) run their {@link extractLines} output through.
  *
  * @remarks
@@ -508,7 +533,7 @@ export declare const DEFAULT_MCP_SESSION_TTL = 300000;
  * @param emitter - The transport's {@link EmitterInterface} to emit `message` / `error` onto
  * @param lines - The complete lines (from {@link extractLines}) to decode and deliver
  */
-export declare function dispatchLines(emitter: EmitterInterface<ClientTransportEventMap>, lines: readonly string[]): void;
+export declare function dispatchLines(emitter: EmitterInterface<MCPClientTransportEventMap>, lines: readonly string[]): void;
 
 /**
  * One entry of an {@link MCPSessionInterface}'s folded replay log — a single pushed {@link
@@ -551,7 +576,7 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
 
 /**
  * The HTTP CLIENT transport for the Model Context Protocol — a
- * {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server over
+ * {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server over
  * `fetch`, the egress mirror of the server's `createMCPRoutes`.
  *
  * @remarks
@@ -584,7 +609,7 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
  *   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /
  *   decode failure surfaces on the `error` event rather than escaping `send`.
- * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); fires
+ * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
  *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
  *
  * @example
@@ -594,11 +619,12 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  * await client.connect()
  * ```
  */
-export declare class HTTPClientTransport implements ClientTransportInterface_2 {
+export declare class HTTPClientTransport implements MCPClientTransportInterface_2 {
     #private;
     constructor(options: HTTPClientTransportOptions);
-    get emitter(): EmitterInterface<ClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
     get session(): string | undefined;
+    get duplex(): boolean;
     start(): Promise<void>;
     send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
@@ -630,6 +656,72 @@ export declare interface HTTPClientTransportOptions {
     readonly timeout?: number;
 }
 
+/**
+ * Compose 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
+ * without one: consumer cancellation of the bridged body, a forwarding failure mid-pump, and a
+ * keepalive tick that finds the SSE stream already closed. That last pair is the whole point of
+ * the composition — a client that vanishes mid-stream aborts nothing by itself, so unless this
+ * object raises the signal on its own failure paths, the handler, the controlled stream, and
+ * the producer behind them all keep running for a response that can no longer be written.
+ * Graceful upstream completion is the one terminal that does NOT abort: the body simply closes,
+ * because the exchange finished rather than ended.
+ *
+ * {@link bridge} preserves the source response status and headers, forwards its body bytes, and
+ * owns keepalive comments plus listener/timer cleanup until upstream completion, request abort,
+ * or consumer cancellation. This is a single-response lifecycle object, not a reusable bridge.
+ * It supplies no handler or session policy.
+ *
+ * The keepalive interval is a BUDGET, sanitized like every other numeric knob in this package:
+ * anything that is not a positive integer — `0`, a negative, a fractional value, `NaN`,
+ * `Infinity` — falls back to {@link DEFAULT_MCP_KEEPALIVE_INTERVAL}, and a larger value clamps
+ * to Node's `2_147_483_647` ms timer maximum. None may reach the platform's timer floor, where
+ * an idle-liveness tick becomes the polling this package forbids everywhere else.
+ *
+ * @example
+ * ```ts
+ * import { HTTPDisconnect } from '@orkestrel/mcp/server'
+ * import { openStream } from '@orkestrel/server'
+ *
+ * const disconnect = new HTTPDisconnect(request.signal, { interval: 15_000 })
+ * const stream = openStream()
+ * const response = disconnect.bridge(stream)
+ * ```
+ */
+export declare class HTTPDisconnect {
+    #private;
+    /**
+     * Create the lifecycle composition for one request and its future SSE response.
+     *
+     * @param signal - The incoming request signal
+     * @param options - Optional keepalive `interval` in milliseconds; an invalid value falls back
+     *   to {@link DEFAULT_MCP_KEEPALIVE_INTERVAL}, and one above Node's timer maximum clamps to it
+     */
+    constructor(signal: AbortSignal, options?: MCPKeepaliveOptions);
+    /**
+     * The signal aborted by the incoming request, or by any end of this response that is not
+     * its graceful completion.
+     *
+     * @returns The composed lifecycle signal
+     */
+    get signal(): AbortSignal;
+    /**
+     * Bridge one open SSE response through cancellation-aware byte forwarding and keepalives.
+     *
+     * Consumer cancellation, a read failure while forwarding, and a keepalive tick that finds the
+     * SSE stream already closed each abort {@link signal}; consumer cancellation also cancels the
+     * upstream reader. Upstream completion closes the returned body without inventing an abort.
+     * Every terminal path clears the keepalive timer and detaches the bridge-owned abort listener.
+     *
+     * @param stream - The open SSE stream whose response will be consumed by the HTTP writer
+     * @returns A one-use response preserving status, status text, headers, and SSE body bytes
+     * @throws When the supplied SSE response has no body
+     */
+    bridge(stream: StreamInterface): Response;
+}
+
 /**
  * Options shared by the MCP Streamable-HTTP POST handler and route factory.
  *
@@ -677,6 +769,27 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
     readonly path?: string;
 }
 
+/**
+ * Infer 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
+ * the JSON-RPC body. 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.
+ *
+ * @param request - The HTTP request carrying the headers
+ * @param reference - The parsed invocation body, or the active legacy session version
+ * @returns The first header issue, or `undefined` when the applicable headers agree
+ *
+ * @example
+ * ```ts
+ * const issue = inferHeaderIssue(request, rpcRequest)
+ * issue?.header // 'Mcp-Method' when that field is absent or mismatched
+ * ```
+ */
+export declare function inferHeaderIssue(request: Request, reference: JSONRPCInvocation | MCPVersion): MCPHeaderIssue | undefined;
+
 /**
  * Infer the legacy revision an `initialize` request negotiates.
  *
@@ -684,10 +797,10 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  * A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
  * request selects the newest supported legacy revision, matching the core initialize result.
  *
- * @param request - The legacy initialize request
+ * @param request - The legacy initialize invocation
  * @returns The negotiated legacy protocol revision
  */
-export declare function inferLegacyVersion(request: JSONRPCRequest): MCPVersion;
+export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPVersion;
 
 /**
  * Infer the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
@@ -718,21 +831,6 @@ export declare interface LineExtraction {
     readonly remainder: string;
 }
 
-/**
- * Whether a modern HTTP request's required standard headers match its JSON-RPC body.
- *
- * @remarks
- * Requires `MCP-Protocol-Version` to equal the reserved `_meta` version and `Mcp-Method`
- * to equal `method`. `Mcp-Name` is required only for `tools/call`, where it must equal
- * `params.name`; discovery and listing requests need no name because none is derivable.
- * Legacy requests return `false` because this predicate models the modern contract only.
- *
- * @param request - The HTTP request carrying the headers
- * @param message - The parsed JSON-RPC request body
- * @returns `true` only when every method-applicable modern header matches
- */
-export declare function matchesModernHeaders(request: Request, message: JSONRPCRequest): boolean;
-
 /** The modern Streamable-HTTP request header carrying the JSON-RPC method name. */
 export declare const MCP_METHOD_HEADER = "mcp-method";
 
@@ -788,6 +886,21 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  */
 export declare type MCPCallerHandler<TState = unknown> = (request: Request, context: RouteContext<string, TState> | undefined) => unknown;
 
+/**
+ * One required MCP HTTP header that is absent or disagrees with its server-derived value.
+ *
+ * @remarks
+ * - `header` — the canonical HTTP field name safe to show to an integrator.
+ * - `reason` — whether the field is absent or carries a mismatched value.
+ * - `message` — the refusal message naming the expected body, session, or server value without
+ *   echoing the client-supplied header value.
+ */
+export declare interface MCPHeaderIssue {
+    readonly header: 'MCP-Protocol-Version' | 'Mcp-Method' | 'Mcp-Name';
+    readonly reason: 'missing' | 'mismatched';
+    readonly message: string;
+}
+
 /**
  * Shared SSE keepalive options for held-open HTTP responses.
  *
@@ -1045,9 +1158,9 @@ export declare function readSessionHeader(request: Request): string | undefined;
  * JSON-RPC error body.
  *
  * @remarks
- * Returns `Response.json(buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, 'Session not found'),
- * { status: 404 })`, mirroring `createMCPRoutes`'s `400` transport-failure shape (a
- * JSON-RPC error BODY with a `null` id) but at the session-not-found status. Shared by
+ * Returns `Response.json(buildJSONRPCError(undefined, JSONRPC_INVALID_REQUEST, 'Session not
+ * found'), { status: 404 })`, mirroring `createMCPRoutes`'s `400` transport-failure shape (a
+ * JSON-RPC error BODY with NO id) but at the session-not-found status. Shared by
  * every {@link import('./middlewares.js').createMCPSession} validation site — the
  * non-`initialize` `POST` path, the resumable `GET {path}` open, and the `DELETE {path}`
  * session-end (each a missing / unknown / TTL-evicted id) — so the single `404` envelope
@@ -1057,6 +1170,41 @@ export declare function readSessionHeader(request: Request): string | undefined;
  */
 export declare function rejectUnknownSession(): Response;
 
+/**
+ * Pump a controlled held-open exchange onto an open SSE stream — one `data:` event per
+ * notification in order, then the terminating response — and END the exchange however the
+ * pump leaves.
+ *
+ * @remarks
+ * The Streamable-HTTP twin of {@link import('@src/core').sendStream}, and it owns exactly what
+ * that owns. The `finally` releases the exchange on EVERY exit — the normal terminal, a
+ * producer that threw, a `write` that threw, and an abort alike — because nothing else will:
+ * a request whose client vanished cancels nothing by itself, so an exchange this pump walks
+ * away from keeps its producer, its request lifetime, and its live subscription slot forever.
+ * The exchange is released BEFORE the body ends, so the slot is already back when the response
+ * completes.
+ *
+ * Total (§14) — never throws and never rejects. A held-open SSE response has already sent its
+ * headers and part of its body, so there is no failure the transport could still convert into
+ * a different answer; the honest end of a broken stream is a closed one, and the fault itself
+ * is already legible on `server.emitter`'s `error` event, which is where a contained fault
+ * belongs.
+ *
+ * @param stream - The controlled held-open answer to write out and then end
+ * @param sse - The open SSE stream to write each serialized message onto
+ * @returns Resolves once the exchange has ended and the SSE body has been closed
+ *
+ * @example
+ * ```ts
+ * const answer = await mcp.dispatch(invocation, { signal: disconnect.signal })
+ * if (answer !== undefined && Symbol.asyncIterator in answer) {
+ * 	const sse = openStream()
+ * 	queueMicrotask(() => void sendEventStream(answer, sse))
+ * }
+ * ```
+ */
+export declare function sendEventStream(stream: MCPStreamControllerInterface, sse: StreamInterface): Promise<void>;
+
 /** The `X-Accel-Buffering` value that disables reverse-proxy buffering. */
 export declare const SSE_BUFFERING_DISABLED = "no";
 
@@ -1068,7 +1216,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
 
 /**
  * The stdio CLIENT transport for the Model Context Protocol — a
- * {@link ClientTransportInterface} that drives a CHILD PROCESS MCP server over
+ * {@link MCPClientTransportInterface} that drives a CHILD PROCESS MCP server over
  * newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
  * import('./HTTPClientTransport.js').HTTPClientTransport} and {@link
  * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
@@ -1087,7 +1235,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * - **Outbound (`send`).** `send(message)` writes one newline-terminated
  *   `JSON.stringify`d line to the child's `stdin`.
  * - **`close()`** kills the child process and fires `close` (idempotent).
- * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the
+ * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
  *   fault), distinct from the emitter's own listener-error channel.
  *
@@ -1098,11 +1246,12 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * await client.connect() // start() spawns the child, then the MCP initialize runs over stdio
  * ```
  */
-export declare class StdioClientTransport implements ClientTransportInterface_2 {
+export declare class StdioClientTransport implements MCPClientTransportInterface_2 {
     #private;
     constructor(options: StdioClientTransportOptions);
-    get emitter(): EmitterInterface<ClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
     get session(): string | undefined;
+    get duplex(): boolean;
     start(): Promise<void>;
     send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
@@ -1145,13 +1294,13 @@ export declare interface StdioServerOptions {
 /**
  * The stdio SERVER transport for the Model Context Protocol — wraps an injectable
  * readable/writable stream pair (`process.stdin`/`process.stdout` in production, a
- * test double in tests) as a {@link ClientTransportInterface}, the newline-delimited
+ * test double in tests) as a {@link MCPClientTransportInterface}, the newline-delimited
  * JSON-RPC channel {@link import('../factories.js').createStdioServer} pumps
  * `mcp.dispatch` over, the stdio mirror of {@link
  * import('./WebSocketServerTransport.js').WebSocketServerTransport}.
  *
  * @remarks
- * - **Reuses `ClientTransportInterface` (§21).** The same generic carrier the HTTP
+ * - **Reuses `MCPClientTransportInterface` (§21).** The same generic carrier the HTTP
  *   and WebSocket server transports implement — `emitter` (`message` / `close` /
  *   `error`), `start`, `send`, `close`. `session` is `undefined` (the stateless v1).
  * - **Inbound (`message`).** `start()` subscribes to `input`'s `data` event; each
@@ -1166,15 +1315,16 @@ export declare interface StdioServerOptions {
  * - **`close()`** fires this transport's `close` (idempotent) — the injected streams
  *   are owned by the caller (typically `process.stdin`/`process.stdout`, which must
  *   never be closed out from under the process) and are not torn down here.
- * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the
+ * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
  *   fault), distinct from the emitter's own listener-error channel.
  */
-export declare class StdioServerTransport implements ClientTransportInterface_2 {
+export declare class StdioServerTransport implements MCPClientTransportInterface_2 {
     #private;
     constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
-    get emitter(): EmitterInterface<ClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
     get session(): string | undefined;
+    get duplex(): boolean;
     start(): Promise<void>;
     send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
@@ -1199,7 +1349,7 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
 
 /**
  * The WebSocket CLIENT transport for the Model Context Protocol — a
- * {@link ClientTransportInterface} that drives a REMOTE MCP server over a WebSocket, the
+ * {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket, the
  * egress mirror of {@link import('./factories.js').createWebSocketServer} and the WebSocket
  * sibling of {@link import('./HTTPClientTransport.js').HTTPClientTransport}.
  *
@@ -1212,6 +1362,12 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   — a mismatch (or a non-`101` response, or a request error) REJECTS `start()` and the socket
  *   is destroyed. On success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
  *   head })` (CLIENT mode — no key → frames are MASKED per §5.3) and bridges its `message`.
+ * - **The arriving socket is RE-ASKED for, never assumed.** `start()` suspends across that
+ *   connect and upgrade, so it re-checks the transport's state before installing anything: a
+ *   concurrent `start()` that already installed a socket, or a {@link close} that ended the
+ *   transport while the handshake was on the wire, both WIN — the socket that arrives late is
+ *   DESTROYED and never bound, so no orphan is left re-emitting frames at nobody. Both
+ *   `start()` calls still resolve; exactly one socket is ever bound.
  * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and narrowed
  *   with `parseJSONRPCMessage` — a {@link JSONRPCMessage} re-emits on this transport's `message`
  *   event (the reply the {@link import('@src/core').MCPClientInterface} correlates by `id`); a
@@ -1222,7 +1378,7 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  * - **URL scheme.** `options.url` accepts a `ws://` / `wss://` URL or an `http://` / `https://`
  *   one; a `ws(s)` scheme is converted to `http(s)` for the underlying upgrade request (`wss`
  *   → TLS via `node:https`). Either reaches the same endpoint.
- * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); every emit
+ * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
  *   the emitter isolates a listener throw (a buggy observer never corrupts the transport);
  *   `error` is a DOMAIN event (a transport-level fault).
  *
@@ -1233,11 +1389,12 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  * await client.connect() // start() handshakes, then the MCP initialize runs over WS frames
  * ```
  */
-export declare class WebSocketClientTransport implements ClientTransportInterface_2 {
+export declare class WebSocketClientTransport implements MCPClientTransportInterface_2 {
     #private;
     constructor(options: WebSocketClientTransportOptions);
-    get emitter(): EmitterInterface<ClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
     get session(): string | undefined;
+    get duplex(): boolean;
     start(): Promise<void>;
     send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
@@ -1256,6 +1413,13 @@ export declare class WebSocketClientTransport implements ClientTransportInterfac
  *   bearer for a guarded server). The transport always sets `Connection: Upgrade`,
  *   `Upgrade: websocket`, a random `Sec-WebSocket-Key`, `Sec-WebSocket-Version: 13`, and
  *   `Sec-WebSocket-Protocol: mcp`; a header supplied here is merged on top.
+ *
+ * **`headers` exists HERE and not on the browser face's `{ url, protocols }`, and that
+ * divergence is deliberate rather than a lag: the host performs the WebSocket handshake.**
+ * This face owns its own `node:http(s)` upgrade request, so it can set any header on it. A
+ * page cannot — the native `WebSocket` constructor takes a URL and subprotocols and nothing
+ * else — so a `headers` key over there would be an option that silently did nothing. Do not
+ * "harmonize" the two shapes.
  */
 export declare interface WebSocketClientTransportOptions {
     readonly url: string;
@@ -1288,12 +1452,12 @@ export declare interface WebSocketServerOptions {
 /**
  * The per-connection JSON-RPC-over-WebSocket SERVER bridge — wraps a
  * {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
- * {@link ClientTransportInterface}, the bidirectional JSON-RPC message channel
+ * {@link MCPClientTransportInterface}, the bidirectional JSON-RPC message channel
  * `createWebSocketServer` pumps `mcp.dispatch` over and the egress mirror's
  * {@link import('./WebSocketClientTransport.js').WebSocketClientTransport} reuses.
  *
  * @remarks
- * - **Reuses `ClientTransportInterface` (§21).** It IS the same generic carrier the HTTP
+ * - **Reuses `MCPClientTransportInterface` (§21).** It IS the same generic carrier the HTTP
  *   client transport implements — `emitter` (`message` / `close` / `error`), `start`,
  *   `send`, `close` — so the WebSocket server and client both speak ONE transport contract,
  *   no near-duplicate sibling interface. `session` is `undefined` (the stateless v1; a
@@ -1311,15 +1475,16 @@ export declare interface WebSocketServerOptions {
  * - **`close()`** closes the underlying socket (the RFC 6455 close handshake) and fires the
  *   transport's `close` event (idempotent — a second `close`, or a socket-driven close, emits
  *   once).
- * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the emitter
+ * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the emitter
  *   isolates a listener throw (a buggy observer never corrupts the bridge). `error` is a
  *   DOMAIN event (a transport-level fault), distinct from the emitter's listener-error channel.
  */
-export declare class WebSocketServerTransport implements ClientTransportInterface_2 {
+export declare class WebSocketServerTransport implements MCPClientTransportInterface_2 {
     #private;
     constructor(socket: NodeWebSocketInterface);
-    get emitter(): EmitterInterface<ClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
     get session(): string | undefined;
+    get duplex(): boolean;
     start(): Promise<void>;
     send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;