@orkestrel/mcp 0.0.5 → 0.0.7

package/dist/src/browser/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["#port","#receive","#closed","#onMessage","#onClosed","#emitter","#url","#headers","#fetch","#timeout","#session","#deliver","#emitter","#url","#protocols","#socket","#closed","#bind","#flush","#queue","#receive","#onClose"],"sources":["../../../src/browser/constants.ts","../../../src/browser/transports/MessagePortTransport.ts","../../../src/browser/helpers.ts","../../../src/browser/transports/HTTPClientTransport.ts","../../../src/browser/transports/WebSocketClientTransport.ts","../../../src/browser/factories.ts","../../../src/browser/serve.ts"],"sourcesContent":["// The MCP browser-transport constants (AGENTS §5 constants file) — the wire-level\n// header name the browser-face HTTP client transport echoes, matching the Node\n// face's `MCP_SESSION_HEADER` (`src/server/constants.ts`) byte-for-byte. The browser\n// face imports nothing from `src/server` (peer environment faces, per AGENTS §2), so\n// the literal is declared once here too — the SAME string, not a shared symbol.\n\n/**\n * The Streamable-HTTP transport header that carries the MCP session id. The browser\n * face's {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}\n * ECHOES this header exactly like the Node face's `HTTPClientTransport`\n * (`src/server`), so the same client interoperates with an `MCPSession`-based\n * server unchanged.\n */\nexport const MCP_SESSION_HEADER = 'mcp-session-id'\n\n// `serveMCP` server-identity defaults — `src/core`'s `createMCPServer` REQUIRES\n// `name`/`version`, but `ServeMCPOptions` (this face's bootstrap) makes both optional\n// (mirroring the CLIENT identity defaults, `DEFAULT_MCP_CLIENT_NAME` /\n// `DEFAULT_MCP_CLIENT_VERSION`, `src/core/constants.ts`), so `serveMCPScope` falls\n// back to these when a caller omits them.\n\n/** The default server name `serveMCPScope` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. */\nexport const DEFAULT_MCP_SERVER_NAME = 'taverna'\n\n/** The default server version `serveMCPScope` reports (`initialize`'s `serverInfo.version`) when `options.version` is omitted. */\nexport const DEFAULT_MCP_SERVER_VERSION = '1.0.0'\n\n// The WebSocket subprotocol constant, declared here independently of the Node face's\n// `MCP_WEBSOCKET_SUBPROTOCOL` (`src/server/constants.ts`) — peer environment faces share\n// no import (AGENTS §2), so the same value is declared twice. The browser face's\n// `WebSocketClientTransport` defaults to this value when `protocols` is omitted, matching\n// `createWebSocketServer`'s unconditional echo.\n\n/**\n * The WebSocket subprotocol `createWebSocketClientTransport` requests by default —\n * `'mcp'`, matching `createWebSocketServer`'s unconditional `Sec-WebSocket-Protocol:\n * mcp` echo. Per RFC 6455 §4.1 a client MUST fail the connection if the server returns\n * a subprotocol it did not request; Node ≥ 22 (undici) enforces this strictly, so the\n * default bakes the correct value in. Override `WebSocketClientTransportOptions.protocols`\n * only when connecting to a foreign server that speaks a different subprotocol (or `[]`\n * for no subprotocol negotiation at all).\n */\nexport const MCP_WEBSOCKET_SUBPROTOCOL = 'mcp'\n","import type { MCPTransportInterface } from '@src/core'\nimport type { MessagePortTransportOptions } from '../types.js'\nimport { isString } from '@orkestrel/contract'\n\n/**\n * The browser-face `MessagePort` transport for the Model Context Protocol — a\n * {@link MCPTransportInterface} over a native `MessagePort`, the genuinely new\n * capability this face adds: MCP over `postMessage`.\n *\n * @remarks\n * - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}\n *   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only\n *   carriers of `@src/core`'s `ClientTransportInterface`), a `MessagePort` is a\n *   plain duplex channel — the SAME class implements `@src/core`'s\n *   `MCPTransportInterface` and is handed to EITHER `bindServer` or\n *   `bindClient`/`createDuplexClientTransport`; which role it plays comes entirely\n *   from the binder it is given to, not from anything this class decides.\n * - **`start()` at construction — bind synchronously.** `MessagePort.start()` is only\n *   REQUIRED when listening via `addEventListener` (as opposed to the `onmessage`\n *   setter, which implies it) — this transport uses `addEventListener`, and\n *   `MCPTransportInterface` has no separate open/connect step for the caller to hook\n *   a start into, so the constructor calls `port.start()` immediately: the port\n *   begins dispatching QUEUED messages the moment the transport exists. This is safe\n *   inside `serveMCP`'s flow (the transport is synchronously handed to `bindServer`\n *   before control returns to the event loop), but is a **footgun for direct use**:\n *   if you construct `new MessagePortTransport({ port })` and then `await` anything\n *   before calling `listen`, messages that arrived in the gap are DROPPED. **Bind\n *   synchronously after construction** — do not interleave an `await` between\n *   `new MessagePortTransport(…)` and `bindServer` / `listen`.\n * - **String payloads only.** `send` posts the message string as-is (`postMessage`\n *   structured-clones it — a string clones to an identical string, so the wire stays\n *   plain JSON-RPC text like every other transport in this package). Inbound: a\n *   non-string `event.data` (a host or a misbehaving peer posting a structured\n *   object) is IGNORED — dropped silently, never forwarded, never thrown (§14) —\n *   because `MCPTransportInterface` carries no `error` channel for this port to\n *   surface a non-string frame on (unlike `ClientTransportInterface`'s `emitter`);\n *   silently ignoring is the total, contract-shaped choice.\n * - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event\n *   (the structured-clone deserialization of an inbound message threw) reports one\n *   BAD FRAME, not a dead channel — the port itself keeps working and later, well-\n *   formed messages still arrive. Routing it to `closed` would tear down the\n *   `bindServer`/`bindClient` wiring (and, transitively, every session it carries)\n *   over a single malformed frame, which is far more destructive than dropping that\n *   one frame — so this transport registers a `messageerror` listener that does\n *   nothing, deliberately.\n * - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`\n *   disconnects it — further `postMessage` calls on EITHER end are silently\n *   undelivered, per the platform contract) and fires the registered `closed`\n *   handler exactly once, whether the caller closes it once or twice. There is no\n *   native \"peer closed\" signal for a `MessagePort` (unlike a WebSocket's `close`\n *   event) — `closed` fires ONLY from this transport's own `close()`.\n * - **Single-handler-replace (the port contract, `@src/core`'s `MCPTransportInterface`\n *   doc).** `listen`/`closed` each hold the ONE currently registered handler; a\n *   second call REPLACES the first rather than adding a second subscriber.\n *\n * @example\n * ```ts\n * const { port1, port2 } = new MessageChannel()\n * const serverTransport = new MessagePortTransport({ port: port1 })\n * bindServer(server, serverTransport) // port1 side dispatches inbound requests\n *\n * const clientTransport = new MessagePortTransport({ port: port2 })\n * const client = createMCPClient({ transport: createDuplexClientTransport(clientTransport) })\n * bindClient(client, clientTransport) // port2 side is the client's carrier\n * ```\n */\nexport class MessagePortTransport implements MCPTransportInterface {\n\treadonly #port: MessagePort\n\t#onMessage: ((message: string) => void) | undefined = undefined\n\t#onClosed: (() => void) | undefined = undefined\n\t#closed = false\n\n\tconstructor(options: MessagePortTransportOptions) {\n\t\tthis.#port = options.port\n\t\tthis.#port.addEventListener('message', (event: MessageEvent) => this.#receive(event.data))\n\t\tthis.#port.addEventListener('messageerror', () => {\n\t\t\t// Intentionally ignored — one bad frame, not a dead channel; see class doc.\n\t\t})\n\t\tthis.#port.start()\n\t}\n\n\tsend(message: string): void {\n\t\tif (this.#closed) return\n\t\tthis.#port.postMessage(message)\n\t}\n\n\tlisten(handler: (message: string) => void): void {\n\t\tthis.#onMessage = handler\n\t}\n\n\tclosed(handler: () => void): void {\n\t\tthis.#onClosed = handler\n\t}\n\n\tclose(): void {\n\t\tif (this.#closed) return\n\t\tthis.#closed = true\n\t\tthis.#port.close()\n\t\tthis.#onClosed?.()\n\t}\n\n\t// Decode one inbound `postMessage` payload: a non-string `data` is dropped, never\n\t// forwarded (§14 — this port carries only plain JSON-RPC text). A string reaches the\n\t// registered `listen` handler unchanged (the string IS the JSON-RPC message; parsing is\n\t// entirely the core's concern, per the port contract).\n\t#receive(data: unknown): void {\n\t\tif (!isString(data)) return\n\t\tthis.#onMessage?.(data)\n\t}\n}\n","import type { JSONRPCMessage, MCPServerInterface } from '@src/core'\nimport type { SSEParserInterface } from '@orkestrel/sse'\nimport type { ServeMCPOptions, ScopeTransportInterface } from './types.js'\nimport { bindServer, parseJSONRPCMessage } from '@src/core'\nimport { isString } from '@orkestrel/contract'\nimport { createSSEParser } from '@orkestrel/sse'\nimport { MessagePortTransport } from './transports/MessagePortTransport.js'\n\n// The MCP browser-transport helpers (AGENTS §4.3 module-scope names — no entity\n// context). `decodeEvent` and `readEventStream` are the browser face's copies of the\n// Node face's SAME-NAMED helpers (`src/server/helpers.ts`) — peer environment faces\n// (AGENTS §2) share no import, so the CLIENT-side SSE decode step (reused by\n// `transports/HTTPClientTransport.ts`) is declared once here too. Both are total and\n// narrow at the boundary, never `as` (AGENTS §14): a malformed / non-message SSE\n// `data:` event is dropped, never thrown.\n//\n// `createScopeMessageListener` is `serve.ts`'s per-event dispatcher, extracted here\n// (AGENTS §5 — no function is declared inside another function body) so\n// `serveMCPScope` merely CALLS it and stores the RETURNED closure (an ordinary\n// value assignment, not an inline function literal) for `addEventListener` /\n// `removeEventListener` to share the same reference.\n\n/**\n * Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`\n * when it is not one — the per-event step {@link readEventStream} folds over.\n *\n * @remarks\n * `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the\n * event's `data`) inside a try/catch and narrows the parsed value with\n * `parseJSONRPCMessage`. Total (§14): malformed JSON or a non-message value yields\n * `undefined`, never throws.\n *\n * @param data - One SSE event's `data` payload\n * @returns The decoded {@link JSONRPCMessage}, or `undefined`\n */\nexport function decodeEvent(data: string): JSONRPCMessage | undefined {\n\ttry {\n\t\treturn parseJSONRPCMessage(JSON.parse(data))\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it\n * carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.\n *\n * @remarks\n * Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({\n * stream: true })` (handling a multi-byte char split across reads) and\n * `@orkestrel/sse`'s {@link SSEParserInterface} (handling a partial line / in-progress\n * event split across reads), then narrows each dispatched event's `data` to a\n * {@link JSONRPCMessage} via {@link decodeEvent} (so a non-message / non-JSON `data:`\n * event is DROPPED, never thrown — total, §14). A `null` body (no stream) yields no\n * messages; {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}\n * reads a request/response SSE reply (the server sends one `data:` event then ends),\n * so this drains to completion.\n *\n * @param response - The SSE `fetch` Response to decode (its `body` is read to completion)\n * @returns Every {@link JSONRPCMessage} the stream carried, in order\n */\nexport async function readEventStream(response: Response): Promise<readonly JSONRPCMessage[]> {\n\tconst body = response.body\n\tif (body === null) return []\n\tconst reader = body.getReader()\n\tconst decoder = new TextDecoder()\n\tconst parser: SSEParserInterface = createSSEParser()\n\tconst messages: JSONRPCMessage[] = []\n\ttry {\n\t\tfor (;;) {\n\t\t\tconst { done, value } = await reader.read()\n\t\t\tif (done) break\n\t\t\tfor (const event of parser.parse(decoder.decode(value, { stream: true }))) {\n\t\t\t\tconst message = decodeEvent(event.data)\n\t\t\t\tif (message !== undefined) messages.push(message)\n\t\t\t}\n\t\t}\n\t} finally {\n\t\treader.releaseLock()\n\t}\n\treturn messages\n}\n\n/**\n * Build `serveMCPScope`'s (`serve.ts`) `message`-event listener — the unified\n * dispatcher that routes EVERY inbound event on a hostable scope, portless or\n * port-bearing, to the right binding.\n *\n * @remarks\n * Port-bearing events (`event.ports.length > 0`) are gated by `options.accept` FIRST\n * — when the gate returns `false` the event is dropped entirely (no binding, no reply).\n * Accepted events spawn a fresh `MessagePortTransport` over `event.ports[0]`,\n * `bindServer` `server` onto it, and record a teardown (`unbind` then `transport.close()`)\n * into `teardowns`. A port that was already seen is IGNORED — repeated delivery of the\n * same `MessagePort` would create duplicate bindings over one port (→ duplicated replies),\n * so the listener tracks seen ports and silently drops repeats.\n *\n * This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client\n * channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event\n * (the unified design's deliberate cross-case, needing no upfront shape flag). An event\n * with NO ports and a STRING `data` is pushed onto `scopeTransport.deliver` (the\n * implicit, already-bound scope channel); any other event (no ports, non-string data)\n * is silently dropped — total (§14), never throws.\n *\n * @param server - The `MCPServerInterface` every spawned/implicit binding dispatches over\n * @param scopeTransport - The implicit scope channel (already `bindServer`-bound) portless events deliver onto\n * @param teardowns - The shared teardown set `serveMCPScope`'s dispose drains; each port-bearing event adds one entry\n * @param options - The `ServeMCPOptions` (for `options.accept`)\n * @returns The `message`-event listener to register (and later remove) on the scope\n *\n * @example\n * ```ts\n * const teardowns = new Set<() => void>()\n * const scopeTransport = createScopeTransport(scope)\n * bindServer(server, scopeTransport)\n * const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)\n * scope.addEventListener('message', onMessage)\n * ```\n */\nexport function createScopeMessageListener(\n\tserver: MCPServerInterface,\n\tscopeTransport: ScopeTransportInterface,\n\tteardowns: Set<() => void>,\n\toptions: ServeMCPOptions,\n): (event: MessageEvent) => void {\n\tconst seen = new Set<MessagePort>()\n\treturn (event: MessageEvent): void => {\n\t\tconst ports = event.ports\n\t\tif (ports.length > 0) {\n\t\t\t// Gate: consult accept (origin/identity check) before binding.\n\t\t\tif (options.accept !== undefined && !options.accept(event)) return\n\t\t\tconst port = ports[0]\n\t\t\t// Deduplicate: repeated delivery of the same port would create duplicate bindings.\n\t\t\tif (seen.has(port)) return\n\t\t\tseen.add(port)\n\t\t\tconst transport = new MessagePortTransport({ port })\n\t\t\tconst unbind = bindServer(server, transport)\n\t\t\tteardowns.add(() => {\n\t\t\t\tunbind()\n\t\t\t\ttransport.close()\n\t\t\t})\n\t\t\treturn\n\t\t}\n\t\tif (isString(event.data)) scopeTransport.deliver(event.data)\n\t}\n}\n","import type { ClientTransportEventMap, ClientTransportInterface, JSONRPCMessage } from '@src/core'\nimport type { EmitterInterface } from '@orkestrel/emitter'\nimport type { HTTPClientTransportOptions } from '../types.js'\nimport { parseJSONRPCMessage } from '@src/core'\nimport { Emitter } from '@orkestrel/emitter'\nimport { MCP_SESSION_HEADER } from '../constants.js'\nimport { readEventStream } from '../helpers.js'\n\n/**\n * The browser-face HTTP CLIENT transport for the Model Context Protocol — a\n * {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server\n * over the native `fetch`, the browser sibling of the Node face's\n * {@link import('@src/server').HTTPClientTransport}, honoring the SAME\n * `mcp-session-id` semantics so it interoperates with an `MCPSession`-based server\n * unchanged.\n *\n * @remarks\n * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized\n *   message (or batch) to `options.url` with `content-type: application/json` and an\n *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may\n *   answer with either framing) — plus any `options.headers` (e.g. an\n *   `Authorization` bearer). It then decodes the reply and emits each decoded\n *   {@link JSONRPCMessage} on the `message` event the\n *   {@link import('@src/core').MCPClientInterface} subscribes to.\n * - **Both reply framings.** A `200` with an `application/json` body is parsed with\n *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded via the\n *   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} (the browser\n *   face's own `readEventStream`) — the inverse of the server's `openStream` seam, so\n *   the wire round-trips. A `202` Accepted (a notification) carries no body and emits\n *   nothing.\n * - **Session echo.** `start()` / `close()` are no-ops (a request/response transport\n *   holds no long-lived connection). The `mcp-session-id` response header, when a\n *   STATEFUL server sends one (on `initialize`), is captured into `session` and then\n *   ECHOED as the `mcp-session-id` request header on every SUBSEQUENT request — so an\n *   `MCPClient` passes a stateful server's session validation. Before `initialize`\n *   returns an id, `session` is `undefined` and no header is sent (safe against a\n *   stateless server, which neither sends nor expects one).\n * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,\n *   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /\n *   decode failure surfaces on the `error` event rather than escaping `send`.\n * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); fires\n *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.\n *\n * @example\n * ```ts\n * const transport = new HTTPClientTransport({ url: 'http://localhost:3000/mcp' })\n * const client = new MCPClient({ transport })\n * await client.connect()\n * ```\n */\nexport class HTTPClientTransport implements ClientTransportInterface {\n\treadonly #emitter: Emitter<ClientTransportEventMap>\n\treadonly #url: string\n\treadonly #headers: Readonly<Record<string, string>>\n\treadonly #fetch: typeof fetch\n\treadonly #timeout: number | undefined\n\t#session: string | undefined = undefined\n\n\tconstructor(options: HTTPClientTransportOptions) {\n\t\tthis.#emitter = new Emitter<ClientTransportEventMap>()\n\t\tthis.#url = options.url\n\t\tthis.#headers = options.headers ?? {}\n\t\tthis.#fetch = options.fetch ?? globalThis.fetch\n\t\tthis.#timeout = options.timeout\n\t}\n\n\tget emitter(): EmitterInterface<ClientTransportEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget session(): string | undefined {\n\t\treturn this.#session\n\t}\n\n\tasync start(): Promise<void> {\n\t\t// A request/response transport opens no long-lived connection — `send` issues each\n\t\t// `fetch` on demand. Nothing to arm.\n\t}\n\n\tasync send(message: JSONRPCMessage | readonly JSONRPCMessage[]): Promise<void> {\n\t\tlet response: Response\n\t\ttry {\n\t\t\tresponse = await this.#fetch(this.#url, {\n\t\t\t\tmethod: 'POST',\n\t\t\t\theaders: {\n\t\t\t\t\t'content-type': 'application/json',\n\t\t\t\t\taccept: 'application/json, text/event-stream',\n\t\t\t\t\t// Echo a captured session id so a STATEFUL server validates the request; before\n\t\t\t\t\t// `initialize` returns one `#session` is undefined → no header (safe for a\n\t\t\t\t\t// stateless server). A caller `headers` key still wins (merged last).\n\t\t\t\t\t...(this.#session === undefined ? {} : { [MCP_SESSION_HEADER]: this.#session }),\n\t\t\t\t\t...this.#headers,\n\t\t\t\t},\n\t\t\t\tbody: JSON.stringify(message),\n\t\t\t\t...(this.#timeout === undefined ? {} : { signal: AbortSignal.timeout(this.#timeout) }),\n\t\t\t})\n\t\t} catch (error) {\n\t\t\t// A network-level failure (connection refused, DNS) — surface it for observation;\n\t\t\t// the client's per-request deadline still rejects the pending request.\n\t\t\tthis.#emitter.emit('error', error)\n\t\t\treturn\n\t\t}\n\t\t// Capture a server-assigned session id (a stateless server sends none) so it is echoed\n\t\t// on subsequent requests; a missing header leaves `session` unchanged.\n\t\tconst session = response.headers.get(MCP_SESSION_HEADER)\n\t\tif (session !== null) this.#session = session\n\t\tawait this.#deliver(response)\n\t}\n\n\tasync close(): Promise<void> {\n\t\tthis.#emitter.emit('close')\n\t}\n\n\t// Decode a reply and emit each carried message. A 202 (notification accepted) has no\n\t// body — emit nothing. An `application/json` body is one envelope; a `text/event-stream`\n\t// body is decoded via the browser-face `readEventStream` (one or more `data:` events). A\n\t// decode failure surfaces on `error` rather than escaping.\n\tasync #deliver(response: Response): Promise<void> {\n\t\tif (response.status === 202) return\n\t\tconst type = response.headers.get('content-type') ?? ''\n\t\ttry {\n\t\t\tif (type.includes('text/event-stream')) {\n\t\t\t\tfor (const message of await readEventStream(response))\n\t\t\t\t\tthis.#emitter.emit('message', message)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif (type.includes('application/json')) {\n\t\t\t\tconst message = parseJSONRPCMessage(await response.json())\n\t\t\t\tif (message !== undefined) this.#emitter.emit('message', message)\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tthis.#emitter.emit('error', error)\n\t\t}\n\t}\n}\n","import type { ClientTransportEventMap, ClientTransportInterface, JSONRPCMessage } from '@src/core'\nimport type { EmitterInterface } from '@orkestrel/emitter'\nimport type { WebSocketClientTransportOptions } from '../types.js'\nimport { parseJSONRPCMessage } from '@src/core'\nimport { isString } from '@orkestrel/contract'\nimport { Emitter } from '@orkestrel/emitter'\nimport { MCP_WEBSOCKET_SUBPROTOCOL } from '../constants.js'\n\n/**\n * The browser-face WebSocket CLIENT transport for the Model Context Protocol — a\n * {@link ClientTransportInterface} that drives a REMOTE MCP server over the native\n * `WebSocket` global, the browser sibling of the Node face's\n * {@link import('@src/server').WebSocketClientTransport}.\n *\n * @remarks\n * - **Host-performed handshake.** `start()` opens `new WebSocket(url, protocols)` and\n *   waits for the native `'open'` event — the RFC 6455 handshake itself is entirely\n *   the host's concern, so this transport carries none of the Node client's\n *   `node:crypto` / `node:http(s)` machinery. A connection failure (the native\n *   `'error'` event while not yet `OPEN`) REJECTS `start()`.\n * - **Queued sends.** `send` writes each message as one text frame immediately once\n *   the socket is `OPEN`; a `send` issued before `'open'` fires (or before `start()`\n *   is even called) is QUEUED and flushed, IN ORDER, the moment the socket opens —\n *   so a caller need not await `start()` before calling `send`.\n * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and\n *   narrowed with `parseJSONRPCMessage` — a well-formed {@link JSONRPCMessage}\n *   re-emits on this transport's `message` event; a non-text (binary) frame or a\n *   non-JSON / non-message text frame surfaces on `error` and is DROPPED (§14 — never\n *   throws on adversarial wire input).\n * - **`close()`** closes the underlying socket and fires `close` (idempotent); the\n *   socket's native `close` event (a server-initiated close) fires the SAME `close`\n *   exactly once total — `close()` first flips the guard, so the native event never\n *   double-emits. **This transport is not reusable after `close()`** — a `send` issued\n *   after `close()` is silently dropped (not queued, not delivered even on a later\n *   `start()`).\n * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); every\n *   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a\n *   transport-level fault).\n *\n * @example\n * ```ts\n * const transport = new WebSocketClientTransport({ url: 'ws://localhost:3000/mcp' })\n * const client = new MCPClient({ transport })\n * await client.connect() // the browser handshakes, then the MCP initialize runs over WS frames\n * ```\n */\nexport class WebSocketClientTransport implements ClientTransportInterface {\n\treadonly #emitter: Emitter<ClientTransportEventMap>\n\treadonly #url: string\n\treadonly #protocols: string | string[] | undefined\n\t#socket: WebSocket | undefined = undefined\n\t#queue: string[] = []\n\t#closed = false\n\n\tconstructor(options: WebSocketClientTransportOptions) {\n\t\tthis.#emitter = new Emitter<ClientTransportEventMap>()\n\t\tthis.#url = options.url\n\t\tconst protocols = options.protocols\n\t\t// Default to MCP_WEBSOCKET_SUBPROTOCOL when `protocols` is omitted — matching\n\t\t// createWebSocketServer's unconditional echo. An empty array means \"no subprotocol\",\n\t\t// overriding the default explicitly for foreign servers.\n\t\tthis.#protocols =\n\t\t\ttypeof protocols === 'string'\n\t\t\t\t? protocols\n\t\t\t\t: protocols === undefined\n\t\t\t\t\t? MCP_WEBSOCKET_SUBPROTOCOL\n\t\t\t\t\t: protocols.length === 0\n\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: [...protocols]\n\t}\n\n\tget emitter(): EmitterInterface<ClientTransportEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget session(): string | undefined {\n\t\treturn undefined\n\t}\n\n\tasync start(): Promise<void> {\n\t\t// Already connected — a second `connect()` short-circuits in the client, but guard here\n\t\t// too (idempotent open).\n\t\tif (this.#socket !== undefined) return\n\t\tthis.#closed = false\n\t\tconst socket = new WebSocket(this.#url, this.#protocols)\n\t\tthis.#socket = socket\n\t\tthis.#bind(socket)\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tsocket.addEventListener(\n\t\t\t\t'open',\n\t\t\t\t() => {\n\t\t\t\t\tthis.#flush(socket)\n\t\t\t\t\tresolve()\n\t\t\t\t},\n\t\t\t\t{ once: true },\n\t\t\t)\n\t\t\tsocket.addEventListener(\n\t\t\t\t'error',\n\t\t\t\t() => {\n\t\t\t\t\tif (socket.readyState !== WebSocket.OPEN) {\n\t\t\t\t\t\tthis.#socket = undefined\n\t\t\t\t\t\treject(new Error('WebSocket connection failed'))\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t{ once: true },\n\t\t\t)\n\t\t})\n\t}\n\n\tasync send(message: JSONRPCMessage | readonly JSONRPCMessage[]): Promise<void> {\n\t\t// After close(), silently drop — never queue (a closed transport is not reusable;\n\t\t// queued messages would resurrect on a later start() which is not a supported pattern).\n\t\tif (this.#closed) return\n\t\tconst messages = Array.isArray(message) ? message : [message]\n\t\tfor (const one of messages) {\n\t\t\tconst text = JSON.stringify(one)\n\t\t\tconst socket = this.#socket\n\t\t\tif (socket !== undefined && socket.readyState === WebSocket.OPEN) socket.send(text)\n\t\t\telse this.#queue.push(text)\n\t\t}\n\t}\n\n\tasync close(): Promise<void> {\n\t\tif (this.#closed) return\n\t\tthis.#closed = true\n\t\tconst socket = this.#socket\n\t\tthis.#socket = undefined\n\t\tif (socket !== undefined) socket.close()\n\t\tthis.#emitter.emit('close')\n\t}\n\n\t// Bridge the native socket's events onto the transport: a text frame → `message`\n\t// (decoded + narrowed), the socket close → `close`, a socket fault → `error`.\n\t#bind(socket: WebSocket): void {\n\t\tsocket.addEventListener('message', (event: MessageEvent) => this.#receive(event.data))\n\t\tsocket.addEventListener('close', () => this.#onClose())\n\t\tsocket.addEventListener('error', (event) => this.#emitter.emit('error', event))\n\t}\n\n\t// Write every queued (pre-open) message, in order, as the socket opens.\n\t#flush(socket: WebSocket): void {\n\t\tfor (const text of this.#queue.splice(0)) socket.send(text)\n\t}\n\n\t// Decode one inbound frame: a non-text (binary) frame is rejected without a throw; a\n\t// text frame is `JSON.parse`d → `parseJSONRPCMessage`. A well-formed message re-emits on\n\t// `message`; a malformed / non-message frame surfaces on `error` and is dropped (§14 —\n\t// never throws on adversarial wire input).\n\t#receive(data: unknown): void {\n\t\tif (!isString(data)) {\n\t\t\tthis.#emitter.emit('error', new Error('non-text WebSocket frame'))\n\t\t\treturn\n\t\t}\n\t\tlet parsed: unknown\n\t\ttry {\n\t\t\tparsed = JSON.parse(data)\n\t\t} catch (error) {\n\t\t\tthis.#emitter.emit('error', error)\n\t\t\treturn\n\t\t}\n\t\tconst message = parseJSONRPCMessage(parsed)\n\t\tif (message === undefined) {\n\t\t\tthis.#emitter.emit('error', new Error('non-JSON-RPC WebSocket frame'))\n\t\t\treturn\n\t\t}\n\t\tthis.#emitter.emit('message', message)\n\t}\n\n\t// The socket closed underneath us — fire `close` once (a `close()` call already flipped\n\t// `#closed`, so it does not double-emit).\n\t#onClose(): void {\n\t\tif (this.#closed) return\n\t\tthis.#closed = true\n\t\tthis.#socket = undefined\n\t\tthis.#emitter.emit('close')\n\t}\n}\n","import type { ClientTransportInterface, MCPTransportInterface } from '@src/core'\nimport type {\n\tHTTPClientTransportOptions,\n\tMessagePortTransportOptions,\n\tScopeTransportInterface,\n\tServeMCPScopeInterface,\n\tWebSocketClientTransportOptions,\n} from './types.js'\nimport { HTTPClientTransport } from './transports/HTTPClientTransport.js'\nimport { MessagePortTransport } from './transports/MessagePortTransport.js'\nimport { WebSocketClientTransport } from './transports/WebSocketClientTransport.js'\n\n/**\n * Create the browser-face WebSocket CLIENT transport for an\n * {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}\n * that drives a REMOTE MCP server over the native `WebSocket` global, the browser\n * sibling of the Node face's `createWebSocketClientTransport` (`@src/server`).\n *\n * @remarks\n * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)\n * opens `new WebSocket(options.url, options.protocols)` and awaits the native\n * `'open'` event — the RFC 6455 handshake itself is the browser's concern. Each\n * JSON-RPC message the client `send`s before the socket opens is QUEUED and flushed,\n * in order, once it does; each decoded reply is surfaced on the transport's\n * `message` event for the client's id correlation.\n *\n * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional\n *   `protocols` (the WebSocket subprotocol(s) to request); see\n *   {@link WebSocketClientTransportOptions}\n * @returns A working {@link ClientTransportInterface} over the native `WebSocket`\n *\n * @example\n * ```ts\n * import { createMCPClient } from '@orkestrel/mcp'\n * import { createWebSocketClientTransport } from '@orkestrel/mcp/browser'\n *\n * const client = createMCPClient({\n * \ttransport: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),\n * })\n * await client.connect()\n * const tools = await client.tools()\n * ```\n */\nexport function createWebSocketClientTransport(\n\toptions: WebSocketClientTransportOptions,\n): ClientTransportInterface {\n\treturn new WebSocketClientTransport(options)\n}\n\n/**\n * Create the browser-face HTTP CLIENT transport for an\n * {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}\n * that drives a REMOTE Streamable-HTTP MCP server over the native `fetch`, the\n * browser sibling of the Node face's `createHTTPClientTransport` (`@src/server`).\n *\n * @remarks\n * Hand it to `createMCPClient({ transport })`: each JSON-RPC message the client\n * sends is `POST`ed to `options.url` with `content-type: application/json` and an\n * `Accept` of both `application/json` and `text/event-stream` (the server answers\n * with EITHER — a plain JSON envelope or a Streamable-HTTP SSE `data:` event,\n * decoded via `@orkestrel/sse`), and the reply is surfaced on the transport's\n * `message` event for the client's id correlation. Add `options.headers` (e.g. an\n * `Authorization` bearer) to reach a guarded server. `start` / `close` hold no\n * connection; against a STATEFUL server it captures the `mcp-session-id` from\n * `initialize` and echoes it on later requests, so the same `MCPClient` passes\n * session validation (a stateless server sends none).\n *\n * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged\n *   onto every request, optional `fetch` (default `globalThis.fetch`), and optional\n *   `timeout` (ms, applied via `AbortSignal.timeout`); see\n *   {@link HTTPClientTransportOptions}\n * @returns A working {@link ClientTransportInterface} over the native `fetch`\n *\n * @example\n * ```ts\n * import { createMCPClient } from '@orkestrel/mcp'\n * import { createHTTPClientTransport } from '@orkestrel/mcp/browser'\n *\n * const client = createMCPClient({\n * \ttransport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),\n * })\n * await client.connect()\n * const tools = await client.tools()\n * ```\n */\nexport function createHTTPClientTransport(\n\toptions: HTTPClientTransportOptions,\n): ClientTransportInterface {\n\treturn new HTTPClientTransport(options)\n}\n\n/**\n * Create the browser-face `MessagePort` transport — a\n * {@link import('@src/core').MCPTransportInterface} over a native `MessagePort`, the\n * SYMMETRIC carrier that works as either a server or a client transport depending on\n * which binder ({@link import('@src/core').bindServer} or\n * {@link import('@src/core').bindClient}) it is handed to.\n *\n * @remarks\n * `port.start()` runs at construction (see {@link MessagePortTransport}'s doc for\n * why); inbound payloads are string-only (a non-string `postMessage` payload is\n * dropped, never thrown); `messageerror` is ignored (one bad frame does not close the\n * channel); `close()` closes the port and fires `closed` exactly once.\n *\n * @param options - `port` (the `MessagePort` half to drive; REQUIRED); see\n *   {@link MessagePortTransportOptions}\n * @returns A working {@link import('@src/core').MCPTransportInterface} over the port\n *\n * @example\n * ```ts\n * import { bindServer, createMCPServer } from '@orkestrel/mcp'\n * import { createMessagePortTransport } from '@orkestrel/mcp/browser'\n *\n * const { port1, port2 } = new MessageChannel()\n * bindServer(createMCPServer({ name: 's', version: '1.0.0', tools }), createMessagePortTransport({ port: port1 }))\n * ```\n */\nexport function createMessagePortTransport(\n\toptions: MessagePortTransportOptions,\n): MCPTransportInterface {\n\treturn new MessagePortTransport(options)\n}\n\n/**\n * Adapt a hostable {@link ServeMCPScopeInterface} (`self` in a dedicated Web Worker,\n * or any structurally matching double) into a {@link ScopeTransportInterface} — the\n * implicit, portless message channel `serveMCPScope` (`serve.ts`) binds for the\n * dedicated-worker shape.\n *\n * @remarks\n * `send` writes each outbound string via `scope.postMessage`. `listen`/`closed`\n * register the SINGLE handler `deliver` / the underlying close path route through —\n * `serveMCPScope`'s own `scope` `message`-event listener calls `deliver(event.data)`\n * for every portless, string-payload event (there is no native registration point on\n * the scope itself for `serveMCPScope` to hand a `listen` handler to, so `deliver` is\n * the bridge). `close()` fires the registered `closed` handler — a scope has nothing\n * physically closable, so this is the only teardown signal available.\n *\n * @param scope - The hostable scope to adapt (structurally, `self` / `globalThis`\n *   inside a dedicated Web Worker)\n * @returns A {@link ScopeTransportInterface} `serveMCPScope` binds and drives via `deliver`\n *\n * @example\n * ```ts\n * const scopeTransport = createScopeTransport(self)\n * const unbind = bindServer(server, scopeTransport)\n * ```\n */\nexport function createScopeTransport(scope: ServeMCPScopeInterface): ScopeTransportInterface {\n\tlet onMessage: ((message: string) => void) | undefined\n\tlet onClosed: (() => void) | undefined\n\treturn {\n\t\tsend(message: string): void {\n\t\t\tscope.postMessage(message)\n\t\t},\n\t\tlisten(handler: (message: string) => void): void {\n\t\t\tonMessage = handler\n\t\t},\n\t\tclosed(handler: () => void): void {\n\t\t\tonClosed = handler\n\t\t},\n\t\tclose(): void {\n\t\t\tonClosed?.()\n\t\t},\n\t\tdeliver(message: string): void {\n\t\t\tonMessage?.(message)\n\t\t},\n\t}\n}\n","import type { ServeMCPOptions, ServeMCPScopeInterface } from './types.js'\nimport { bindServer, createMCPServer } from '@src/core'\nimport { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION } from './constants.js'\nimport { createScopeTransport } from './factories.js'\nimport { createScopeMessageListener } from './helpers.js'\n\n// The `serveWorker` analog (PROPOSAL §3.3.4): boot an `MCPServer` inside a hostable\n// scope and wire its message events to it. `serveMCP(options)` is a one-liner over\n// `globalThis`; `serveMCPScope(scope, options)` is the testable core — it takes the\n// scope as a parameter so a test drives it with a scope double instead of the real\n// `globalThis`.\n//\n// UNIFIED dedicated-worker / Service-Worker wiring, no upfront detection flag: a\n// dedicated worker's implicit channel (no port) and a Service Worker's per-client\n// `MessagePort` are structurally distinguishable PER EVENT (`event.ports.length`),\n// so ONE `message` listener handles both shapes uniformly — an event carrying a port\n// spawns a per-port `MessagePortTransport` binding (multi-client); an event with no\n// port but a string `data` routes through the implicit scope channel. Per AGENTS §3.3.4,\n// this face imports project code freely (`@src/core` bundles into the worker) — the\n// inlined-guards exception `node:worker_threads`' type-stripping forces on the Node\n// face's `serve.ts` (`@orkestrel/worker`) does NOT apply here and is not copied.\n\n/**\n * Boot an `MCPServer` inside a hostable scope (a dedicated Web Worker's `self`, or a\n * Service Worker's `self`) and wire its message events to it.\n *\n * @remarks\n * **Trust boundary — mechanism, not policy.** `serveMCPScope` exposes the ENTIRE\n * supplied `tools` registry to EVERY client the scope accepts a port from, with NO\n * built-in origin or identity check. In a Service Worker that means every same-origin\n * context the SW controls (any window, worker, or iframe can\n * `controller.postMessage(msg, [port])` and get a fully-bound server with complete\n * tool-call access). Origin allow-listing, handshake tokens, and any other gating are\n * the embedding application's responsibility — compose a guard in front. Use the\n * `accept` option to gate port-bearing events before binding: return `false` to drop\n * the event entirely (no binding, no reply).\n *\n * **Lifetime / per-client binding accumulation.** Each accepted port-bearing event\n * creates a fresh `MessagePortTransport` + `bindServer` binding that lives for the\n * scope's lifetime — there is NO per-client reaping, because `MessagePort` provides\n * no \"peer closed\" signal. For bounded, long-lived client sets this is fine; embedders\n * with high client churn must track and invoke the dispose function themselves to\n * avoid unbounded accumulation.\n *\n * **Portless events and the implicit scope channel.** A portless `message` event\n * (e.g. `controller.postMessage('<json-rpc>')` in a Service Worker) delivers its\n * string directly to the implicit scope transport — **the tool EXECUTES** — even\n * though no reply can reach the caller. In a `ServiceWorkerGlobalScope` the reply\n * path (`scopeTransport.send` → `scope.postMessage`) throws (no `self.postMessage`),\n * and `bindServer` routes the throw to the server emitter's `error` event (see\n * `@src/core bindServer`), so the un-repliable reply is dropped. The net effect is\n * **blind side-effecting ingress**: the tool runs but the caller gets no result.\n * Crucially, **`accept` does NOT gate this channel** — it is consulted only for\n * port-bearing events. In a Service Worker, if `accept` is your sole guard, ensure\n * all clients connect through transferred `MessagePort`s (port-bearing messages), or\n * restrict the exposed tools to side-effect-free operations, or validate a token\n * inside the tools themselves.\n *\n * Binds the implicit scope channel EAGERLY (at call time, not lazily on first use) —\n * `bindServer` is called once against a {@link import('./types.js').ScopeTransportInterface}\n * wrapping `scope` for the whole lifetime of the returned dispose, so a dedicated\n * worker's very first portless message is served with no first-use setup cost or\n * ordering hazard.\n *\n * Every inbound `message` event is inspected structurally: `event.ports.length > 0`\n * spawns a fresh {@link import('./factories.js').createMessagePortTransport} +\n * `bindServer` for THAT port (tracked for teardown) — this holds even on a\n * dedicated-worker-shaped scope, the unified design's deliberate cross-case. An\n * event with NO ports and a STRING `event.data` is delivered onto the implicit scope\n * channel; any other event (no ports, non-string data) is dropped.\n *\n * @param scope - The hostable scope to wire (structurally, `self` inside a worker)\n * @param options - `tools` (the live registry to expose; REQUIRED), optional\n *   `name`/`version` (default {@link import('./constants.js').DEFAULT_MCP_SERVER_NAME} /\n *   {@link import('./constants.js').DEFAULT_MCP_SERVER_VERSION}), optional `accept`\n *   (origin/identity gate for port-bearing events); see {@link ServeMCPOptions}\n * @returns A dispose function — unbinds every binding, closes every accepted\n *   `MessagePort`, and removes the scope's `message` listener. Idempotent.\n *\n * @example\n * ```ts\n * const scope = { postMessage() {}, addEventListener() {}, removeEventListener() {} }\n * const dispose = serveMCPScope(scope, {\n *   tools: createToolManager(),\n *   // Prefer token-in-data — event.origin is empty for same-origin worker messages.\n *   accept: (event) => event.data === 'my-secret-token',\n * })\n * // ... later:\n * dispose()\n * ```\n */\nexport function serveMCPScope(scope: ServeMCPScopeInterface, options: ServeMCPOptions): () => void {\n\tconst server = createMCPServer({\n\t\ttools: options.tools,\n\t\tname: options.name ?? DEFAULT_MCP_SERVER_NAME,\n\t\tversion: options.version ?? DEFAULT_MCP_SERVER_VERSION,\n\t})\n\tconst scopeTransport = createScopeTransport(scope)\n\tconst unbindScope = bindServer(server, scopeTransport)\n\tconst teardowns = new Set<() => void>()\n\tconst onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)\n\tscope.addEventListener('message', onMessage)\n\tlet disposed = false\n\treturn () => {\n\t\tif (disposed) return\n\t\tdisposed = true\n\t\tscope.removeEventListener('message', onMessage)\n\t\tunbindScope()\n\t\tfor (const teardown of teardowns) teardown()\n\t\tteardowns.clear()\n\t}\n}\n\n/**\n * Boot an `MCPServer` inside the CURRENT hostable scope (`globalThis` — a dedicated\n * Web Worker or a Service Worker) and wire its message events to it.\n *\n * @remarks\n * A one-liner over {@link serveMCPScope}: `serveMCP(options)` is exactly\n * `serveMCPScope(globalThis, options)`. Kept as its own export so the scope-facing\n * wiring stays independently testable (AGENTS §5) — drive {@link serveMCPScope}\n * directly with a scope double for a test, and this thin wrapper for real deploys.\n *\n * **Trust boundary and lifecycle** — see {@link serveMCPScope}'s `@remarks`. The same\n * considerations apply: ENTIRE tool registry exposed to every accepted port-bearing\n * event; use `accept` to gate; per-client bindings accumulate for the scope's lifetime.\n *\n * @param options - `tools` (the live registry to expose; REQUIRED), optional\n *   `name`/`version`, optional `accept` (origin/identity gate); see {@link ServeMCPOptions}\n * @returns A dispose function — see {@link serveMCPScope}\n *\n * @example\n * ```ts\n * // Inside a dedicated Web Worker's entry module:\n * import { serveMCP } from '@orkestrel/mcp/browser'\n * import { createToolManager, createTool } from '@orkestrel/agent'\n *\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))\n * const dispose = serveMCP({ tools, name: 'worker-mcp', version: '1.0.0' })\n * // ... later, on teardown:\n * dispose()\n * ```\n */\nexport function serveMCP(options: ServeMCPOptions): () => void {\n\treturn serveMCPScope(globalThis, options)\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["#port","#receive","#closed","#onMessage","#onClosed","#emitter","#url","#headers","#fetch","#timeout","#session","#protocol","#deliver","#capture","#emitter","#url","#protocols","#socket","#closed","#bind","#flush","#queue","#receive","#onClose"],"sources":["../../../src/browser/constants.ts","../../../src/browser/transports/MessagePortTransport.ts","../../../src/browser/helpers.ts","../../../src/browser/transports/HTTPClientTransport.ts","../../../src/browser/transports/WebSocketClientTransport.ts","../../../src/browser/factories.ts"],"sourcesContent":["// The MCP browser-transport constants (AGENTS §5 constants file) — the wire-level\n// header names the browser-face HTTP client transport echoes, matching the Node\n// face's session and protocol-version headers byte-for-byte. The browser face imports\n// nothing from `src/server` (peer environment faces, per AGENTS §2), so the literals\n// are declared once here too — the SAME strings, not shared symbols.\n\n/**\n * The Streamable-HTTP transport header that carries the MCP session id. The browser\n * face's {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}\n * ECHOES this header exactly like the Node face's `HTTPClientTransport`\n * (`src/server`), so the same client interoperates with an `MCPSession`-based\n * server unchanged.\n */\nexport const MCP_SESSION_HEADER = 'mcp-session-id'\n\n/**\n * The Streamable-HTTP transport header carrying the negotiated MCP protocol version\n * on every post-initialize request. The browser HTTP client captures the initialize\n * result's `protocolVersion` and sends this header on each subsequent request.\n */\nexport const MCP_PROTOCOL_VERSION_HEADER = 'mcp-protocol-version'\n\n// `serveMCP` server-identity defaults — `src/core`'s `createMCPServer` REQUIRES\n// `name`/`version`, but `ServeMCPOptions` (this face's bootstrap) makes both optional\n// (mirroring the CLIENT identity defaults, `DEFAULT_MCP_CLIENT_NAME` /\n// `DEFAULT_MCP_CLIENT_VERSION`, `src/core/constants.ts`), so `serveMCPScope` falls\n// back to these when a caller omits them.\n\n/** The default server name `serveMCPScope` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. */\nexport const DEFAULT_MCP_SERVER_NAME = 'taverna'\n\n/** The default server version `serveMCPScope` reports (`initialize`'s `serverInfo.version`) when `options.version` is omitted. */\nexport const DEFAULT_MCP_SERVER_VERSION = '1.0.0'\n\n// The WebSocket subprotocol constant, declared here independently of the Node face's\n// `MCP_WEBSOCKET_SUBPROTOCOL` (`src/server/constants.ts`) — peer environment faces share\n// no import (AGENTS §2), so the same value is declared twice. The browser face's\n// `WebSocketClientTransport` defaults to this value when `protocols` is omitted, matching\n// `createWebSocketServer`'s unconditional echo.\n\n/**\n * The WebSocket subprotocol `createWebSocketClientTransport` requests by default —\n * `'mcp'`, matching `createWebSocketServer`'s unconditional `Sec-WebSocket-Protocol:\n * mcp` echo. Per RFC 6455 §4.1 a client MUST fail the connection if the server returns\n * a subprotocol it did not request; Node ≥ 22 (undici) enforces this strictly, so the\n * default bakes the correct value in. Override `WebSocketClientTransportOptions.protocols`\n * only when connecting to a foreign server that speaks a different subprotocol (or `[]`\n * for no subprotocol negotiation at all).\n */\nexport const MCP_WEBSOCKET_SUBPROTOCOL = 'mcp'\n","import type { MCPTransportInterface } from '@src/core'\nimport type { MessagePortTransportOptions } from '../types.js'\nimport { isString } from '@orkestrel/contract'\n\n/**\n * The browser-face `MessagePort` transport for the Model Context Protocol — a\n * {@link MCPTransportInterface} over a native `MessagePort`, the genuinely new\n * capability this face adds: MCP over `postMessage`.\n *\n * @remarks\n * - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}\n *   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only\n *   carriers of `@src/core`'s `ClientTransportInterface`), a `MessagePort` is a\n *   plain duplex channel — the SAME class implements `@src/core`'s\n *   `MCPTransportInterface` and is handed to EITHER `bindServer` or\n *   `bindClient`/`createDuplexClientTransport`; which role it plays comes entirely\n *   from the binder it is given to, not from anything this class decides.\n * - **`start()` at construction — bind synchronously.** `MessagePort.start()` is only\n *   REQUIRED when listening via `addEventListener` (as opposed to the `onmessage`\n *   setter, which implies it) — this transport uses `addEventListener`, and\n *   `MCPTransportInterface` has no separate open/connect step for the caller to hook\n *   a start into, so the constructor calls `port.start()` immediately: the port\n *   begins dispatching QUEUED messages the moment the transport exists. This is safe\n *   inside `serveMCP`'s flow (the transport is synchronously handed to `bindServer`\n *   before control returns to the event loop), but is a **footgun for direct use**:\n *   if you construct `new MessagePortTransport({ port })` and then `await` anything\n *   before calling `listen`, messages that arrived in the gap are DROPPED. **Bind\n *   synchronously after construction** — do not interleave an `await` between\n *   `new MessagePortTransport(…)` and `bindServer` / `listen`.\n * - **String payloads only.** `send` posts the message string as-is (`postMessage`\n *   structured-clones it — a string clones to an identical string, so the wire stays\n *   plain JSON-RPC text like every other transport in this package). Inbound: a\n *   non-string `event.data` (a host or a misbehaving peer posting a structured\n *   object) is IGNORED — dropped silently, never forwarded, never thrown (§14) —\n *   because `MCPTransportInterface` carries no `error` channel for this port to\n *   surface a non-string frame on (unlike `ClientTransportInterface`'s `emitter`);\n *   silently ignoring is the total, contract-shaped choice.\n * - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event\n *   (the structured-clone deserialization of an inbound message threw) reports one\n *   BAD FRAME, not a dead channel — the port itself keeps working and later, well-\n *   formed messages still arrive. Routing it to `closed` would tear down the\n *   `bindServer`/`bindClient` wiring (and, transitively, every session it carries)\n *   over a single malformed frame, which is far more destructive than dropping that\n *   one frame — so this transport registers a `messageerror` listener that does\n *   nothing, deliberately.\n * - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`\n *   disconnects it — further `postMessage` calls on EITHER end are silently\n *   undelivered, per the platform contract) and fires the registered `closed`\n *   handler exactly once, whether the caller closes it once or twice. There is no\n *   native \"peer closed\" signal for a `MessagePort` (unlike a WebSocket's `close`\n *   event) — `closed` fires ONLY from this transport's own `close()`.\n * - **Single-handler-replace (the port contract, `@src/core`'s `MCPTransportInterface`\n *   doc).** `listen`/`closed` each hold the ONE currently registered handler; a\n *   second call REPLACES the first rather than adding a second subscriber.\n *\n * @example\n * ```ts\n * const { port1, port2 } = new MessageChannel()\n * const serverTransport = new MessagePortTransport({ port: port1 })\n * bindServer(server, serverTransport) // port1 side dispatches inbound requests\n *\n * const clientTransport = new MessagePortTransport({ port: port2 })\n * const client = createMCPClient({ transport: createDuplexClientTransport(clientTransport) })\n * bindClient(client, clientTransport) // port2 side is the client's carrier\n * ```\n */\nexport class MessagePortTransport implements MCPTransportInterface {\n\treadonly #port: MessagePort\n\t#onMessage: ((message: string) => void) | undefined = undefined\n\t#onClosed: (() => void) | undefined = undefined\n\t#closed = false\n\n\tconstructor(options: MessagePortTransportOptions) {\n\t\tthis.#port = options.port\n\t\tthis.#port.addEventListener('message', (event: MessageEvent) => this.#receive(event.data))\n\t\tthis.#port.addEventListener('messageerror', () => {\n\t\t\t// Intentionally ignored — one bad frame, not a dead channel; see class doc.\n\t\t})\n\t\tthis.#port.start()\n\t}\n\n\tsend(message: string): void {\n\t\tif (this.#closed) return\n\t\tthis.#port.postMessage(message)\n\t}\n\n\tlisten(handler: (message: string) => void): void {\n\t\tthis.#onMessage = handler\n\t}\n\n\tclosed(handler: () => void): void {\n\t\tthis.#onClosed = handler\n\t}\n\n\tclose(): void {\n\t\tif (this.#closed) return\n\t\tthis.#closed = true\n\t\tthis.#port.close()\n\t\tthis.#onClosed?.()\n\t}\n\n\t// Decode one inbound `postMessage` payload: a non-string `data` is dropped, never\n\t// forwarded (§14 — this port carries only plain JSON-RPC text). A string reaches the\n\t// registered `listen` handler unchanged (the string IS the JSON-RPC message; parsing is\n\t// entirely the core's concern, per the port contract).\n\t#receive(data: unknown): void {\n\t\tif (!isString(data)) return\n\t\tthis.#onMessage?.(data)\n\t}\n}\n","import type { JSONRPCMessage, MCPServerInterface } from '@src/core'\nimport type { SSEParserInterface } from '@orkestrel/sse'\nimport type { ServeMCPOptions, ScopeTransportInterface } from './types.js'\nimport { bindServer, parseJSONRPCMessage } from '@src/core'\nimport { isString } from '@orkestrel/contract'\nimport { createSSEParser } from '@orkestrel/sse'\nimport { MessagePortTransport } from './transports/MessagePortTransport.js'\n\n// The MCP browser-transport helpers (AGENTS §4.3 module-scope names — no entity\n// context). `decodeEvent` and `readEventStream` are the browser face's copies of the\n// Node face's SAME-NAMED helpers (`src/server/helpers.ts`) — peer environment faces\n// (AGENTS §2) share no import, so the CLIENT-side SSE decode step (reused by\n// `transports/HTTPClientTransport.ts`) is declared once here too. Both are total and\n// narrow at the boundary, never `as` (AGENTS §14): a malformed / non-message SSE\n// `data:` event is dropped, never thrown.\n//\n// `createScopeMessageListener` is the bootstrap factory's per-event dispatcher, extracted here\n// (AGENTS §5 — no function is declared inside another function body) so\n// `serveMCPScope` merely CALLS it and stores the RETURNED closure (an ordinary\n// value assignment, not an inline function literal) for `addEventListener` /\n// `removeEventListener` to share the same reference.\n\n/**\n * Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`\n * when it is not one — the per-event step {@link readEventStream} folds over.\n *\n * @remarks\n * `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the\n * event's `data`) inside a try/catch and narrows the parsed value with\n * `parseJSONRPCMessage`. Total (§14): malformed JSON or a non-message value yields\n * `undefined`, never throws.\n *\n * @param data - One SSE event's `data` payload\n * @returns The decoded {@link JSONRPCMessage}, or `undefined`\n */\nexport function decodeEvent(data: string): JSONRPCMessage | undefined {\n\ttry {\n\t\treturn parseJSONRPCMessage(JSON.parse(data))\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it\n * carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.\n *\n * @remarks\n * Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({\n * stream: true })` (handling a multi-byte char split across reads) and\n * `@orkestrel/sse`'s {@link SSEParserInterface} (handling a partial line / in-progress\n * event split across reads), then narrows each dispatched event's `data` to a\n * {@link JSONRPCMessage} via {@link decodeEvent} (so a non-message / non-JSON `data:`\n * event is DROPPED, never thrown — total, §14). A `null` body (no stream) yields no\n * messages; {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}\n * reads a request/response SSE reply (the server sends one `data:` event then ends),\n * so this drains to completion.\n *\n * @param response - The SSE `fetch` Response to decode (its `body` is read to completion)\n * @returns Every {@link JSONRPCMessage} the stream carried, in order\n */\nexport async function readEventStream(response: Response): Promise<readonly JSONRPCMessage[]> {\n\tconst body = response.body\n\tif (body === null) return []\n\tconst reader = body.getReader()\n\tconst decoder = new TextDecoder()\n\tconst parser: SSEParserInterface = createSSEParser()\n\tconst messages: JSONRPCMessage[] = []\n\ttry {\n\t\tfor (;;) {\n\t\t\tconst { done, value } = await reader.read()\n\t\t\tif (done) break\n\t\t\tfor (const event of parser.parse(decoder.decode(value, { stream: true }))) {\n\t\t\t\tconst message = decodeEvent(event.data)\n\t\t\t\tif (message !== undefined) messages.push(message)\n\t\t\t}\n\t\t}\n\t} finally {\n\t\treader.releaseLock()\n\t}\n\treturn messages\n}\n\n/**\n * Build `serveMCPScope`'s `message`-event listener — the unified\n * dispatcher that routes EVERY inbound event on a hostable scope, portless or\n * port-bearing, to the right binding.\n *\n * @remarks\n * Port-bearing events (`event.ports.length > 0`) are gated by `options.accept` FIRST\n * — when the gate returns `false` the event is dropped entirely (no binding, no reply).\n * Accepted events spawn a fresh `MessagePortTransport` over `event.ports[0]`,\n * `bindServer` `server` onto it, and record a teardown (`unbind` then `transport.close()`)\n * into `teardowns`. A port that was already seen is IGNORED — repeated delivery of the\n * same `MessagePort` would create duplicate bindings over one port (→ duplicated replies),\n * so the listener tracks seen ports and silently drops repeats.\n *\n * This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client\n * channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event\n * (the unified design's deliberate cross-case, needing no upfront shape flag). An event\n * with NO ports and a STRING `data` is pushed onto `scopeTransport.deliver` (the\n * implicit, already-bound scope channel); any other event (no ports, non-string data)\n * is silently dropped — total (§14), never throws.\n *\n * @param server - The `MCPServerInterface` every spawned/implicit binding dispatches over\n * @param scopeTransport - The implicit scope channel (already `bindServer`-bound) portless events deliver onto\n * @param teardowns - The shared teardown set `serveMCPScope`'s dispose drains; each port-bearing event adds one entry\n * @param options - The `ServeMCPOptions` (for `options.accept`)\n * @returns The `message`-event listener to register (and later remove) on the scope\n *\n * @example\n * ```ts\n * const teardowns = new Set<() => void>()\n * const scopeTransport = createScopeTransport(scope)\n * bindServer(server, scopeTransport)\n * const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)\n * scope.addEventListener('message', onMessage)\n * ```\n */\nexport function createScopeMessageListener(\n\tserver: MCPServerInterface,\n\tscopeTransport: ScopeTransportInterface,\n\tteardowns: Set<() => void>,\n\toptions: ServeMCPOptions,\n): (event: MessageEvent) => void {\n\tconst seen = new Set<MessagePort>()\n\treturn (event: MessageEvent): void => {\n\t\tconst ports = event.ports\n\t\tif (ports.length > 0) {\n\t\t\t// Gate: consult accept (origin/identity check) before binding.\n\t\t\tif (options.accept !== undefined && !options.accept(event)) return\n\t\t\tconst port = ports[0]\n\t\t\tif (port === undefined) return\n\t\t\t// Deduplicate: repeated delivery of the same port would create duplicate bindings.\n\t\t\tif (seen.has(port)) return\n\t\t\tseen.add(port)\n\t\t\tconst transport = new MessagePortTransport({ port })\n\t\t\tconst unbind = bindServer(server, transport)\n\t\t\tteardowns.add(() => {\n\t\t\t\tunbind()\n\t\t\t\ttransport.close()\n\t\t\t})\n\t\t\treturn\n\t\t}\n\t\tif (isString(event.data)) scopeTransport.deliver(event.data)\n\t}\n}\n","import type { ClientTransportEventMap, ClientTransportInterface, JSONRPCMessage } from '@src/core'\nimport type { EmitterInterface } from '@orkestrel/emitter'\nimport type { HTTPClientTransportOptions } from '../types.js'\nimport { isJSONRPCResponse, parseJSONRPCMessage, SUPPORTED_PROTOCOL_VERSIONS } from '@src/core'\nimport { isRecord, isString } from '@orkestrel/contract'\nimport { Emitter } from '@orkestrel/emitter'\nimport { MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER } from '../constants.js'\nimport { readEventStream } from '../helpers.js'\n\n/**\n * The browser-face HTTP CLIENT transport for the Model Context Protocol — a\n * {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server\n * over the native `fetch`, the browser sibling of the Node face's\n * {@link import('@src/server').HTTPClientTransport}, honoring the SAME\n * `mcp-session-id` semantics so it interoperates with an `MCPSession`-based server\n * unchanged.\n *\n * @remarks\n * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized\n *   message to `options.url` with `content-type: application/json` and an\n *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may\n *   answer with either framing) — plus any `options.headers` (e.g. an\n *   `Authorization` bearer). It then decodes the reply and emits each decoded\n *   {@link JSONRPCMessage} on the `message` event the\n *   {@link import('@src/core').MCPClientInterface} subscribes to.\n * - **Both reply framings.** A `200` with an `application/json` body is parsed with\n *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded via the\n *   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} (the browser\n *   face's own `readEventStream`) — the inverse of the server's `openStream` seam, so\n *   the wire round-trips. A `202` Accepted (a notification) carries no body and emits\n *   nothing.\n * - **Session and protocol echo.** `start()` is a no-op (a\n *   request/response transport opens no long-lived connection). The\n *   `mcp-session-id` response header, when a STATEFUL server sends one (on\n *   `initialize`), is captured into `session` and then ECHOED as the\n *   `mcp-session-id` request header on every SUBSEQUENT request — so an\n *   `MCPClient` passes a stateful server's session validation. The\n *   initialize result's `protocolVersion` is likewise captured, but only\n *   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` on\n *   every subsequent request, as required by the 2025-06-18 Streamable-HTTP\n *   transport. Before initialize returns, neither captured header is sent.\n *   `close()` clears the captured protocol so a reconnect's `initialize`\n *   POST is headerless; the captured `session` persists across `close()`.\n * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,\n *   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /\n *   decode failure surfaces on the `error` event rather than escaping `send`.\n * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); fires\n *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.\n *\n * @example\n * ```ts\n * const transport = new HTTPClientTransport({ url: 'http://localhost:3000/mcp' })\n * const client = new MCPClient({ transport })\n * await client.connect()\n * ```\n */\nexport class HTTPClientTransport implements ClientTransportInterface {\n\treadonly #emitter: Emitter<ClientTransportEventMap>\n\treadonly #url: string\n\treadonly #headers: Readonly<Record<string, string>>\n\treadonly #fetch: typeof fetch\n\treadonly #timeout: number | undefined\n\t#session: string | undefined = undefined\n\t#protocol: string | undefined = undefined\n\n\tconstructor(options: HTTPClientTransportOptions) {\n\t\tthis.#emitter = new Emitter<ClientTransportEventMap>()\n\t\tthis.#url = options.url\n\t\tthis.#headers = options.headers ?? {}\n\t\tthis.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis)\n\t\tthis.#timeout = options.timeout\n\t}\n\n\tget emitter(): EmitterInterface<ClientTransportEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget session(): string | undefined {\n\t\treturn this.#session\n\t}\n\n\tasync start(): Promise<void> {\n\t\t// A request/response transport opens no long-lived connection — `send` issues each\n\t\t// `fetch` on demand. Nothing to arm.\n\t}\n\n\tasync send(message: JSONRPCMessage): Promise<void> {\n\t\tlet response: Response\n\t\ttry {\n\t\t\tresponse = await this.#fetch(this.#url, {\n\t\t\t\tmethod: 'POST',\n\t\t\t\theaders: {\n\t\t\t\t\t'content-type': 'application/json',\n\t\t\t\t\taccept: 'application/json, text/event-stream',\n\t\t\t\t\t// Echo a captured session id so a STATEFUL server validates the request; before\n\t\t\t\t\t// `initialize` returns one `#session` is undefined → no header (safe for a\n\t\t\t\t\t// stateless server). A caller `headers` key still wins (merged last).\n\t\t\t\t\t...(this.#session === undefined ? {} : { [MCP_SESSION_HEADER]: this.#session }),\n\t\t\t\t\t...(this.#protocol === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol }),\n\t\t\t\t\t...this.#headers,\n\t\t\t\t},\n\t\t\t\tbody: JSON.stringify(message),\n\t\t\t\t...(this.#timeout === undefined ? {} : { signal: AbortSignal.timeout(this.#timeout) }),\n\t\t\t})\n\t\t} catch (error) {\n\t\t\t// A network-level failure (connection refused, DNS) — surface it for observation;\n\t\t\t// the client's per-request deadline still rejects the pending request.\n\t\t\tthis.#emitter.emit('error', error)\n\t\t\treturn\n\t\t}\n\t\t// Capture a server-assigned session id (a stateless server sends none) so it is echoed\n\t\t// on subsequent requests; a missing header leaves `session` unchanged.\n\t\tconst session = response.headers.get(MCP_SESSION_HEADER)\n\t\tif (session !== null) this.#session = session\n\t\tawait this.#deliver(response)\n\t}\n\n\t// Clear the captured protocol before emitting `close`, so a reconnect's `initialize`\n\t// POST carries no `mcp-protocol-version` header (the captured `session` is untouched).\n\tasync close(): Promise<void> {\n\t\tthis.#protocol = undefined\n\t\tthis.#emitter.emit('close')\n\t}\n\n\t// Decode a reply and emit each carried message. A 202 (notification accepted) has no\n\t// body — emit nothing. An `application/json` body is one envelope; a `text/event-stream`\n\t// body is decoded via the browser-face `readEventStream` (one or more `data:` events). A\n\t// decode failure surfaces on `error` rather than escaping.\n\tasync #deliver(response: Response): Promise<void> {\n\t\tif (response.status === 202) return\n\t\tconst type = response.headers.get('content-type') ?? ''\n\t\ttry {\n\t\t\tif (type.includes('text/event-stream')) {\n\t\t\t\tfor (const message of await readEventStream(response)) this.#capture(message)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif (type.includes('application/json')) {\n\t\t\t\tconst message = parseJSONRPCMessage(await response.json())\n\t\t\t\tif (message !== undefined) this.#capture(message)\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tthis.#emitter.emit('error', error)\n\t\t}\n\t}\n\n\t// Capture the negotiated SUPPORTED protocol from the initialize result before emitting\n\t// the message, so the next request carries its required protocol-version header; any\n\t// other value (missing or unsupported) is ignored and leaves `#protocol` unchanged.\n\t#capture(message: JSONRPCMessage): void {\n\t\tif (\n\t\t\tisJSONRPCResponse(message) &&\n\t\t\tisRecord(message.result) &&\n\t\t\tisString(message.result['protocolVersion']) &&\n\t\t\tSUPPORTED_PROTOCOL_VERSIONS.includes(message.result['protocolVersion'])\n\t\t) {\n\t\t\tthis.#protocol = message.result['protocolVersion']\n\t\t}\n\t\tthis.#emitter.emit('message', message)\n\t}\n}\n","import type { ClientTransportEventMap, ClientTransportInterface, JSONRPCMessage } from '@src/core'\nimport type { EmitterInterface } from '@orkestrel/emitter'\nimport type { WebSocketClientTransportOptions } from '../types.js'\nimport { parseJSONRPCMessage } from '@src/core'\nimport { isString } from '@orkestrel/contract'\nimport { Emitter } from '@orkestrel/emitter'\nimport { MCP_WEBSOCKET_SUBPROTOCOL } from '../constants.js'\n\n/**\n * The browser-face WebSocket CLIENT transport for the Model Context Protocol — a\n * {@link ClientTransportInterface} that drives a REMOTE MCP server over the native\n * `WebSocket` global, the browser sibling of the Node face's\n * {@link import('@src/server').WebSocketClientTransport}.\n *\n * @remarks\n * - **Host-performed handshake.** `start()` opens `new WebSocket(url, protocols)` and\n *   waits for the native `'open'` event — the RFC 6455 handshake itself is entirely\n *   the host's concern, so this transport carries none of the Node client's\n *   `node:crypto` / `node:http(s)` machinery. A connection failure (the native\n *   `'error'` event while not yet `OPEN`) REJECTS `start()`.\n * - **Queued sends.** `send` writes each message as one text frame immediately once\n *   the socket is `OPEN`; a `send` issued before `'open'` fires (or before `start()`\n *   is even called) is QUEUED and flushed, IN ORDER, the moment the socket opens —\n *   so a caller need not await `start()` before calling `send`.\n * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and\n *   narrowed with `parseJSONRPCMessage` — a well-formed {@link JSONRPCMessage}\n *   re-emits on this transport's `message` event; a non-text (binary) frame or a\n *   non-JSON / non-message text frame surfaces on `error` and is DROPPED (§14 — never\n *   throws on adversarial wire input).\n * - **`close()`** closes the underlying socket and fires `close` (idempotent); the\n *   socket's native `close` event (a server-initiated close) fires the SAME `close`\n *   exactly once total — `close()` first flips the guard, so the native event never\n *   double-emits. **This transport is not reusable after `close()`** — a `send` issued\n *   after `close()` is silently dropped (not queued, not delivered even on a later\n *   `start()`).\n * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); every\n *   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a\n *   transport-level fault).\n *\n * @example\n * ```ts\n * const transport = new WebSocketClientTransport({ url: 'ws://localhost:3000/mcp' })\n * const client = new MCPClient({ transport })\n * await client.connect() // the browser handshakes, then the MCP initialize runs over WS frames\n * ```\n */\nexport class WebSocketClientTransport implements ClientTransportInterface {\n\treadonly #emitter: Emitter<ClientTransportEventMap>\n\treadonly #url: string\n\treadonly #protocols: string | string[] | undefined\n\t#socket: WebSocket | undefined = undefined\n\t#queue: string[] = []\n\t#closed = false\n\n\tconstructor(options: WebSocketClientTransportOptions) {\n\t\tthis.#emitter = new Emitter<ClientTransportEventMap>()\n\t\tthis.#url = options.url\n\t\tconst protocols = options.protocols\n\t\t// Default to MCP_WEBSOCKET_SUBPROTOCOL when `protocols` is omitted — matching\n\t\t// createWebSocketServer's unconditional echo. An empty array means \"no subprotocol\",\n\t\t// overriding the default explicitly for foreign servers.\n\t\tthis.#protocols =\n\t\t\ttypeof protocols === 'string'\n\t\t\t\t? protocols\n\t\t\t\t: protocols === undefined\n\t\t\t\t\t? MCP_WEBSOCKET_SUBPROTOCOL\n\t\t\t\t\t: protocols.length === 0\n\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: [...protocols]\n\t}\n\n\tget emitter(): EmitterInterface<ClientTransportEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget session(): string | undefined {\n\t\treturn undefined\n\t}\n\n\tasync start(): Promise<void> {\n\t\t// Already connected — a second `connect()` short-circuits in the client, but guard here\n\t\t// too (idempotent open).\n\t\tif (this.#socket !== undefined) return\n\t\tthis.#closed = false\n\t\tconst socket = new WebSocket(this.#url, this.#protocols)\n\t\tthis.#socket = socket\n\t\tthis.#bind(socket)\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tsocket.addEventListener(\n\t\t\t\t'open',\n\t\t\t\t() => {\n\t\t\t\t\tthis.#flush(socket)\n\t\t\t\t\tresolve()\n\t\t\t\t},\n\t\t\t\t{ once: true },\n\t\t\t)\n\t\t\tsocket.addEventListener(\n\t\t\t\t'error',\n\t\t\t\t() => {\n\t\t\t\t\tif (socket.readyState !== WebSocket.OPEN) {\n\t\t\t\t\t\tthis.#socket = undefined\n\t\t\t\t\t\treject(new Error('WebSocket connection failed'))\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t{ once: true },\n\t\t\t)\n\t\t})\n\t}\n\n\tasync send(message: JSONRPCMessage): Promise<void> {\n\t\t// After close(), silently drop — never queue (a closed transport is not reusable;\n\t\t// queued messages would resurrect on a later start() which is not a supported pattern).\n\t\tif (this.#closed) return\n\t\tconst text = JSON.stringify(message)\n\t\tconst socket = this.#socket\n\t\tif (socket !== undefined && socket.readyState === WebSocket.OPEN) socket.send(text)\n\t\telse this.#queue.push(text)\n\t}\n\n\tasync close(): Promise<void> {\n\t\tif (this.#closed) return\n\t\tthis.#closed = true\n\t\tconst socket = this.#socket\n\t\tthis.#socket = undefined\n\t\tif (socket !== undefined) socket.close()\n\t\tthis.#emitter.emit('close')\n\t}\n\n\t// Bridge the native socket's events onto the transport: a text frame → `message`\n\t// (decoded + narrowed), the socket close → `close`, a socket fault → `error`.\n\t#bind(socket: WebSocket): void {\n\t\tsocket.addEventListener('message', (event: MessageEvent) => this.#receive(event.data))\n\t\tsocket.addEventListener('close', () => this.#onClose())\n\t\tsocket.addEventListener('error', (event) => this.#emitter.emit('error', event))\n\t}\n\n\t// Write every queued (pre-open) message, in order, as the socket opens.\n\t#flush(socket: WebSocket): void {\n\t\tfor (const text of this.#queue.splice(0)) socket.send(text)\n\t}\n\n\t// Decode one inbound frame: a non-text (binary) frame is rejected without a throw; a\n\t// text frame is `JSON.parse`d → `parseJSONRPCMessage`. A well-formed message re-emits on\n\t// `message`; a malformed / non-message frame surfaces on `error` and is dropped (§14 —\n\t// never throws on adversarial wire input).\n\t#receive(data: unknown): void {\n\t\tif (!isString(data)) {\n\t\t\tthis.#emitter.emit('error', new Error('non-text WebSocket frame'))\n\t\t\treturn\n\t\t}\n\t\tlet parsed: unknown\n\t\ttry {\n\t\t\tparsed = JSON.parse(data)\n\t\t} catch (error) {\n\t\t\tthis.#emitter.emit('error', error)\n\t\t\treturn\n\t\t}\n\t\tconst message = parseJSONRPCMessage(parsed)\n\t\tif (message === undefined) {\n\t\t\tthis.#emitter.emit('error', new Error('non-JSON-RPC WebSocket frame'))\n\t\t\treturn\n\t\t}\n\t\tthis.#emitter.emit('message', message)\n\t}\n\n\t// The socket closed underneath us — fire `close` once (a `close()` call already flipped\n\t// `#closed`, so it does not double-emit).\n\t#onClose(): void {\n\t\tif (this.#closed) return\n\t\tthis.#closed = true\n\t\tthis.#socket = undefined\n\t\tthis.#emitter.emit('close')\n\t}\n}\n","import type { ClientTransportInterface, MCPTransportInterface } from '@src/core'\nimport type {\n\tHTTPClientTransportOptions,\n\tMessagePortTransportOptions,\n\tScopeTransportInterface,\n\tServeMCPOptions,\n\tServeMCPScopeInterface,\n\tWebSocketClientTransportOptions,\n} from './types.js'\nimport { bindServer, createMCPServer } from '@src/core'\nimport { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION } from './constants.js'\nimport { createScopeMessageListener } from './helpers.js'\nimport { HTTPClientTransport } from './transports/HTTPClientTransport.js'\nimport { MessagePortTransport } from './transports/MessagePortTransport.js'\nimport { WebSocketClientTransport } from './transports/WebSocketClientTransport.js'\n\n/**\n * Create the browser-face WebSocket CLIENT transport for an\n * {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}\n * that drives a REMOTE MCP server over the native `WebSocket` global, the browser\n * sibling of the Node face's `createWebSocketClientTransport` (`@src/server`).\n *\n * @remarks\n * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)\n * opens `new WebSocket(options.url, options.protocols)` and awaits the native\n * `'open'` event — the RFC 6455 handshake itself is the browser's concern. Each\n * JSON-RPC message the client `send`s before the socket opens is QUEUED and flushed,\n * in order, once it does; each decoded reply is surfaced on the transport's\n * `message` event for the client's id correlation.\n *\n * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional\n *   `protocols` (the WebSocket subprotocol(s) to request); see\n *   {@link WebSocketClientTransportOptions}\n * @returns A working {@link ClientTransportInterface} over the native `WebSocket`\n *\n * @example\n * ```ts\n * import { createMCPClient } from '@orkestrel/mcp'\n * import { createWebSocketClientTransport } from '@orkestrel/mcp/browser'\n *\n * const client = createMCPClient({\n * \ttransport: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),\n * })\n * await client.connect()\n * const tools = await client.tools()\n * ```\n */\nexport function createWebSocketClientTransport(\n\toptions: WebSocketClientTransportOptions,\n): ClientTransportInterface {\n\treturn new WebSocketClientTransport(options)\n}\n\n/**\n * Create the browser-face HTTP CLIENT transport for an\n * {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}\n * that drives a REMOTE Streamable-HTTP MCP server over the native `fetch`, the\n * browser sibling of the Node face's `createHTTPClientTransport` (`@src/server`).\n *\n * @remarks\n * Hand it to `createMCPClient({ transport })`: each JSON-RPC message the client\n * sends is `POST`ed to `options.url` with `content-type: application/json` and an\n * `Accept` of both `application/json` and `text/event-stream` (the server answers\n * with EITHER — a plain JSON envelope or a Streamable-HTTP SSE `data:` event,\n * decoded via `@orkestrel/sse`), and the reply is surfaced on the transport's\n * `message` event for the client's id correlation. Add `options.headers` (e.g. an\n * `Authorization` bearer) to reach a guarded server. `start` / `close` hold no\n * connection; against a STATEFUL server it captures the `mcp-session-id` from\n * `initialize` and echoes it on later requests. It also captures the initialize\n * result's `protocolVersion` and sends `mcp-protocol-version` on every subsequent\n * request, so the same `MCPClient` passes the session and 2025-06-18 protocol\n * gates without caller wiring.\n *\n * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged\n *   onto every request, optional `fetch` (default `globalThis.fetch`), and optional\n *   `timeout` (ms, applied via `AbortSignal.timeout`); see\n *   {@link HTTPClientTransportOptions}\n * @returns A working {@link ClientTransportInterface} over the native `fetch`\n *\n * @example\n * ```ts\n * import { createMCPClient } from '@orkestrel/mcp'\n * import { createHTTPClientTransport } from '@orkestrel/mcp/browser'\n *\n * const client = createMCPClient({\n * \ttransport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),\n * })\n * await client.connect()\n * const tools = await client.tools()\n * ```\n */\nexport function createHTTPClientTransport(\n\toptions: HTTPClientTransportOptions,\n): ClientTransportInterface {\n\treturn new HTTPClientTransport(options)\n}\n\n/**\n * Create the browser-face `MessagePort` transport — a\n * {@link import('@src/core').MCPTransportInterface} over a native `MessagePort`, the\n * SYMMETRIC carrier that works as either a server or a client transport depending on\n * which binder ({@link import('@src/core').bindServer} or\n * {@link import('@src/core').bindClient}) it is handed to.\n *\n * @remarks\n * `port.start()` runs at construction (see {@link MessagePortTransport}'s doc for\n * why); inbound payloads are string-only (a non-string `postMessage` payload is\n * dropped, never thrown); `messageerror` is ignored (one bad frame does not close the\n * channel); `close()` closes the port and fires `closed` exactly once.\n *\n * @param options - `port` (the `MessagePort` half to drive; REQUIRED); see\n *   {@link MessagePortTransportOptions}\n * @returns A working {@link import('@src/core').MCPTransportInterface} over the port\n *\n * @example\n * ```ts\n * import { bindServer, createMCPServer } from '@orkestrel/mcp'\n * import { createMessagePortTransport } from '@orkestrel/mcp/browser'\n *\n * const { port1, port2 } = new MessageChannel()\n * bindServer(createMCPServer({ name: 's', version: '1.0.0', tools }), createMessagePortTransport({ port: port1 }))\n * ```\n */\nexport function createMessagePortTransport(\n\toptions: MessagePortTransportOptions,\n): MCPTransportInterface {\n\treturn new MessagePortTransport(options)\n}\n\n/**\n * Adapt a hostable {@link ServeMCPScopeInterface} (`self` in a dedicated Web Worker,\n * or any structurally matching double) into a {@link ScopeTransportInterface} — the\n * implicit, portless message channel `serveMCPScope` binds for the\n * dedicated-worker shape.\n *\n * @remarks\n * `send` writes each outbound string via `scope.postMessage`. `listen`/`closed`\n * register the SINGLE handler `deliver` / the underlying close path route through —\n * `serveMCPScope`'s own `scope` `message`-event listener calls `deliver(event.data)`\n * for every portless, string-payload event (there is no native registration point on\n * the scope itself for `serveMCPScope` to hand a `listen` handler to, so `deliver` is\n * the bridge). `close()` fires the registered `closed` handler — a scope has nothing\n * physically closable, so this is the only teardown signal available.\n *\n * @param scope - The hostable scope to adapt (structurally, `self` / `globalThis`\n *   inside a dedicated Web Worker)\n * @returns A {@link ScopeTransportInterface} `serveMCPScope` binds and drives via `deliver`\n *\n * @example\n * ```ts\n * const scopeTransport = createScopeTransport(self)\n * const unbind = bindServer(server, scopeTransport)\n * ```\n */\nexport function createScopeTransport(scope: ServeMCPScopeInterface): ScopeTransportInterface {\n\tlet onMessage: ((message: string) => void) | undefined\n\tlet onClosed: (() => void) | undefined\n\treturn {\n\t\tsend(message: string): void {\n\t\t\tscope.postMessage(message)\n\t\t},\n\t\tlisten(handler: (message: string) => void): void {\n\t\t\tonMessage = handler\n\t\t},\n\t\tclosed(handler: () => void): void {\n\t\t\tonClosed = handler\n\t\t},\n\t\tclose(): void {\n\t\t\tonClosed?.()\n\t\t},\n\t\tdeliver(message: string): void {\n\t\t\tonMessage?.(message)\n\t\t},\n\t}\n}\n\n/**\n * Boot an `MCPServer` inside a hostable worker scope and wire its message events to it.\n *\n * @remarks\n * Port-bearing events are gated by `options.accept`, deduplicated by port, and receive\n * their own `MessagePortTransport` binding. Portless string events use the scope's\n * implicit channel. The returned disposer removes the listener, unbinds the implicit\n * channel, and closes every accepted port binding.\n *\n * @param scope - The hostable worker scope to wire\n * @param options - The tools, optional identity, and optional port-event gate\n * @returns An idempotent disposer for every binding owned by this call\n */\nexport function serveMCPScope(scope: ServeMCPScopeInterface, options: ServeMCPOptions): () => void {\n\tconst server = createMCPServer({\n\t\ttools: options.tools,\n\t\tname: options.name ?? DEFAULT_MCP_SERVER_NAME,\n\t\tversion: options.version ?? DEFAULT_MCP_SERVER_VERSION,\n\t})\n\tconst scopeTransport = createScopeTransport(scope)\n\tconst unbindScope = bindServer(server, scopeTransport)\n\tconst teardowns = new Set<() => void>()\n\tconst onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)\n\tscope.addEventListener('message', onMessage)\n\tlet disposed = false\n\treturn () => {\n\t\tif (disposed) return\n\t\tdisposed = true\n\t\tscope.removeEventListener('message', onMessage)\n\t\tunbindScope()\n\t\tfor (const teardown of teardowns) teardown()\n\t\tteardowns.clear()\n\t}\n}\n\n/**\n * Boot an `MCPServer` inside the current hostable worker scope.\n *\n * @param options - The tools, optional identity, and optional port-event gate\n * @returns The disposer returned by {@link serveMCPScope}\n */\nexport function serveMCP(options: ServeMCPOptions): () => void {\n\treturn serveMCPScope(globalThis, options)\n}\n"],"mappings":"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"}

package/dist/src/core/index.cjs

@@ -6,15 +6,16 @@ let _orkestrel_agent = require("@orkestrel/agent");
 /** The MCP protocol revision this server implements (the default negotiated version). */
 var MCP_PROTOCOL_VERSION = "2025-06-18";
 /**
-* The MCP protocol revisions this server can negotiate — the current
-* {@link MCP_PROTOCOL_VERSION} plus a prior rev a client may still request.
+* The MCP protocol revisions this server can negotiate.
 *
 * @remarks
 * `initialize` echoes the client's requested `protocolVersion` when it appears in
 * this list, else falls back to {@link MCP_PROTOCOL_VERSION}. Frozen so the list is
-* an immutable contract.
+* an immutable contract. The package does not advertise `2025-03-26` because that
+* revision mandates JSON-RPC batching, while this package accepts only individual
+* JSON-RPC messages.
 */
-var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-06-18", "2025-03-26"]);
+var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-06-18"]);
 /** JSON-RPC 2.0 reserved error: invalid JSON was received (the message did not parse). */
 var JSONRPC_PARSE_ERROR = -32700;
 /** JSON-RPC 2.0 reserved error: the payload was not a valid Request object. */
@@ -35,6 +36,61 @@ var DEFAULT_MCP_CLIENT_VERSION = "1.0.0";
 */
 var DEFAULT_MCP_REQUEST_TIMEOUT = 3e4;
 //#endregion
+//#region src/core/errors.ts
+/**
+* A remote Model Context Protocol JSON-RPC error, preserving its machine-readable
+* numeric code and optional structured context.
+*
+* @remarks
+* {@link MCPClient} throws this error only for a remote JSON-RPC `error` response.
+* Local lifecycle and transport conditions such as disconnects and request timeouts
+* remain plain `Error`s. `context` carries the response's optional `error.data`
+* unchanged and is `undefined` when the peer omitted it.
+*
+* @example
+* ```ts
+* const error = new MCPError('Method not found', -32601, { method: 'missing' })
+* error.code // -32601
+* error.context // { method: 'missing' }
+* ```
+*/
+var MCPError = class extends Error {
+	name = "MCPError";
+	code;
+	context;
+	/**
+	* Create a remote MCP protocol error.
+	*
+	* @param message - The human-readable JSON-RPC error message
+	* @param code - The machine-readable numeric JSON-RPC error code
+	* @param context - The optional JSON-RPC `error.data` payload
+	*/
+	constructor(message, code, context) {
+		super(message);
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Determine whether an unknown value is an {@link MCPError}.
+*
+* @param value - The unknown value to inspect
+* @returns `true` only when the value is an `MCPError`
+*
+* @example
+* ```ts
+* isMCPError(new MCPError('Method not found', -32601)) // true
+* isMCPError(new Error('Method not found')) // false
+* ```
+*/
+function isMCPError(value) {
+	try {
+		return value instanceof MCPError;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/core/validators.ts
 /**
 * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,
@@ -314,18 +370,16 @@ function initializeResult(name, version, requested) {
 */
 function bindServer(server, transport) {
 	let active = true;
-	transport.listen((message) => {
+	transport.listen(async (message) => {
 		if (!active) return;
-		(async () => {
+		try {
+			const response = await server.handle(message);
+			if (response !== void 0) await transport.send(response);
+		} catch (error) {
 			try {
-				const response = await server.handle(message);
-				if (response !== void 0) await transport.send(response);
-			} catch (error) {
-				try {
-					server.emitter.emit("error", error);
-				} catch {}
-			}
-		})();
+				server.emitter.emit("error", error);
+			} catch {}
+		}
 	});
 	transport.closed(() => {
 		active = false;
@@ -450,8 +504,8 @@ var MCPServer = class {
 	#tools;
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter({
-			on: options.on,
-			error: options.error
+			...options.on !== void 0 ? { on: options.on } : {},
+			...options.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#name = options.name;
 		this.#version = options.version;
@@ -516,8 +570,9 @@ var MCPServer = class {
 *
 * @remarks
 * - **The mirror of `MCPServer`.** The server DISPATCHES requests over a tool registry;
-*   this client ISSUES them over a transport. `connect` runs `initialize` then sends
-*   `notifications/initialized`; `tools()` lists the remote tools and wraps each as a
+*   this client ISSUES them over a transport. `connect` runs `initialize`, validates and
+*   exposes the negotiated `protocol`, then sends `notifications/initialized`; `tools()`
+*   lists the remote tools and wraps each as a
 *   local {@link ToolInterface} whose `execute` calls back through `call`; `call` runs a
 *   remote `tools/call` and returns the tool's value (a remote `isError: true` throws
 *   locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}
@@ -554,10 +609,11 @@ var MCPClient = class {
 	#pending = /* @__PURE__ */ new Map();
 	#nextId = 0;
 	#connected = false;
+	#protocol = void 0;
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter({
-			on: options.on,
-			error: options.error
+			...options.on !== void 0 ? { on: options.on } : {},
+			...options.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#transport = options.transport;
 		this.#name = options.name ?? "taverna";
@@ -571,6 +627,9 @@ var MCPClient = class {
 	get connected() {
 		return this.#connected;
 	}
+	get protocol() {
+		return this.#protocol;
+	}
 	get transport() {
 		return this.#transport;
 	}
@@ -580,7 +639,7 @@ var MCPClient = class {
 	async connect() {
 		if (this.#connected) return;
 		await this.#transport.start();
-		await this.#request("initialize", {
+		const result = await this.#request("initialize", {
 			protocolVersion: MCP_PROTOCOL_VERSION,
 			capabilities: {},
 			clientInfo: {
@@ -588,6 +647,13 @@ var MCPClient = class {
 				version: this.#version
 			}
 		});
+		const protocol = (0, _orkestrel_contract.isRecord)(result) ? result["protocolVersion"] : void 0;
+		if (!(0, _orkestrel_contract.isString)(protocol) || !SUPPORTED_PROTOCOL_VERSIONS.includes(protocol)) {
+			await this.#transport.close();
+			if ((0, _orkestrel_contract.isString)(protocol)) throw new Error(`MCP server negotiated unsupported protocol version '${protocol}'`);
+			throw new Error("MCP server returned a non-string protocol version");
+		}
+		this.#protocol = protocol;
 		this.#connected = true;
 		await this.#transport.send({
 			jsonrpc: "2.0",
@@ -598,8 +664,8 @@ var MCPClient = class {
 	async disconnect() {
 		if (!this.#connected) return;
 		this.#connected = false;
-		for (const pending of this.#pending.values()) pending.reject(/* @__PURE__ */ new Error("MCP client disconnected"));
-		this.#pending.clear();
+		this.#protocol = void 0;
+		for (const id of this.#pending.keys()) this.#settle(id, /* @__PURE__ */ new Error("MCP client disconnected"), true);
 		await this.#transport.close();
 		this.#emitter.emit("disconnect");
 	}
@@ -639,38 +705,24 @@ var MCPClient = class {
 		};
 		return new Promise((resolve, reject) => {
 			const deadline = AbortSignal.timeout(this.#timeout);
-			const settle = () => {
-				this.#pending.delete(id);
-				deadline.removeEventListener("abort", onDeadline);
-			};
-			const onDeadline = () => {
-				settle();
-				reject(/* @__PURE__ */ new Error(`MCP request '${method}' timed out after ${this.#timeout}ms`));
-			};
-			deadline.addEventListener("abort", onDeadline, { once: true });
+			const timeout = this.#timeoutRequest.bind(this, id, method);
+			deadline.addEventListener("abort", timeout, { once: true });
 			this.#pending.set(id, {
-				resolve: (value) => {
-					settle();
-					resolve(value);
-				},
-				reject: (error) => {
-					settle();
-					reject(error);
-				}
+				resolve,
+				reject,
+				deadline,
+				timeout
 			});
 			this.#transport.send(request).catch((error) => {
-				const pending = this.#pending.get(id);
-				if (pending === void 0) return;
-				pending.reject(error instanceof Error ? error : new Error(String(error)));
+				this.#settle(id, error instanceof Error ? error : new Error(String(error)), true);
 			});
 		});
 	}
 	#receive(message) {
 		if (isJSONRPCResponse(message) && isRequestId(message.id)) {
-			const pending = this.#pending.get(message.id);
-			if (pending !== void 0) {
-				if (message.error !== void 0) pending.reject(/* @__PURE__ */ new Error(`MCP error ${message.error.code}: ${message.error.message}`));
-				else pending.resolve(message.result);
+			if (this.#pending.has(message.id)) {
+				if (message.error !== void 0) this.#settle(message.id, new MCPError(message.error.message, message.error.code, message.error.data), true);
+				else this.#settle(message.id, message.result, false);
 				return;
 			}
 		}
@@ -681,7 +733,7 @@ var MCPClient = class {
 		const description = descriptor["description"];
 		const options = {
 			name,
-			execute: (args) => this.call(name, args)
+			execute: this.call.bind(this, name)
 		};
 		if ((0, _orkestrel_contract.isString)(description)) options.description = description;
 		if ((0, _orkestrel_contract.isRecord)(inputSchema)) options.parameters = inputSchema;
@@ -693,6 +745,17 @@ var MCPClient = class {
 		for (const block of result["content"]) if ((0, _orkestrel_contract.isRecord)(block) && (0, _orkestrel_contract.isString)(block["text"])) parts.push(block["text"]);
 		return parts.join("\n");
 	}
+	#timeoutRequest(id, method) {
+		this.#settle(id, /* @__PURE__ */ new Error(`MCP request '${method}' timed out after ${this.#timeout}ms`), true);
+	}
+	#settle(id, value, failed) {
+		const pending = this.#pending.get(id);
+		if (pending === void 0) return;
+		this.#pending.delete(id);
+		pending.deadline.removeEventListener("abort", pending.timeout);
+		if (failed) pending.reject(value);
+		else pending.resolve(value);
+	}
 };
 //#endregion
 //#region src/core/factories.ts
@@ -742,7 +805,8 @@ function createMCPServer(options) {
 * @remarks
 * The egress mirror of {@link createMCPServer}: where the server exposes a local tool
 * registry over MCP, the client USES a remote server's tools. `connect()` handshakes,
-* `tools()` lists + wraps the remote tools (each `execute` calls back over the wire),
+* validates and exposes the negotiated protocol, `tools()` lists + wraps the remote
+* tools (each `execute` calls back over the wire),
 * and `call(name, args)` runs a remote `tools/call` (a remote tool failure throws
 * locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}
 * isolates it). The transport is injected — a concrete one (the HTTP transport over
@@ -780,8 +844,8 @@ function createMCPClient(options) {
 * @remarks
 * Hand the RESULT to `createMCPClient({ transport })`, then pass the SAME
 * `transport` to {@link import('./helpers.js').bindClient} to complete the inbound
-* wiring: `send` serializes each outbound {@link JSONRPCMessage} (or batch, one per
-* message) and writes it via `transport.send`; `close` closes the underlying
+* wiring: `send` serializes each outbound {@link JSONRPCMessage} and writes it via
+* `transport.send`; `close` closes the underlying
 * `transport`; `start` is a no-op (the duplex channel is already open by the time
 * it is handed in — there is no separate connect step at this layer); `session` is
 * always `undefined` (session correlation is a higher-level concern the duplex port
@@ -805,8 +869,7 @@ function createDuplexClientTransport(transport) {
 		session: void 0,
 		async start() {},
 		async send(message) {
-			const messages = Array.isArray(message) ? message : [message];
-			for (const one of messages) await transport.send(JSON.stringify(one));
+			await transport.send(JSON.stringify(message));
 		},
 		async close() {
 			await transport.close();
@@ -823,6 +886,7 @@ exports.JSONRPC_METHOD_NOT_FOUND = JSONRPC_METHOD_NOT_FOUND;
 exports.JSONRPC_PARSE_ERROR = JSONRPC_PARSE_ERROR;
 exports.JSONRPC_SERVER_ERROR = JSONRPC_SERVER_ERROR;
 exports.MCPClient = MCPClient;
+exports.MCPError = MCPError;
 exports.MCPServer = MCPServer;
 exports.MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSION;
 exports.SUPPORTED_PROTOCOL_VERSIONS = SUPPORTED_PROTOCOL_VERSIONS;
@@ -838,6 +902,7 @@ exports.isInitializeRequest = isInitializeRequest;
 exports.isJSONRPCMessage = isJSONRPCMessage;
 exports.isJSONRPCRequest = isJSONRPCRequest;
 exports.isJSONRPCResponse = isJSONRPCResponse;
+exports.isMCPError = isMCPError;
 exports.isRequestId = isRequestId;
 exports.jsonRPCError = jsonRPCError;
 exports.jsonRPCResult = jsonRPCResult;