@orkestrel/mcp 0.0.26 → 0.0.28

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

@@ -16,7 +16,7 @@ import { ToolResult } from '@orkestrel/tool';
  * @remarks
  * The client's outbound writes flow through `client.transport.send` — its existing,
  * unmodified request/response correlation — so `client` must have been constructed
- * with a {@link import('./types.js').MCPClientTransportInterface} that itself carries
+ * with a {@link import('./types.js').MCPMessageTransportInterface} that itself carries
  * the SAME `transport` (see {@link import('./factories.js').createDuplexClientTransport},
  * the additive factory that adapts an {@link MCPTransportInterface} into that shape);
  * this binder then completes the inbound half by decoding each message and pushing it
@@ -155,7 +155,7 @@ export declare function buildCallOutcome(name: string, result: unknown): MCPCall
  * rather than as a violation.
  *
  * Only write one on a carrier that accepts a client-initiated notification — see
- * {@link import('./types.js').MCPClientTransportInterface.duplex}. On Streamable HTTP the
+ * {@link import('./types.js').MCPMessageTransportInterface.duplex}. On Streamable HTTP the
  * dated revision defines no such frame, and closing the response stream is the
  * cancellation signal instead.
  *
@@ -189,6 +189,60 @@ export declare function buildCancelledNotification(id: JSONRPCId, reason?: strin
  */
 export declare function buildDiscoverResult(options: MCPServerOptions): MCPDiscoverResult;
 
+/**
+ * Builds the `x-mcp-header` projections one tool's `inputSchema` declares.
+ *
+ * @remarks
+ * The single decision both sides of the protocol make about an annotated tool: an HTTP
+ * CLIENT excludes a definition this refuses from the `tools/list` result it delivers, and a
+ * SERVER recognizes exactly the `Mcp-Param-*` names this returns for its own definitions.
+ *
+ * `undefined` means the definition is invalid, and every rule the protocol states produces
+ * it: a value that is not an RFC 9110 token, a non-primitive or untyped annotated leaf, a
+ * name repeated case-insensitively within the schema, an annotation the `properties` chain
+ * does not reach, and a schema that is not a record at all. An empty list is the valid answer
+ * for a schema carrying no annotation.
+ *
+ * Total — never throws, and a cyclic or stack-hostile schema is refused rather than followed.
+ *
+ * @param schema - The tool's advertised `inputSchema`
+ * @returns The declared projections, or `undefined` when the definition is invalid
+ *
+ * @example
+ * ```ts
+ * buildHeaderParameters({
+ * 	type: 'object',
+ * 	properties: { region: { type: 'string', 'x-mcp-header': 'Region' } },
+ * }) // → [{ name: 'Region', path: ['region'], primitive: 'string' }]
+ * ```
+ */
+export declare function buildHeaderParameters(schema: unknown): readonly MCPHeaderParameter[] | undefined;
+
+/**
+ * Builds the `Mcp-Param-*` request headers one `tools/call` carries.
+ *
+ * @remarks
+ * The projection SEP-2243 requires of an HTTP client, and the same derivation a server runs
+ * to know what the request must carry. Each parameter's value is read at its exact
+ * property path in the call's own `arguments`; an absent or `null` value omits its header
+ * entirely, which is the protocol's distinction between "not supplied" and "supplied empty".
+ * The rendered text then travels through {@link encodeSentinel}, so a value carrying
+ * non-ASCII, control, or edge whitespace characters reaches the peer intact.
+ *
+ * @param parameters - The projections the tool's `inputSchema` declares
+ * @param values - The call's `arguments` record
+ * @returns The header field names and values, empty when nothing projects
+ *
+ * @example
+ * ```ts
+ * buildHeaderProjection(
+ * 	[{ name: 'Region', path: ['region'], primitive: 'string' }],
+ * 	{ region: 'us-west1' },
+ * ) // → { 'Mcp-Param-Region': 'us-west1' }
+ * ```
+ */
+export declare function buildHeaderProjection(parameters: readonly MCPHeaderParameter[], values: unknown): Readonly<Record<string, string>>;
+
 /**
  * Builds the MCP `initialize` result — the negotiated protocol version, the
  * advertised capabilities, and the server identity.
@@ -304,6 +358,20 @@ export declare function buildModernResult<T extends object>(result: T, identity:
  */
 export declare function buildProgressNotification(token: string | number, progress: MCPProgress): JSONRPCNotification;
 
+/**
+ * Builds the error for a non-success HTTP response that carried no JSON-RPC message.
+ *
+ * @param response - The response whose status is reported
+ * @param type - The response's content type, or an empty string when absent
+ * @returns An error naming the HTTP status and unsupported response shape
+ *
+ * @example
+ * ```ts
+ * const error = buildResponseError(new Response('', { status: 500 }), '')
+ * ```
+ */
+export declare function buildResponseError(response: Response, type: string): Error;
+
 /**
  * Builds the first notification carrying a subscription id for a listen request.
  *
@@ -358,9 +426,68 @@ export declare function buildToolCall(request: JSONRPCRequest, caller?: unknown,
  */
 export declare function buildToolDescriptors(manager: ToolManagerInterface): readonly MCPToolDescriptor[];
 
+/**
+ * Computes the capabilities one round of input requests needs and the client did not declare.
+ *
+ * @remarks
+ * The protocol's rule is about SENDING: a server never issues a request kind the client's
+ * declared capabilities exclude. So this reads the round rather than the method, and it
+ * answers with the refusal's own payload — the `requiredCapabilities` record a
+ * `MissingRequiredClientCapability` error carries, keyed by each missing capability, in the
+ * `ClientCapabilities` shape the schema defines rather than as a list of names.
+ *
+ * Each kind maps to one declaration: `sampling/createMessage` to `sampling`, `roots/list` to
+ * `roots`, a form elicitation to what {@link supportsFormElicitation} accepts, and a
+ * URL-mode elicitation to a record-valued `elicitation.url`. A request this package cannot
+ * recognize needs nothing, because {@link import('./validators.js').isMCPInputRequestMap}
+ * has already refused the round it would have travelled in. Total over hostile input.
+ *
+ * The `elicitation` value names the ARM the round needs, so a client can act on the refusal
+ * by declaring exactly what the payload asks for. A missing URL arm answers `{ url: {} }`, a
+ * missing form arm answers the empty record this package reads as form-only, and a round
+ * needing both answers `{ form: {}, url: {} }`. An empty record for a URL round would name
+ * the declaration a URL-capable client already sent, and refuse the identical round again.
+ *
+ * @param requests - The round the server is about to issue
+ * @param capabilities - The client capability record the request declared
+ * @returns The missing capabilities, or `undefined` when the client declared every one
+ *
+ * @example
+ * ```ts
+ * computeMissingCapabilities({ answer: { method: 'roots/list' } }, {}) // { roots: {} }
+ * computeMissingCapabilities({ answer: { method: 'roots/list' } }, { roots: {} }) // undefined
+ * ```
+ */
+export declare function computeMissingCapabilities(requests: MCPInputRequestMap, capabilities: unknown): MCPClientCapabilities | undefined;
+
+/**
+ * Counts every {@link MCP_HEADER_ANNOTATION} key one JSON value carries, at any position.
+ *
+ * @remarks
+ * The companion of {@link extractHeaderAnnotations}, which reads only the annotations a
+ * `properties` chain reaches. Comparing the two answers is how
+ * {@link buildHeaderParameters} decides reachability without a second walk that would have
+ * to re-state which JSON Schema keywords are traversable: an annotation the reachable walk
+ * did not read is one sitting under `items`, a composition or conditional keyword, a `$ref`
+ * target, or any other position, and the protocol makes the whole tool definition invalid for
+ * it.
+ *
+ * Iterative and ancestor-tracked, so a deeply nested or self-referential value terminates
+ * rather than exhausting the stack. Total — never throws, whatever the input.
+ *
+ * @param value - The value to scan, normally a tool's `inputSchema`
+ * @returns How many annotation keys the value carries
+ *
+ * @example
+ * ```ts
+ * countHeaderAnnotations({ properties: { region: { 'x-mcp-header': 'Region' } } }) // 1
+ * ```
+ */
+export declare function countHeaderAnnotations(value: unknown): number;
+
 /**
  * Adapts an {@link MCPTransportInterface} (the environment-agnostic duplex message
- * channel) into a {@link MCPClientTransportInterface} — the additive bridge that lets
+ * channel) into a {@link MCPMessageTransportInterface} — the additive bridge that lets
  * `createMCPClient` run over the new port without any change to `MCPClient`'s
  * existing shape.
  *
@@ -383,7 +510,7 @@ export declare function buildToolDescriptors(manager: ToolManagerInterface): rea
  * capable emitter for `bindClient` to push onto.
  *
  * @param transport - The duplex channel to adapt
- * @returns A {@link MCPClientTransportInterface} `createMCPClient` can drive
+ * @returns A {@link MCPMessageTransportInterface} `createMCPClient` can drive
  *
  * @example
  * ```ts
@@ -392,11 +519,11 @@ export declare function buildToolDescriptors(manager: ToolManagerInterface): rea
  * await client.connect()
  * ```
  */
-export declare function createDuplexClientTransport(transport: MCPTransportInterface): MCPClientTransportInterface;
+export declare function createDuplexClientTransport(transport: MCPTransportInterface): MCPMessageTransportInterface;
 
 /**
  * Creates a transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE
- * MCP server over an injected {@link import('./types.js').MCPClientTransportInterface},
+ * MCP server over an injected {@link import('./types.js').MCPMessageTransportInterface},
  * negotiates the modern revision through `server/discover`, and exposes the server's tools as local
  * {@link import('@orkestrel/tool').ToolInterface}s an agent can run.
  *
@@ -427,7 +554,7 @@ export declare function createDuplexClientTransport(transport: MCPTransportInter
  * })
  * await client.connect()
  * agent.context.tools.add(await client.tools()) // give the agent the remote tools
- * const value = await client.call('search', { query: 'mcp' })
+ * const outcome = await client.call('search', { query: 'mcp' })
  * ```
  */
 export declare function createMCPClient(options: MCPClientOptions): MCPClientInterface;
@@ -455,14 +582,14 @@ export declare function createMCPLegacy(server: MCPServerInterface): MCPDispatch
  * client.version // '2026-07-28'
  * ```
  */
-export declare function createMCPLegacyClientTransport(transport: MCPClientTransportInterface, options?: MCPLegacyClientTransportOptions): MCPClientTransportInterface;
+export declare function createMCPLegacyClientTransport(transport: MCPMessageTransportInterface, options?: MCPLegacyClientTransportOptions): MCPMessageTransportInterface;
 
 /**
  * Creates a transport-agnostic Model Context Protocol server — exposes a live
  * {@link import('@orkestrel/tool').ToolManagerInterface} and an optional
  * {@link import('./types.js').MCPResourceManagerInterface},
  * {@link import('./types.js').MCPPromptManagerInterface}, and
- * {@link import('./types.js').MCPCompletionManagerInterface} over JSON-RPC 2.0.
+ * {@link import('./types.js').MCPCompletionInterface} over JSON-RPC 2.0.
  *
  * @remarks
  * Pump raw message strings through `handle` (parse → dispatch → serialize) from a
@@ -505,7 +632,7 @@ export declare function createMCPServer(options: MCPServerOptions): MCPServerInt
  *
  * @remarks
  * The bound is checked FIRST, against the raw string, so an oversized message is never
- * `JSON.parse`d at all: a decoder that parses before it measures has already spent the work
+ * parsed at all: a decoder that parses before it measures has already spent the work
  * the bound exists to refuse. A message over the bound, malformed JSON, and a well-formed
  * value that is not a JSON-RPC message are one answer — `undefined` — because a binder does
  * exactly the same thing with each of them: nothing, and let
@@ -526,7 +653,76 @@ export declare function createMCPServer(options: MCPServerOptions): MCPServerInt
 export declare function decodeBoundedMessage(message: string, limits: MCPJSONLimitOptions): JSONRPCMessage | undefined;
 
 /**
- * Default modern result freshness lifetime in milliseconds.
+ * Decodes one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
+ * when it is not one — the per-event step {@link readEventStream} folds over.
+ *
+ * @remarks
+ * Parses the `data` (a peer serializes the JSON-RPC envelope as the event's `data`) with
+ * `@orkestrel/contract`'s `parseJSON` — the declared JSON boundary, which answers `undefined`
+ * instead of throwing — and narrows the parsed value with `parseJSONRPCMessage`. Total:
+ * malformed JSON or a non-message value yields `undefined`, never throws.
+ *
+ * @param data - One SSE event's `data` payload
+ * @returns The decoded {@link JSONRPCMessage}, or `undefined`
+ *
+ * @example
+ * ```ts
+ * decodeEvent('{"jsonrpc":"2.0","id":1,"result":{}}') // the decoded response
+ * ```
+ */
+export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
+
+/**
+ * Reads the value one standard MCP request header carries, decoding the Base64 sentinel.
+ *
+ * @remarks
+ * The sentinel format is `=?base64?{Base64OfUTF8}?=`, spelled once as
+ * {@link MCP_SENTINEL_PREFIX} and {@link MCP_SENTINEL_SUFFIX} and read from there by both
+ * directions of the codec.
+ * The markers alone decide whether a value is a sentinel: a value carrying the prefix and the
+ * suffix is one, and its payload is then held to `decodeBase64` from `@orkestrel/codec` — the
+ * canonical RFC 4648 § 4 grammar, which admits exactly one spelling per byte sequence — and to
+ * well-formed UTF-8. A payload leaving a non-zero bit in the sextet its padding discards is a
+ * second spelling of a byte, so it is refused: `=?base64?QR==?=` reaches for the byte
+ * `=?base64?QQ==?=` spells canonically, and only the canonical spelling decodes. A malformed
+ * payload answers `undefined` rather than falling back to the literal, because the protocol
+ * requires a server to REJECT invalid characters, and a fallback would admit the very value
+ * the rule exists to refuse. A value missing either marker is a literal and comes back
+ * unchanged.
+ *
+ * `decodeUTF8` from `@orkestrel/codec` reads the bytes back as text: strict RFC 3629, where an
+ * overlong, an encoded surrogate, a code point past U+10FFFF, and a truncated sequence each
+ * answer `undefined` rather than a replacement character, and total, so the refusal arrives as
+ * that value instead of as a throw. It also keeps a leading U+FEFF as a character of the
+ * value, where the platform decoder consumes it as a byte order mark — which is what lets a
+ * value leading with U+FEFF survive {@link encodeSentinel} and come back whole.
+ *
+ * {@link import('./validators.js').isStandardBase64} is a wider and separate rule: it names
+ * JSON Schema `byte` membership for the blob, image, and audio content a peer sends, where
+ * this package receives liberally. It does not govern this payload.
+ *
+ * Optional whitespace is excluded first, per RFC 9110 § 5.5: a recipient parses a field value
+ * with its surrounding spaces and horizontal tabs removed, so a peer that padded a plain value
+ * still matches the body. A value whose own leading or trailing whitespace is significant
+ * cannot survive that, which is what {@link encodeSentinel} encodes it for.
+ *
+ * Total — never throws, whatever the input.
+ *
+ * @param value - The raw header field value the peer sent
+ * @returns The carried value, or `undefined` when the sentinel's payload is invalid
+ *
+ * @example
+ * ```ts
+ * decodeSentinel('=?base64?Y2Fmw6k=?=') // 'café'
+ * decodeSentinel('  search  ') // 'search' — optional whitespace excluded
+ * decodeSentinel('=?base64?SGVsbG8?=') // undefined — invalid padding
+ * decodeSentinel('=?base64?QR==?=') // undefined — a non-canonical spelling
+ * ```
+ */
+export declare function decodeSentinel(value: string): string | undefined;
+
+/**
+ * Sets the default modern result freshness lifetime in milliseconds.
  *
  * @remarks
  * `ttlMs` is required on cacheable results, while zero means immediately stale
@@ -534,23 +730,31 @@ export declare function decodeBoundedMessage(message: string, limits: MCPJSONLim
  */
 export declare const DEFAULT_MCP_CACHE_TTL = 60000;
 
-/** The default client name reported in the MCP `initialize` handshake (`clientInfo.name`). */
-export declare const DEFAULT_MCP_CLIENT_NAME = "taverna";
+/**
+ * Supplies the default client name reported in the MCP `initialize` handshake
+ * (`clientInfo.name`).
+ */
+export declare const DEFAULT_MCP_CLIENT_NAME = "@orkestrel/mcp";
 
-/** The default client version reported in the MCP `initialize` handshake (`clientInfo.version`). */
+/**
+ * Supplies the default client version reported in the MCP `initialize` handshake
+ * (`clientInfo.version`).
+ */
 export declare const DEFAULT_MCP_CLIENT_VERSION = "1.0.0";
 
 /**
- * Secure server bounds used when the matching `limit` option leaf is absent or malformed.
+ * Sets the secure server bounds used when the matching `limit` option leaf is absent or
+ * malformed.
  *
  * @remarks
  * One MiB admits ordinary JSON-RPC requests and substantial tool arguments; 16 KiB admits
  * extension-rich modern metadata and signed multi-round state; four MiB admits substantial
  * JSON tool output without allowing an unconfigured service to serialize arbitrary process
- * memory; 64 metadata keys admits the reserved keys plus many extensions; 128 concurrent
- * streams admits a busy service while bounding retained producers; depth 32 admits ordinary
- * JSON documents while rejecting stack-hostile nesting. Frozen so callers cannot alter the
- * defaults observed by later servers.
+ * memory; 64 keys admits `_meta`'s reserved keys plus many extensions, and bounds a produced
+ * result's breadth by the same leaf; 128 concurrent streams admits a busy service while
+ * bounding retained producers; depth 32 admits ordinary JSON documents while rejecting
+ * stack-hostile nesting. Frozen so callers cannot alter the defaults observed by later
+ * servers.
  */
 export declare const DEFAULT_MCP_LIMITS: Readonly<{
     message: 1048576;
@@ -563,14 +767,39 @@ export declare const DEFAULT_MCP_LIMITS: Readonly<{
 }>;
 
 /**
- * The default per-request deadline (ms) an `MCPClient` applies when `options.timeout`
+ * Sets the default per-request deadline (ms) an `MCPClient` applies when `options.timeout`
  * is unset — a request the remote server does not answer within it rejects.
  */
 export declare const DEFAULT_MCP_REQUEST_TIMEOUT = 30000;
 
-/** The default number of subscription frames retained while no client read is parked. */
+/** Sets the default number of subscription frames retained while no client read is parked. */
 export declare const DEFAULT_MCP_SUBSCRIPTION_CAPACITY = 64;
 
+/**
+ * Decodes one inbound frame and delivers it onto a transport emitter as `message` or `error`.
+ *
+ * @remarks
+ * The ONE inbound fold every message-carrying transport in this package runs: parse the frame,
+ * narrow it with `parseJSONRPCMessage`, emit `message` for a well-formed
+ * {@link JSONRPCMessage}, and emit `error` for anything else. Total — an adversarial frame
+ * produces an `error` emission and never a throw.
+ *
+ * The two failures report differently on purpose. Unparsable text emits the CAUGHT parse
+ * error, which names the offending position; well-formed JSON that is not a JSON-RPC message
+ * has no caught value to report, so it emits `fault` — the carrier's own wording, passed in
+ * rather than forked into a second copy of this body.
+ *
+ * @param emitter - The transport's emitter to deliver onto
+ * @param text - One inbound frame's raw text
+ * @param fault - The message for the error emitted when the frame parses but is not JSON-RPC
+ *
+ * @example
+ * ```ts
+ * deliverMessage(transport.emitter, frame, 'non-JSON-RPC WebSocket frame')
+ * ```
+ */
+export declare function deliverMessage(emitter: EmitterInterface<MCPMessageTransportEventMap>, text: string, fault: string): void;
+
 /**
  * Computes a lowercase host-neutral SHA-256 digest of one bounded canonical JSON value.
  *
@@ -581,7 +810,7 @@ export declare const DEFAULT_MCP_SUBSCRIPTION_CAPACITY = 64;
 export declare function digestJSON(value: unknown, limits: MCPJSONLimitOptions): Promise<string | undefined>;
 
 /**
- * The one empty argument record every argument-less modern `tools/call` runs with.
+ * Holds the one empty argument record every argument-less modern `tools/call` runs with.
  *
  * @remarks
  * Frozen and null-prototype, and SHARED: two calls that name no `arguments` receive the same
@@ -596,6 +825,44 @@ export declare function digestJSON(value: unknown, limits: MCPJSONLimitOptions):
  */
 export declare const EMPTY_MCP_ARGUMENTS: Readonly<Record<string, unknown>>;
 
+/**
+ * Builds the wire form one standard MCP request header value must travel as.
+ *
+ * @remarks
+ * The exact inverse of {@link decodeSentinel}, and its membership rule is stated as that
+ * inverse rather than as a second list that could drift: a value travels LITERALLY when it is
+ * plain printable ASCII — every code point in `U+0020`–`U+007E`, the RFC 9110 field-value
+ * range this package admits — and {@link decodeSentinel} gives it back unchanged. Every other
+ * value travels wrapped in {@link MCP_SENTINEL_PREFIX} and {@link MCP_SENTINEL_SUFFIX}, the
+ * same markers the decode recognizes a sentinel by. `encodeBase64` from `@orkestrel/codec`
+ * spells the payload, so the wire form carries the canonical spelling {@link decodeSentinel}
+ * accepts.
+ *
+ * That one rule covers each row of the protocol's encoding table. A non-ASCII value and a
+ * value carrying a control character fail the ASCII test. A value with leading or trailing
+ * whitespace comes back trimmed, so it fails the round trip. A value already wearing the
+ * sentinel markers decodes to something else, or to nothing, so it fails the round trip too
+ * and is encoded rather than read back as a sentinel it never was.
+ *
+ * The bytes come from the platform `TextEncoder`, not from codec's `encodeUTF8`, and that is a
+ * ruling rather than an oversight. `TextEncoder` is total: it spells ill-formed text — a lone
+ * surrogate, which has no UTF-8 spelling — with the replacement character, so this function
+ * answers a `string` for every input. `encodeUTF8` refuses that text with `undefined`, which
+ * would widen this return to `string | undefined` and oblige every header projection to handle
+ * a value it cannot send. The decode side carries no such tension, so it reads back through
+ * codec's strict `decodeUTF8`.
+ *
+ * @param value - The value the header must carry
+ * @returns The literal value, or its Base64 sentinel form
+ *
+ * @example
+ * ```ts
+ * encodeSentinel('search') // 'search'
+ * encodeSentinel('café') // '=?base64?Y2Fmw6k=?='
+ * ```
+ */
+export declare function encodeSentinel(value: string): string;
+
 /**
  * Concatenates an MCP tool-call result's text content blocks into one string.
  *
@@ -616,6 +883,157 @@ export declare const EMPTY_MCP_ARGUMENTS: Readonly<Record<string, unknown>>;
  */
 export declare function extractContentText(result: unknown): string;
 
+/**
+ * Reads every `x-mcp-header` annotation reachable from a schema node through `properties`.
+ *
+ * @remarks
+ * Reachability is the protocol's own rule: an annotation counts only where a chain of
+ * `properties` keys leads to it from the `inputSchema` root, so `path` is both the schema
+ * position and the position the call's `arguments` carry the value at. A property named
+ * `items` is reachable like any other, because the chain is read by key POSITION rather than
+ * by key name.
+ *
+ * `undefined` means the definition is invalid rather than empty: a reachable annotation whose
+ * value is not an {@link import('./validators.js').isFieldToken} token, one sitting on the
+ * schema ROOT (which is no property), one on a leaf whose declared type is not an
+ * {@link import('./validators.js').isMCPHeaderPrimitive} primitive, or a chain deeper than
+ * `DEFAULT_MCP_LIMITS.depth` — which is also what makes a self-referential schema terminate.
+ * A node that is not a record carries nothing and answers an empty list, because a leaf the
+ * walk cannot read is not a violation.
+ *
+ * @param schema - The schema node to read
+ * @param path - The `properties` keys already traversed; the root is called with `[]`
+ * @returns The annotations reachable from this node, or `undefined` when one is invalid
+ *
+ * @example
+ * ```ts
+ * extractHeaderAnnotations({ properties: { region: { type: 'string', 'x-mcp-header': 'Region' } } }, [])
+ * // → [{ name: 'Region', path: ['region'], primitive: 'string' }]
+ * ```
+ */
+export declare function extractHeaderAnnotations(schema: unknown, path: readonly string[]): readonly MCPHeaderParameter[] | undefined;
+
+/**
+ * Reads one named tool's advertised `inputSchema` out of a `tools/list` answer.
+ *
+ * @remarks
+ * The answer is read as foreign data end to end — a dispatched response, an error envelope,
+ * and a result whose `tools` member is absent or is not an array all read as "no schema"
+ * rather than as a fault. That is what lets the HTTP POST handler ask its own dispatcher
+ * which `Mcp-Param-*` names a `tools/call` may carry without narrowing anything first.
+ *
+ * @param response - The `tools/list` answer, normally a {@link JSONRPCResponse}
+ * @param name - The tool whose schema to read
+ * @returns The advertised `inputSchema`, or `undefined` when the answer carries none
+ *
+ * @example
+ * ```ts
+ * extractToolSchema(answer, 'search')?.['properties']
+ * ```
+ */
+export declare function extractToolSchema(response: unknown, name: string): Readonly<Record<string, unknown>> | undefined;
+
+/**
+ * Drives a REMOTE Streamable-HTTP MCP server over `fetch` — a CLIENT
+ * {@link MCPMessageTransportInterface} for the Model Context Protocol, the egress mirror of
+ * the server's `createMCPRoutes`.
+ *
+ * @remarks
+ * - **One class, both faces.** It touches `fetch`, `Response`, `AbortController`,
+ *   `AbortSignal`, and `WeakMap` alone, so it is host-independent and lives in core. Each
+ *   environment face publishes its own `createHTTPClientTransport` over it —
+ *   `@orkestrel/mcp/browser` and `@orkestrel/mcp/server` — and both factories return this
+ *   class, so a reply reaches a page and a Node process through the same decode.
+ * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
+ *   message to `options.url` with `content-type: application/json` and an
+ *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
+ *   answer with either framing) — plus any `options.headers` (for example, an `Authorization`
+ *   bearer). It then decodes the reply and emits each decoded {@link JSONRPCMessage} on
+ *   the `message` event the {@link import('@orkestrel/mcp').MCPClientInterface} subscribes
+ *   to.
+ * - **Both reply framings.** A `200` with an `application/json` body is parsed with
+ *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded with the
+ *   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} ({@link
+ *   readEventStream}) — the inverse of the server's `createStream` seam, so the wire
+ *   round-trips. A `202`
+ *   Accepted (a notification) carries no body and emits nothing.
+ * - **Session and protocol headers.** `start()` is a no-op (a
+ *   request/response transport opens no long-lived connection). The
+ *   `mcp-session-id` response header, when a STATEFUL server sends one (on
+ *   `initialize`), is captured into `session` and then ECHOED as the
+ *   `mcp-session-id` request header on every SUBSEQUENT request — so an
+ *   `MCPClient` passes a stateful server's session validation. The
+ *   initialize result's `protocolVersion` is likewise captured, but only
+ *   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` alone on
+ *   subsequent legacy requests. Modern requests instead derive protocol and method
+ *   headers from the message, plus the name header only for `tools/call` — carried in the
+ *   protocol's Base64 sentinel form whenever the tool name cannot ride as plain ASCII.
+ *   Before initialize returns, neither captured legacy header is sent.
+ *   `close()` clears the captured protocol so a reconnect's `initialize`
+ *   POST is headerless; the captured `session` persists across `close()`.
+ * - **`close()` releases what is in flight.** Every `fetch` this transport still has open is
+ *   ABORTED, which cancels the response body a `send` is reading — an SSE reply the server
+ *   never ends would otherwise outlive the transport, with nothing left able to reach it. The
+ *   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
+ *   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
+ * - **Total at the boundary, and a non-success reply REJECTS.** Every reply is narrowed
+ *   (`parseJSONRPCMessage`, the SSE decoder). A non-message success reply is dropped, never
+ *   asserted. A non-success reply that carries no valid JSON-RPC message rejects `send` with
+ *   an error naming its HTTP status and body shape — the peer answered, and answering the
+ *   caller's request with silence would leave it waiting out its own deadline for a failure
+ *   the transport already read. A valid JSON-RPC error body is emitted at any HTTP status,
+ *   because the protocol carries that outcome in band. A `fetch` or decode failure on a
+ *   success response surfaces on the `error` event rather than escaping `send`.
+ * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); fires
+ *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
+ *
+ * @example
+ * ```ts
+ * const transport = new HTTPClientTransport({ url: 'http://localhost:3000/mcp' })
+ * const client = new MCPClient({ transport })
+ * await client.connect()
+ * ```
+ */
+export declare class HTTPClientTransport implements MCPMessageTransportInterface {
+    #private;
+    constructor(options: HTTPClientTransportOptions);
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
+    get session(): string | undefined;
+    get duplex(): boolean;
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Options for `createHTTPClientTransport` — the remote MCP server's URL and any extra
+ * request headers.
+ *
+ * @remarks
+ * - `url` — the absolute URL of the remote server's Streamable-HTTP endpoint (the
+ *   `POST` target every JSON-RPC message is written to, for example,
+ *   `http://localhost:3000/mcp`). REQUIRED.
+ * - `headers` — extra request headers merged onto every `POST` (for example, an
+ *   `Authorization` bearer for a guarded server). The transport always sets
+ *   `content-type: application/json` and an `Accept` of both `application/json` and
+ *   `text/event-stream` (so the server may answer with either framing); a key supplied
+ *   here is merged on top.
+ * - `fetch` — the `fetch` implementation to issue each `POST` with; defaults to
+ *   `globalThis.fetch` bound to `globalThis`. Injectable for a test double or a non-global
+ *   `fetch`.
+ * - `timeout` — an optional per-request timeout in milliseconds; when set, each
+ *   `fetch` call composes that deadline with the transport's own close through
+ *   `AbortSignal.any([close, AbortSignal.timeout(timeout)])`, so whichever fires first
+ *   ends the request. Omit for no transport-level deadline; the close signal is passed
+ *   either way.
+ */
+export declare interface HTTPClientTransportOptions {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly fetch?: typeof fetch;
+    readonly timeout?: number;
+}
+
 /**
  * Infers the wire era for an MCP protocol revision.
  *
@@ -630,6 +1048,26 @@ export declare function extractContentText(result: unknown): string;
  */
 export declare function inferEra(version: string): MCPEra | undefined;
 
+/**
+ * Infers the wire era one invocation's own structure selects.
+ *
+ * @remarks
+ * The STRUCTURAL read, distinct from {@link inferEra}'s read of a revision string: era is fixed
+ * by the reserved modern metadata a request carries, so this answers for a message whose
+ * revision has not been read and cannot answer `undefined` — every invocation took one of the
+ * two published wire shapes. It is what an observation surface reports and what an ingress
+ * routes on, so both derive it here rather than each spelling the ternary out.
+ *
+ * @param invocation - The invocation whose structure selects the era
+ * @returns `'modern'` when the invocation carries the modern request shape, `'legacy'` otherwise
+ *
+ * @example
+ * ```ts
+ * inferRequestEra({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: meta } })
+ * ```
+ */
+export declare function inferRequestEra(invocation: JSONRPCInvocation): MCPEra;
+
 /**
  * Infers the protocol version an outbound message announces itself with — the ONE
  * projection every HTTP client transport stamps `mcp-protocol-version` from.
@@ -677,7 +1115,7 @@ export declare function inferVersion(offered: readonly string[]): MCPModernVersi
  * scheme allowlist. Component scanning is bounded by the input length.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is an RFC 3986 URI rather than a relative reference
+ * @returns True if the value is an RFC 3986 URI rather than a relative reference; false otherwise
  */
 export declare function isAbsoluteURI(value: unknown): value is string;
 
@@ -691,7 +1129,7 @@ export declare function isAbsoluteURI(value: unknown): value is string;
  *
  * @param value - The unknown value to inspect
  * @param limits - Serialized byte, optional key, and nesting-depth bounds
- * @returns `true` only for safe JSON satisfying every bound
+ * @returns True if `value` is safe JSON satisfying every bound; false otherwise
  *
  * @example
  * ```ts
@@ -705,7 +1143,7 @@ export declare function isBoundedJSON<T>(value: T, limits: MCPJSONLimitOptions):
  *
  * @param value - The unknown value to inspect
  * @param bytes - The maximum accepted encoded bytes
- * @returns `true` only for a string whose UTF-8 representation fits the bound
+ * @returns True if `value` is a string whose UTF-8 representation fits the bound; false otherwise
  *
  * @example
  * ```ts
@@ -742,7 +1180,7 @@ export declare function isBoundedString(value: unknown, bytes: number): value is
  *
  * @param value - The accepted response content to check
  * @param schema - The exact {@link MCPElicitSchema} that was issued with the elicitation
- * @returns `true` when every declared and undeclared value is legal under `schema`
+ * @returns True if every declared and undeclared value is legal under `schema`; false otherwise
  *
  * @example
  * ```ts
@@ -759,29 +1197,31 @@ export declare function isBoundedString(value: unknown, bytes: number): value is
 export declare function isElicitContent(value: unknown, schema: unknown): value is Readonly<Record<string, MCPElicitValue>>;
 
 /**
- * Determines whether a client capability record declares form-mode elicitation.
+ * Determines whether a value is one RFC 9110 field token.
  *
  * @remarks
- * The protocol's empty `elicitation` object is the implicit form-only declaration.
- * A non-empty declaration must carry a record-valued `form` member; URL-only support
- * does not authorize a form request. Total over hostile input.
+ * A token is one or more `tchar`: the ASCII letters, the digits, and
+ * ``!#$%&'*+-.^_`|~``. That set already excludes the empty string, whitespace, a colon, a
+ * control character, and every non-ASCII code point, so it is the whole constraint an
+ * `x-mcp-header` annotation's value must satisfy — the value is appended verbatim to
+ * {@link MCP_PARAM_PREFIX} and must survive as an HTTP field name.
  *
- * @param value - The client capability record to inspect
- * @returns `true` when form-mode elicitation is declared
+ * @param value - The unknown value to inspect
+ * @returns True if the value is a non-empty RFC 9110 token; false otherwise
  *
  * @example
  * ```ts
- * isFormElicitationSupported({ elicitation: {} }) // true — implicit form mode
- * isFormElicitationSupported({ elicitation: { url: {} } }) // false
+ * isFieldToken('Region') // true
+ * isFieldToken('My Region') // false
  * ```
  */
-export declare function isFormElicitationSupported(value: unknown): boolean;
+export declare function isFieldToken(value: unknown): value is string;
 
 /**
  * Determines whether a parsed value is an MCP `initialize` invocation.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid `initialize` request or notification
+ * @returns True if `value` is a valid `initialize` request or notification; false otherwise
  *
  * @example
  * ```ts
@@ -813,7 +1253,7 @@ export declare function isJSONObject(value: unknown): value is Readonly<Record<s
  * itself the hostile step, and it is bounded here rather than allowed to escape. Total.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` carries an integer `code` and a string `message`
+ * @returns True if `value` carries an integer `code` and a string `message`; false otherwise
  *
  * @example
  * ```ts
@@ -834,7 +1274,7 @@ export declare function isJSONRPCError(value: unknown): value is JSONRPCError;
  * `result`. `error` carries an integer `code` and a string `message`. Total.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid JSON-RPC error response
+ * @returns True if `value` is a valid JSON-RPC error response; false otherwise
  *
  * @example
  * ```ts
@@ -856,7 +1296,7 @@ export declare function isJSONRPCErrorResponse(value: unknown): value is JSONRPC
  * no minimum length. Total: any other input returns `false`.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a string or a finite integer
+ * @returns True if `value` is a string or a finite integer; false otherwise
  *
  * @example
  * ```ts
@@ -878,7 +1318,7 @@ export declare function isJSONRPCId(value: unknown): value is JSONRPCId;
  * mutually exclusive, so a positive answer names exactly one arm. Total.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid JSON-RPC request or notification
+ * @returns True if `value` is a valid JSON-RPC request or notification; false otherwise
  */
 export declare function isJSONRPCInvocation(value: unknown): value is JSONRPCInvocation;
 
@@ -890,7 +1330,7 @@ export declare function isJSONRPCInvocation(value: unknown): value is JSONRPCInv
  * The union of {@link isJSONRPCInvocation} and {@link isJSONRPCResponse}. Total.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid JSON-RPC message
+ * @returns True if `value` is a valid JSON-RPC message; false otherwise
  */
 export declare function isJSONRPCMessage(value: unknown): value is JSONRPCMessage;
 
@@ -903,7 +1343,7 @@ export declare function isJSONRPCMessage(value: unknown): value is JSONRPCMessag
  * be a record. Total: any other input returns `false`.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid JSON-RPC notification
+ * @returns True if `value` is a valid JSON-RPC notification; false otherwise
  *
  * @example
  * ```ts
@@ -925,7 +1365,7 @@ export declare function isJSONRPCNotification(value: unknown): value is JSONRPCN
  * be a record. Total: any other input returns `false`.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid JSON-RPC request
+ * @returns True if `value` is a valid JSON-RPC request; false otherwise
  *
  * @example
  * ```ts
@@ -943,7 +1383,7 @@ export declare function isJSONRPCRequest(value: unknown): value is JSONRPCReques
  * The union of the mutually exclusive arms. Total.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid JSON-RPC response
+ * @returns True if `value` is a valid JSON-RPC response; false otherwise
  */
 export declare function isJSONRPCResponse(value: unknown): value is JSONRPCResponse;
 
@@ -960,7 +1400,7 @@ export declare function isJSONRPCResponse(value: unknown): value is JSONRPCRespo
  * Total.
  *
  * @param value - The already-parsed value to test
- * @returns `true` when `value` is a valid JSON-RPC result response
+ * @returns True if `value` is a valid JSON-RPC result response; false otherwise
  *
  * @example
  * ```ts
@@ -974,7 +1414,7 @@ export declare function isJSONRPCResultResponse(value: unknown): value is JSONRP
  * Determines whether a value carries valid dated-schema MCP content annotations.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is valid MCP annotations
+ * @returns True if the value is valid MCP annotations; false otherwise
  */
 export declare function isMCPAnnotations(value: unknown): value is MCPAnnotations;
 
@@ -982,7 +1422,7 @@ export declare function isMCPAnnotations(value: unknown): value is MCPAnnotation
  * Determines whether a value is embedded blob MCP resource contents.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is embedded blob resource contents
+ * @returns True if the value is embedded blob resource contents; false otherwise
  */
 export declare function isMCPBlobResource(value: unknown): value is MCPBlobResource;
 
@@ -990,7 +1430,7 @@ export declare function isMCPBlobResource(value: unknown): value is MCPBlobResou
  * Determines whether a value is a complete modern MCP tool result.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a complete MCP call result
+ * @returns True if the value is a complete MCP call result; false otherwise
  */
 export declare function isMCPCallResult(value: unknown): value is MCPCallResult;
 
@@ -1001,7 +1441,7 @@ export declare function isMCPClientCapabilities(value: unknown): value is MCPCli
  * Determines whether a value is one host-produced completion candidate set.
  *
  * @param value - The unknown value to inspect
- * @returns Whether its candidates and optional result facts are valid
+ * @returns True if its candidates and optional result facts are valid; false otherwise
  */
 export declare function isMCPCompletion(value: unknown): value is MCPCompletion;
 
@@ -1009,7 +1449,7 @@ export declare function isMCPCompletion(value: unknown): value is MCPCompletion;
  * Determines whether a value is one `completion/complete` parameter object.
  *
  * @param value - The unknown value to inspect
- * @returns Whether its reference, fragment, and optional string context are valid
+ * @returns True if its reference, fragment, and optional string context are valid; false otherwise
  */
 export declare function isMCPCompletionParams(value: unknown): value is MCPCompletionParams;
 
@@ -1017,7 +1457,7 @@ export declare function isMCPCompletionParams(value: unknown): value is MCPCompl
  * Determines whether a value is a prompt or resource-template completion reference.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the discriminated reference is valid
+ * @returns True if the discriminated reference is valid; false otherwise
  */
 export declare function isMCPCompletionReference(value: unknown): value is MCPCompletionReference;
 
@@ -1025,7 +1465,7 @@ export declare function isMCPCompletionReference(value: unknown): value is MCPCo
  * Determines whether a value is one complete, capped `completion/complete` result.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the result is complete and carries at most 100 candidates
+ * @returns True if the result is complete and carries at most 100 candidates; false otherwise
  */
 export declare function isMCPCompletionResult(value: unknown): value is MCPCompletionResult;
 
@@ -1033,7 +1473,7 @@ export declare function isMCPCompletionResult(value: unknown): value is MCPCompl
  * Determines whether a value is one exact dated-schema MCP tool content block.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is valid MCP content
+ * @returns True if the value is valid MCP content; false otherwise
  */
 export declare function isMCPContent(value: unknown): value is MCPContent;
 
@@ -1041,7 +1481,7 @@ export declare function isMCPContent(value: unknown): value is MCPContent;
  * Determines whether a value is one restricted primitive form-elicitation schema.
  *
  * @param value - The unknown value to inspect
- * @returns `true` for a supported boolean, numeric, string, or string-array schema
+ * @returns True if `value` is a supported boolean, numeric, string, or string-array schema; false otherwise
  *
  * @example
  * ```ts
@@ -1055,7 +1495,7 @@ export declare function isMCPElicitFieldSchema(value: unknown): value is MCPElic
  * Determines whether a value is a form-mode elicitation parameter object.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when `value` has the restricted form elicitation shape
+ * @returns True if `value` has the restricted form elicitation shape; false otherwise
  *
  * @example
  * ```ts
@@ -1071,7 +1511,7 @@ export declare function isMCPElicitForm(value: unknown): value is MCPElicitForm;
  * Determines whether a value is an embedded `elicitation/create` request.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when `value` is a form- or URL-mode elicitation request
+ * @returns True if `value` is a form- or URL-mode elicitation request; false otherwise
  *
  * @example
  * ```ts
@@ -1087,7 +1527,7 @@ export declare function isMCPElicitRequest(value: unknown): value is MCPElicitRe
  * Determines whether a value is one elicitation response.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when action/content have the protocol shape
+ * @returns True if action/content have the protocol shape; false otherwise
  *
  * @example
  * ```ts
@@ -1107,7 +1547,7 @@ export declare function isMCPElicitResult(value: unknown): value is MCPElicitRes
  * an unrecognized top-level annotation is data rather than a rejection.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when `value` is a restricted object schema of supported field schemas
+ * @returns True if `value` is a restricted object schema of supported field schemas; false otherwise
  *
  * @example
  * ```ts
@@ -1121,7 +1561,7 @@ export declare function isMCPElicitSchema(value: unknown): value is MCPElicitSch
  * Determines whether a value is a URL-mode elicitation parameter object.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when `value` has the URL elicitation shape
+ * @returns True if `value` has the URL elicitation shape; false otherwise
  *
  * @example
  * ```ts
@@ -1134,7 +1574,7 @@ export declare function isMCPElicitURL(value: unknown): value is MCPElicitURL;
  * Determines whether an unknown value is an {@link MCPError}.
  *
  * @param value - The unknown value to inspect
- * @returns `true` only when the value is an `MCPError`
+ * @returns True if the value is an `MCPError`; false otherwise
  *
  * @example
  * ```ts
@@ -1144,11 +1584,30 @@ export declare function isMCPElicitURL(value: unknown): value is MCPElicitURL;
  */
 export declare function isMCPError(value: unknown): value is MCPError;
 
+/**
+ * Determines whether a value is a JSON Schema type an `x-mcp-header` annotation may sit on.
+ *
+ * @remarks
+ * `number` is refused deliberately: a JSON number has no interoperable decimal text form, so
+ * a header carrying one could not be compared with the body byte for byte. `integer` renders
+ * exactly, and the server compares it numerically.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if the value is one of `'string'`, `'integer'`, or `'boolean'`; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPHeaderPrimitive('integer') // true
+ * isMCPHeaderPrimitive('number') // false
+ * ```
+ */
+export declare function isMCPHeaderPrimitive(value: unknown): value is MCPHeaderPrimitive;
+
 /**
  * Determines whether a value is one exact dated-schema MCP icon.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a valid MCP icon
+ * @returns True if the value is a valid MCP icon; false otherwise
  */
 export declare function isMCPIcon(value: unknown): value is MCPIcon;
 
@@ -1159,7 +1618,7 @@ export declare function isMCPIdentity(value: unknown): value is MCPIdentity;
  * Determines whether a value is one legal embedded multi-round-trip request.
  *
  * @param value - The unknown value to inspect
- * @returns `true` for elicitation, deprecated sampling, or deprecated roots requests
+ * @returns True if `value` is an embedded elicitation, sampling, or roots request; false otherwise
  *
  * @example
  * ```ts
@@ -1169,10 +1628,10 @@ export declare function isMCPIdentity(value: unknown): value is MCPIdentity;
 export declare function isMCPInputRequest(value: unknown): value is MCPInputRequest;
 
 /**
- * Determines whether a value is a server-keyed map of embedded input requests.
+ * Determines whether a value is a consumer-keyed map of embedded input requests.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when every own value is a legal {@link MCPInputRequest}
+ * @returns True if every own value is a legal {@link MCPInputRequest}; false otherwise
  *
  * @example
  * ```ts
@@ -1181,6 +1640,30 @@ export declare function isMCPInputRequest(value: unknown): value is MCPInputRequ
  */
 export declare function isMCPInputRequestMap(value: unknown): value is MCPInputRequestMap;
 
+/**
+ * Determines whether a response answers the exact embedded request that was issued.
+ *
+ * @remarks
+ * A response carries no `method` of its own, so the ISSUED request selects which arm applies
+ * — the same way {@link isElicitContent} takes the issued schema rather than trusting the
+ * content to describe itself. A form elicitation is checked twice: once for the response
+ * shape and once, on `accept`, for the content against the schema that round issued. A
+ * URL-mode elicitation issues no schema, so only the shape is checked. A request this
+ * package cannot recognize admits NOTHING, because an unrecognized question has no correct
+ * answer. Total over hostile responses and hostile requests alike.
+ *
+ * @param value - The client's answer to check
+ * @param request - The exact {@link MCPInputRequest} that was issued under the same key
+ * @returns True if the answer is legal for that request; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPInputResponse({ roots: [] }, { method: 'roots/list' }) // true
+ * isMCPInputResponse({ roots: [] }, { method: 'sampling/createMessage', params: {} }) // false
+ * ```
+ */
+export declare function isMCPInputResponse(value: unknown, request: unknown): value is MCPInputResponse;
+
 /**
  * Determines whether a value is an MCP input-required result.
  *
@@ -1189,7 +1672,7 @@ export declare function isMCPInputRequestMap(value: unknown): value is MCPInputR
  * both must be present and valid. Total over hostile input.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when `value` is a valid input-required result
+ * @returns True if `value` is a valid input-required result; false otherwise
  *
  * @example
  * ```ts
@@ -1208,7 +1691,7 @@ export declare function isMCPInputResult(value: unknown): value is MCPInputResul
  * hostile input.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a legacy result
+ * @returns True if the value is a legacy result; false otherwise
  *
  * @example
  * ```ts
@@ -1222,7 +1705,7 @@ export declare function isMCPLegacyResult(value: unknown): value is MCPLegacyRes
  * Determines whether a value is a revision accepted by the optional legacy decorator.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when the value is one of {@link SUPPORTED_LEGACY_PROTOCOL_VERSIONS}
+ * @returns True if the value is one of {@link SUPPORTED_LEGACY_PROTOCOL_VERSIONS}; false otherwise
  */
 export declare function isMCPLegacyVersion(value: unknown): value is MCPLegacyVersion;
 
@@ -1239,7 +1722,7 @@ export declare function isMCPMetaObject(value: unknown): value is MCPMetaObject;
  * Determines whether a value is a modern protocol revision accepted by a bare server.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when the value is one of {@link SUPPORTED_MODERN_PROTOCOL_VERSIONS}
+ * @returns True if the value is one of {@link SUPPORTED_MODERN_PROTOCOL_VERSIONS}; false otherwise
  */
 export declare function isMCPModernVersion(value: unknown): value is MCPModernVersion;
 
@@ -1253,7 +1736,7 @@ export declare function isMCPModernVersion(value: unknown): value is MCPModernVe
  * {@link JSONRPCId}, because a stamp naming nothing addressable is worse than no stamp.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when the value is exact metadata whose subscription stamp, if present, is valid
+ * @returns True if the value is exact metadata whose subscription stamp, if present, is valid; false otherwise
  *
  * @example
  * ```ts
@@ -1268,7 +1751,7 @@ export declare function isMCPNotificationMetaObject(value: unknown): value is MC
  * Determines whether a value carries the shared optional pagination cursor.
  *
  * @param value - The unknown value to inspect
- * @returns Whether a present `cursor` is a string
+ * @returns True if a present `cursor` is a string; false otherwise
  */
 export declare function isMCPPaginationParams(value: unknown): value is MCPPaginationParams;
 
@@ -1276,7 +1759,7 @@ export declare function isMCPPaginationParams(value: unknown): value is MCPPagin
  * Determines whether a value is one exact finite MCP progress payload.
  *
  * @param value - The unknown value to inspect
- * @returns Whether required progress and optional total/message fields match the dated schema
+ * @returns True if required progress and optional total/message fields match the dated schema; false otherwise
  */
 export declare function isMCPProgress(value: unknown): value is MCPProgress;
 
@@ -1284,7 +1767,7 @@ export declare function isMCPProgress(value: unknown): value is MCPProgress;
  * Determines whether a value is one `prompts/list` descriptor.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the prompt descriptor is valid
+ * @returns True if the prompt descriptor is valid; false otherwise
  */
 export declare function isMCPPrompt(value: unknown): value is MCPPrompt;
 
@@ -1292,7 +1775,7 @@ export declare function isMCPPrompt(value: unknown): value is MCPPrompt;
  * Determines whether a value is one prompt argument descriptor.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the prompt argument descriptor is valid
+ * @returns True if the prompt argument descriptor is valid; false otherwise
  */
 export declare function isMCPPromptArgument(value: unknown): value is MCPPromptArgument;
 
@@ -1300,7 +1783,7 @@ export declare function isMCPPromptArgument(value: unknown): value is MCPPromptA
  * Determines whether a value is one complete `prompts/get` result.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the prompt result and all messages are valid
+ * @returns True if the prompt result and all messages are valid; false otherwise
  */
 export declare function isMCPPromptGetResult(value: unknown): value is MCPPromptGetResult;
 
@@ -1308,7 +1791,7 @@ export declare function isMCPPromptGetResult(value: unknown): value is MCPPrompt
  * Determines whether a value is one prompt message with existing rich content.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the role and content are valid
+ * @returns True if the role and content are valid; false otherwise
  */
 export declare function isMCPPromptMessage(value: unknown): value is MCPPromptMessage;
 
@@ -1316,7 +1799,7 @@ export declare function isMCPPromptMessage(value: unknown): value is MCPPromptMe
  * Determines whether a value is one consumer-owned prompt page.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the prompts and optional following cursor are valid
+ * @returns True if the prompts and optional following cursor are valid; false otherwise
  */
 export declare function isMCPPromptPage(value: unknown): value is MCPPromptPage;
 
@@ -1324,7 +1807,7 @@ export declare function isMCPPromptPage(value: unknown): value is MCPPromptPage;
  * Determines whether a value is one `resources/list` descriptor.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a valid resource descriptor
+ * @returns True if the value is a valid resource descriptor; false otherwise
  */
 export declare function isMCPResource(value: unknown): value is MCPResource;
 
@@ -1332,7 +1815,7 @@ export declare function isMCPResource(value: unknown): value is MCPResource;
  * Determines whether a value is structurally discriminated resource contents.
  *
  * @param value - The unknown value to inspect
- * @returns Whether exactly one of `text` and `blob` is present and valid
+ * @returns True if exactly one of `text` and `blob` is present and valid; false otherwise
  */
 export declare function isMCPResourceContents(value: unknown): value is MCPResourceContents;
 
@@ -1340,7 +1823,7 @@ export declare function isMCPResourceContents(value: unknown): value is MCPResou
  * Determines whether a value is one consumer-owned resource page.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the resources and optional following cursor are valid
+ * @returns True if the resources and optional following cursor are valid; false otherwise
  */
 export declare function isMCPResourcePage(value: unknown): value is MCPResourcePage;
 
@@ -1352,7 +1835,7 @@ export declare function isMCPResourcePage(value: unknown): value is MCPResourceP
  * level belong to the consumer-supplied resource manager; this package projects the string.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a valid resource-template descriptor
+ * @returns True if the value is a valid resource-template descriptor; false otherwise
  */
 export declare function isMCPResourceTemplate(value: unknown): value is MCPResourceTemplate;
 
@@ -1360,7 +1843,7 @@ export declare function isMCPResourceTemplate(value: unknown): value is MCPResou
  * Determines whether a value is one consumer-owned resource-template page.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the templates and optional following cursor are valid
+ * @returns True if the templates and optional following cursor are valid; false otherwise
  */
 export declare function isMCPResourceTemplatePage(value: unknown): value is MCPResourceTemplatePage;
 
@@ -1377,7 +1860,7 @@ export declare function isMCPResourceTemplatePage(value: unknown): value is MCPR
  * input.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a modern result
+ * @returns True if the value is a modern result; false otherwise
  *
  * @example
  * ```ts
@@ -1391,6 +1874,95 @@ export declare function isMCPResult(value: unknown): value is MCPResult;
 /** Determines whether a value is exact result metadata with a valid reserved server identity. */
 export declare function isMCPResultMetaObject(value: unknown): value is MCPResultMetaObject;
 
+/**
+ * Determines whether a value is one filesystem root a client exposes.
+ *
+ * @remarks
+ * The dated schema declares `uri` with `format: uri`, so this applies the same RFC 3986
+ * check {@link isAbsoluteURI} gives every other `format: uri` field the package validates,
+ * including a URL-mode elicitation's `url`. Total over hostile input.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if `value` carries an absolute `uri` and an optional string `name`; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPRoot({ uri: 'file:///workspace', name: 'workspace' }) // true
+ * isMCPRoot({ uri: 'workspace' }) // false — the schema declares `format: uri`
+ * ```
+ */
+export declare function isMCPRoot(value: unknown): value is MCPRoot;
+
+/**
+ * Determines whether a value is one client answer to an embedded `roots/list` request.
+ *
+ * @remarks
+ * The dated schema requires the `roots` array, and each root is checked by
+ * {@link isMCPRoot}. Total over hostile input.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if `value` carries an array of valid roots; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPRootResult({ roots: [{ uri: 'file:///workspace' }] }) // true
+ * isMCPRootResult({ roots: {} }) // false — the schema requires an array
+ * ```
+ */
+export declare function isMCPRootResult(value: unknown): value is MCPRootResult;
+
+/**
+ * Determines whether a value is one block a sampling completion may carry.
+ *
+ * @remarks
+ * The schema's `SamplingMessageContentBlock`: the text, image, and audio blocks
+ * {@link isMCPContent} also admits, plus `tool_use` and `tool_result`. The resource arms of
+ * {@link isMCPContent} are refused, because the schema leaves them out of a sampling
+ * completion. A `tool_result` carries ordinary {@link isMCPContent} blocks and an open
+ * `structuredContent`, which the schema constrains to no shape at all. Total over hostile
+ * input.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if `value` is one legal sampling content block; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPSampleContent({ type: 'text', text: 'Paris' }) // true
+ * isMCPSampleContent({ type: 'tool_use', id: 'c1', name: 'lookup', input: {} }) // true
+ * isMCPSampleContent({ type: 'resource_link', name: 'doc', uri: 'file:///doc' }) // false
+ * ```
+ */
+export declare function isMCPSampleContent(value: unknown): value is MCPSampleContent;
+
+/**
+ * Determines whether a value is one client answer to an embedded sampling request.
+ *
+ * @remarks
+ * The schema's `CreateMessageResult` types `content` as an `anyOf` over one
+ * {@link isMCPSampleContent} block or an ARRAY of them, so both are admitted here: a
+ * tool-using model answers with `tool_use` and `tool_result` blocks, and a model answering in
+ * several parts answers with the array. `stopReason` stays an open string because the schema
+ * names four values and permits any other a provider reports. Total over hostile input.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if `value` has the sampling-completion shape; false otherwise
+ *
+ * @example
+ * ```ts
+ * isMCPSampleResult({
+ * 	role: 'assistant',
+ * 	content: { type: 'text', text: 'Paris' },
+ * 	model: 'test-model',
+ * }) // true
+ * isMCPSampleResult({
+ * 	role: 'assistant',
+ * 	content: [{ type: 'text', text: 'Paris' }],
+ * 	model: 'test-model',
+ * }) // true
+ * ```
+ */
+export declare function isMCPSampleResult(value: unknown): value is MCPSampleResult;
+
 /** Determines whether a value is one exact open dated server-capability declaration. */
 export declare function isMCPServerCapabilities(value: unknown): value is MCPServerCapabilities;
 
@@ -1398,7 +1970,7 @@ export declare function isMCPServerCapabilities(value: unknown): value is MCPSer
  * Determines whether a value is a string-valued MCP argument record.
  *
  * @param value - The unknown value to inspect
- * @returns Whether every own argument value is a string
+ * @returns True if every own argument value is a string; false otherwise
  */
 export declare function isMCPStringArguments(value: unknown): value is Readonly<Record<string, string>>;
 
@@ -1416,7 +1988,7 @@ export declare function isMCPStringArguments(value: unknown): value is Readonly<
  * the caller asked for.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when every recognized filter field has its protocol shape
+ * @returns True if every recognized filter field has its protocol shape; false otherwise
  */
 export declare function isMCPSubscriptionFilter(value: unknown): value is MCPSubscriptionFilter;
 
@@ -1424,7 +1996,7 @@ export declare function isMCPSubscriptionFilter(value: unknown): value is MCPSub
  * Determines whether a value is a graceful `subscriptions/listen` result.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when the result is complete and carries a valid subscription id
+ * @returns True if the result is complete and carries a valid subscription id; false otherwise
  */
 export declare function isMCPSubscriptionResult(value: unknown): value is MCPSubscriptionResult;
 
@@ -1448,7 +2020,7 @@ export declare function isMCPSubscriptionResult(value: unknown): value is MCPSub
  * What is checked is what this package publishes as the contract.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a well-formed {@link MCPTaskDetail}
+ * @returns True if the value is a well-formed {@link MCPTaskDetail}; false otherwise
  *
  * @example
  * ```ts
@@ -1475,7 +2047,7 @@ export declare function isMCPTaskDetail(value: unknown): value is MCPTaskDetail;
  * peer stamps there is the peer's to write.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a well-formed {@link MCPTaskDetailResult}
+ * @returns True if the value is a well-formed {@link MCPTaskDetailResult}; false otherwise
  *
  * @example
  * ```ts
@@ -1502,7 +2074,7 @@ export declare function isMCPTaskDetailResult(value: unknown): value is MCPTaskD
  * to it, so a guard that demanded the stamp would refuse every frame a producer emits.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a well-formed `notifications/tasks` notification
+ * @returns True if the value is a well-formed `notifications/tasks` notification; false otherwise
  *
  * @example
  * ```ts
@@ -1513,10 +2085,7 @@ export declare function isMCPTaskDetailResult(value: unknown): value is MCPTaskD
  *   params: { taskId: 'a' } }) // false — the params owe a whole snapshot
  * ```
  */
-export declare function isMCPTaskNotification(value: unknown): value is JSONRPCNotification & {
-    readonly method: 'notifications/tasks';
-    readonly params: MCPTaskNotificationParams;
-};
+export declare function isMCPTaskNotification(value: unknown): value is MCPTaskNotification;
 
 /**
  * Determines whether a value is a modern MCP task-creation result.
@@ -1530,7 +2099,7 @@ export declare function isMCPTaskNotification(value: unknown): value is JSONRPCN
  * INTEGER milliseconds because the schema formats them `int`.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is a well-formed `resultType: 'task'` result
+ * @returns True if the value is a well-formed `resultType: 'task'` result; false otherwise
  *
  * @example
  * ```ts
@@ -1544,7 +2113,7 @@ export declare function isMCPTaskResult(value: unknown): value is MCPTaskResult;
  * Determines whether a value is one of the extension's task lifecycle states.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is an {@link MCPTaskStatus}
+ * @returns True if the value is an {@link MCPTaskStatus}; false otherwise
  *
  * @example
  * ```ts
@@ -1558,7 +2127,7 @@ export declare function isMCPTaskStatus(value: unknown): value is MCPTaskStatus;
  * Determines whether a value is embedded textual MCP resource contents.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is embedded textual resource contents
+ * @returns True if the value is embedded textual resource contents; false otherwise
  */
 export declare function isMCPTextResource(value: unknown): value is MCPTextResource;
 
@@ -1566,7 +2135,7 @@ export declare function isMCPTextResource(value: unknown): value is MCPTextResou
  * Determines whether a value is a supported {@link MCPVersion}.
  *
  * @param value - The unknown value to inspect
- * @returns `true` when the value is one of {@link SUPPORTED_MCP_VERSIONS}
+ * @returns True if the value is one of {@link SUPPORTED_MCP_VERSIONS}; false otherwise
  */
 export declare function isMCPVersion(value: unknown): value is MCPVersion;
 
@@ -1581,7 +2150,7 @@ export declare function isMCPVersion(value: unknown): value is MCPVersion;
  * legacy dispatch. Total over hostile and malformed input.
  *
  * @param value - The already-parsed value to inspect
- * @returns `true` when the value is an invocation carrying the reserved version key
+ * @returns True if the value is an invocation carrying the reserved version key; false otherwise
  */
 export declare function isModernRequest(value: unknown): value is JSONRPCInvocation;
 
@@ -1600,7 +2169,7 @@ export declare function isModernRequest(value: unknown): value is JSONRPCInvocat
  * refuse. It is a SYNTAX guard: no time zone, locale, calendar era, or leap second applies.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is an RFC 3339 `full-date` for a day that exists
+ * @returns True if the value is an RFC 3339 `full-date` for a day that exists; false otherwise
  *
  * @example
  * ```ts
@@ -1624,7 +2193,7 @@ export declare function isRFC3339Date(value: unknown): value is string;
  * second.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is an RFC 3339 `date-time` for a day that exists
+ * @returns True if the value is an RFC 3339 `date-time` for a day that exists; false otherwise
  *
  * @example
  * ```ts
@@ -1639,40 +2208,13 @@ export declare function isRFC3339DateTime(value: unknown): value is string;
  * Determines whether a value is standard padded base64 as required by JSON Schema `byte` format.
  *
  * @param value - The unknown value to inspect
- * @returns Whether the value is an empty or completely padded standard base64 encoding
+ * @returns True if the value is an empty or completely padded standard base64 encoding; false otherwise
  */
 export declare function isStandardBase64(value: unknown): value is string;
 
 /**
- * Determines whether a client capability record declares the stable Tasks extension.
- *
- * @remarks
- * The declaration lives at `extensions['io.modelcontextprotocol/tasks']` and the schema
- * types its value EXACTLY EMPTY — `Record<string, never>`, an object with no additional
- * properties. So the key's presence is the whole declaration, and the value carries the
- * whole of the check: a `true` or a string there is a client speaking a different protocol
- * rather than a shorthand, and a member inside the object is a client declaring an option
- * this extension does not define. Both are refused, because a server that accepted either
- * would be reading a shape no peer can produce from the snapshot's own schema.
- *
- * A client declares this PER REQUEST. Nothing here consults a session, because the modern
- * revision is stateless and a capability declared once at connect time says nothing about
- * the request in hand. Total over hostile input.
- *
- * @param value - The client capability record to inspect
- * @returns `true` when the tasks extension is declared as the schema's empty object
- *
- * @example
- * ```ts
- * isTaskSupported({ extensions: { 'io.modelcontextprotocol/tasks': {} } }) // true
- * isTaskSupported({ extensions: {} }) // false — the key is the declaration
- * isTaskSupported({ extensions: { 'io.modelcontextprotocol/tasks': { on: true } } }) // false
- * ```
- */
-export declare function isTaskSupported(value: unknown): boolean;
-
-/**
- * JSON-RPC 2.0 reserved error: the server failed while handling an otherwise valid request.
+ * Names the JSON-RPC 2.0 reserved error for a server that failed while handling an otherwise
+ * valid request.
  *
  * @remarks
  * The code every MODERN internal fault answers with — a provider, handler, continuation,
@@ -1682,20 +2224,20 @@ export declare function isTaskSupported(value: unknown): boolean;
  */
 export declare const JSONRPC_INTERNAL_ERROR = -32603;
 
-/** JSON-RPC 2.0 reserved error: the method's parameters were invalid. */
+/** Names the JSON-RPC 2.0 reserved error for a method's invalid parameters. */
 export declare const JSONRPC_INVALID_PARAMS = -32602;
 
-/** JSON-RPC 2.0 reserved error: the payload was not a valid Request object. */
+/** Names the JSON-RPC 2.0 reserved error for a payload that was not a valid Request object. */
 export declare const JSONRPC_INVALID_REQUEST = -32600;
 
-/** JSON-RPC 2.0 reserved error: the requested method does not exist. */
+/** Names the JSON-RPC 2.0 reserved error for a requested method that does not exist. */
 export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
 
-/** JSON-RPC 2.0 reserved error: invalid JSON was received (the message did not parse). */
+/** Names the JSON-RPC 2.0 reserved error for invalid JSON received (the message did not parse). */
 export declare const JSONRPC_PARSE_ERROR = -32700;
 
 /**
- * JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range).
+ * Names the JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range).
  *
  * @remarks
  * Retained for the LEGACY branch alone. A modern fault answers
@@ -1705,7 +2247,7 @@ export declare const JSONRPC_PARSE_ERROR = -32700;
 export declare const JSONRPC_SERVER_ERROR = -32000;
 
 /**
- * A JSON-RPC 2.0 error object — the `error` member of a
+ * Represents a JSON-RPC 2.0 error object — the `error` member of a
  * {@link JSONRPCErrorResponse}.
  *
  * @remarks
@@ -1720,8 +2262,8 @@ export declare interface JSONRPCError {
 }
 
 /**
- * The failure arm of a JSON-RPC 2.0 response — the request's `id` echoed with the
- * {@link JSONRPCError} that ended it.
+ * Represents the failure arm of a JSON-RPC 2.0 response — the request's `id` echoed with
+ * the {@link JSONRPCError} that ended it.
  *
  * @remarks
  * `id` is OMITTED, never `null`, when the request could not be parsed or its id
@@ -1730,18 +2272,18 @@ export declare interface JSONRPCError {
  */
 export declare interface JSONRPCErrorResponse {
     readonly jsonrpc: '2.0';
-    /** The failed request's id; ABSENT when no id could be read. */
+    /** Holds the failed request's id; ABSENT when no id could be read. */
     readonly id?: JSONRPCId;
     readonly error: JSONRPCError;
-    /** Forbidden — an answer carries a result or an error, never both. */
+    /** Forbids this member; an answer carries a result or an error, never both. */
     readonly result?: never;
 }
 
-/** A JSON-RPC 2.0 correlation id — the value a request and its response share. */
+/** Represents a JSON-RPC 2.0 correlation id — the value a request and its response share. */
 export declare type JSONRPCId = string | number;
 
 /**
- * One inbound JSON-RPC call — the common dispatch input.
+ * Represents one inbound JSON-RPC call — the common dispatch input.
  *
  * @remarks
  * Narrow the arms apart on the id: `invocation.id === undefined` is the notification
@@ -1750,7 +2292,7 @@ export declare type JSONRPCId = string | number;
 export declare type JSONRPCInvocation = JSONRPCRequest | JSONRPCNotification;
 
 /**
- * A JSON-RPC 2.0 message on the wire — a {@link JSONRPCInvocation} or a
+ * Represents a JSON-RPC 2.0 message on the wire — a {@link JSONRPCInvocation} or a
  * {@link JSONRPCResponse}.
  *
  * @remarks
@@ -1760,8 +2302,8 @@ export declare type JSONRPCInvocation = JSONRPCRequest | JSONRPCNotification;
 export declare type JSONRPCMessage = JSONRPCInvocation | JSONRPCResponse;
 
 /**
- * A JSON-RPC 2.0 notification — a fire-and-forget `method` call that is answered by
- * nothing (for example, `notifications/initialized`).
+ * Represents a JSON-RPC 2.0 notification — a fire-and-forget `method` call that is answered
+ * by nothing (for example, `notifications/initialized`).
  *
  * @remarks
  * A notification MUST NOT carry an `id`, so `id` is declared `never`: a
@@ -1771,14 +2313,14 @@ export declare type JSONRPCMessage = JSONRPCInvocation | JSONRPCResponse;
 export declare interface JSONRPCNotification {
     readonly jsonrpc: '2.0';
     readonly method: string;
-    /** Forbidden — an id is what makes a call a {@link JSONRPCRequest} instead. */
+    /** Forbids this member; an id is what makes a call a {@link JSONRPCRequest} instead. */
     readonly id?: never;
-    /** The method's open argument record (narrowed by the handler). */
+    /** Holds the method's open argument record (narrowed by the handler). */
     readonly params?: Readonly<Record<string, unknown>>;
 }
 
 /**
- * A JSON-RPC 2.0 request — a `method` call with optional `params`, correlated to
+ * Represents a JSON-RPC 2.0 request — a `method` call with optional `params`, correlated to
  * its response by the `id` it REQUIRES.
  *
  * @remarks
@@ -1791,12 +2333,12 @@ export declare interface JSONRPCRequest {
     readonly method: string;
     /** Correlates the request with its response. */
     readonly id: JSONRPCId;
-    /** The method's open argument record (narrowed by the handler). */
+    /** Holds the method's open argument record (narrowed by the handler). */
     readonly params?: Readonly<Record<string, unknown>>;
 }
 
 /**
- * A JSON-RPC 2.0 response — the answer to one {@link JSONRPCRequest}.
+ * Represents a JSON-RPC 2.0 response — the answer to one {@link JSONRPCRequest}.
  *
  * @remarks
  * The arms are mutually exclusive in the type and in their guards. Narrow them
@@ -1805,8 +2347,8 @@ export declare interface JSONRPCRequest {
 export declare type JSONRPCResponse = JSONRPCResultResponse | JSONRPCErrorResponse;
 
 /**
- * The success arm of a JSON-RPC 2.0 response — the request's `id` echoed with the
- * method's `result`.
+ * Represents the success arm of a JSON-RPC 2.0 response — the request's `id` echoed with
+ * the method's `result`.
  *
  * @remarks
  * A result answers a request, and a request always has a readable `id`, so `id` is
@@ -1817,7 +2359,7 @@ export declare interface JSONRPCResultResponse {
     readonly jsonrpc: '2.0';
     readonly id: JSONRPCId;
     readonly result: MCPResult | MCPLegacyResult;
-    /** Forbidden — an answer carries a result or an error, never both. */
+    /** Forbids this member; an answer carries a result or an error, never both. */
     readonly error?: never;
 }
 
@@ -1858,7 +2400,7 @@ export declare function legacyResultToModern(result: MCPLegacyResult, method: st
  *
  * @param method - The method the pending request was issued for
  * @param resultType - The unknown `resultType` the peer answered with
- * @returns Whether that method may legally answer with that `resultType`
+ * @returns True if that method may legally answer with that `resultType`; false otherwise
  *
  * @example
  * ```ts
@@ -1874,12 +2416,12 @@ export declare function matchesResultType(method: string, resultType: unknown):
  *
  * @param notification - The server notification offered by the configured producer
  * @param filter - The filter acknowledged to the client
- * @returns `true` when the notification belongs on this subscription stream
+ * @returns True if the notification belongs on this subscription stream; false otherwise
  */
 export declare function matchesSubscriptionNotification(notification: JSONRPCNotification, filter: MCPSubscriptionFilter): boolean;
 
 /**
- * The reserved extension key identifying the stable Tasks extension.
+ * Names the reserved extension key identifying the stable Tasks extension.
  *
  * @remarks
  * The ONE spelling of it in this package, and the identity of the immutable snapshot dated
@@ -1890,11 +2432,11 @@ export declare function matchesSubscriptionNotification(notification: JSONRPCNot
  */
 export declare const MCP_EXTENSION_TASKS = "io.modelcontextprotocol/tasks";
 
-/** The older legacy revision the optional legacy decorator accepts and an adapter can pin. */
+/** Names the older legacy revision the optional legacy decorator accepts and an adapter can pin. */
 export declare const MCP_FALLBACK_VERSION: MCPLegacyVersion;
 
 /**
- * The revision offered and defaulted to in the legacy `initialize` handshake.
+ * Names the revision offered and defaulted to in the legacy `initialize` handshake.
  *
  * @remarks
  * This is deliberately a legacy revision, and the newest one supported. 2026-07-28 is stateless
@@ -1903,26 +2445,62 @@ export declare const MCP_FALLBACK_VERSION: MCPLegacyVersion;
  */
 export declare const MCP_HANDSHAKE_VERSION: MCPLegacyVersion;
 
-/** MCP reserved error: required HTTP metadata does not match the request body. */
+/**
+ * Identifies the tool-schema annotation key naming the header one parameter projects into.
+ *
+ * @remarks
+ * It is valid ONLY on a primitive property schema statically reachable from the `inputSchema`
+ * root through `properties` keys alone. An occurrence anywhere else — under `items`, a
+ * composition or conditional keyword, or a `$ref` target — makes the whole tool definition
+ * invalid, which is what {@link import('@orkestrel/mcp').buildHeaderParameters} decides.
+ */
+export declare const MCP_HEADER_ANNOTATION = "x-mcp-header";
+
+/** Names the MCP reserved error for required HTTP metadata that does not match the request body. */
 export declare const MCP_HEADER_MISMATCH = -32020;
 
-/** Reserved modern `_meta` key carrying the client's open capability record. */
+/**
+ * Bounds the `tools/list` pages one modern `tools/call` walks to reach its own annotations.
+ *
+ * @remarks
+ * The HTTP POST handler reads a called tool's {@link MCP_HEADER_ANNOTATION} annotations by
+ * dispatching `tools/list` fresh on every `tools/call`, following `nextCursor` until the
+ * named tool is found or the answer carries no cursor. The walk is bounded because its cost
+ * is paid per call: at a page size of 100 this bound reaches 800 definitions, and a consumer
+ * whose replacement `tools/list` pages more finely than that pays the extra dispatches on
+ * every call it serves. The built-in listing answers the whole registry on one page and
+ * never reaches the second. A definition further in than the walk reaches reads as no
+ * definition, so its {@link MCP_PARAM_PREFIX} headers are forwarded untouched — the same
+ * answer a name no served definition annotates receives.
+ */
+export declare const MCP_LOOKUP_PAGES = 8;
+
+/** Names the reserved modern `_meta` key carrying the client's open capability record. */
 export declare const MCP_META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
 
-/** Reserved modern `_meta` key carrying the optional client identity. */
+/** Names the reserved modern `_meta` key carrying the optional client identity. */
 export declare const MCP_META_CLIENT = "io.modelcontextprotocol/clientInfo";
 
-/** Reserved modern `_meta` key carrying the server identity on results. */
+/** Names the reserved modern `_meta` key carrying the server identity on results. */
 export declare const MCP_META_SERVER = "io.modelcontextprotocol/serverInfo";
 
-/** Reserved modern `_meta` key carrying a `subscriptions/listen` request id. */
+/** Names the reserved modern `_meta` key carrying a `subscriptions/listen` request id. */
 export declare const MCP_META_SUBSCRIPTION = "io.modelcontextprotocol/subscriptionId";
 
-/** Reserved modern `_meta` key carrying the request's protocol revision. */
+/** Names the reserved modern `_meta` key carrying the request's protocol revision. */
 export declare const MCP_META_VERSION = "io.modelcontextprotocol/protocolVersion";
 
 /**
- * MCP reserved error: an operation needs a client capability that was not declared.
+ * Names the modern Streamable-HTTP request header carrying the JSON-RPC method.
+ *
+ * @remarks
+ * It is stamped on every modern request and on no legacy request.
+ */
+export declare const MCP_METHOD_HEADER = "mcp-method";
+
+/**
+ * Names the MCP reserved error for an operation needing a client capability that was not
+ * declared.
  *
  * @remarks
  * The GENERIC code for the whole condition, not one capability's code. This server answers
@@ -1936,20 +2514,91 @@ export declare const MCP_META_VERSION = "io.modelcontextprotocol/protocolVersion
  */
 export declare const MCP_MISSING_CAPABILITY = -32021;
 
-/** The modern revision offered by an unpinned client during discovery. */
+/** Names the modern revision offered by an unpinned client during discovery. */
 export declare const MCP_MODERN_VERSION: MCPModernVersion;
 
-/** MCP reserved error: a request names an unsupported protocol revision. */
+/**
+ * Names the modern Streamable-HTTP request header carrying a named target.
+ *
+ * @remarks
+ * The HTTP client transport stamps it only for `tools/call`, from that request's `params.name`,
+ * in the Base64 sentinel form whenever the name cannot ride as plain ASCII.
+ */
+export declare const MCP_NAME_HEADER = "mcp-name";
+
+/**
+ * Names the request-header prefix an `x-mcp-header` annotation projects a tool argument onto.
+ *
+ * @remarks
+ * The full field name is this prefix followed by the annotation's own value verbatim, so
+ * `x-mcp-header: 'Region'` becomes `Mcp-Param-Region`. HTTP field names are case-insensitive,
+ * which is why {@link MCP_HEADER_ANNOTATION} values are unique case-insensitively within one
+ * `inputSchema`.
+ */
+export declare const MCP_PARAM_PREFIX = "Mcp-Param-";
+
+/**
+ * Names the Streamable-HTTP transport header carrying the MCP protocol version.
+ *
+ * @remarks
+ * A modern request derives it from its own `_meta`; a legacy request echoes the revision the
+ * `initialize` result negotiated on each subsequent request.
+ */
+export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+
+/**
+ * Names the opening marker of the Base64 sentinel a standard MCP header value travels in.
+ *
+ * @remarks
+ * The markers are LOWERCASE and exact, and this constant with {@link MCP_SENTINEL_SUFFIX} is
+ * their ONE spelling in this package: {@link import('@orkestrel/mcp').encodeSentinel} builds a
+ * sentinel from them and {@link import('@orkestrel/mcp').decodeSentinel} recognizes one by
+ * them, so the two directions cannot drift apart.
+ */
+export declare const MCP_SENTINEL_PREFIX = "=?base64?";
+
+/** Names the closing marker of the Base64 sentinel a standard MCP header value travels in. */
+export declare const MCP_SENTINEL_SUFFIX = "?=";
+
+/**
+ * Names the Streamable-HTTP transport header that carries the MCP session id.
+ *
+ * @remarks
+ * A STATEFUL server sends it on the `initialize` reply, and
+ * {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport} echoes it as a
+ * request header on every subsequent request, so a client passes that server's session
+ * validation unchanged.
+ */
+export declare const MCP_SESSION_HEADER = "mcp-session-id";
+
+/** Names the MCP reserved error for a request naming an unsupported protocol revision. */
 export declare const MCP_UNSUPPORTED_VERSION = -32022;
 
-/** Optional audience, importance, and modification hints attached to MCP content. */
+/**
+ * Names the WebSocket subprotocol `createWebSocketClientTransport` requests by default —
+ * `'mcp'`, which `createWebSocketServer` selects when the client offers it. Per RFC 6455
+ * §4.1 a client MUST fail the connection if the server returns
+ * a subprotocol it did not request; Node ≥ 22 (undici) enforces this strictly, so the
+ * default bakes the correct value in. Override `WebSocketClientTransportOptions.protocols`
+ * only when connecting to a foreign server that speaks a different subprotocol (or `[]`
+ * for no subprotocol negotiation at all).
+ *
+ * @remarks
+ * The client sends it in `Sec-WebSocket-Protocol` and the server echoes it in its `101`
+ * handshake, so an MCP WebSocket endpoint is distinguishable from any other WebSocket on the
+ * same path. The default WebSocket upgrade path is the same `'/mcp'` the HTTP transport mounts
+ * at — the upgrade is selected by the `Upgrade: websocket` header, not a separate path.
+ */
+export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
+
+/** Represents the optional audience, importance, and modification hints on MCP content. */
 export declare interface MCPAnnotations {
     readonly audience?: readonly MCPRole[];
     readonly priority?: number;
     readonly lastModified?: string;
 }
 
-/** A base64-encoded audio MCP content block. */
+/** Represents a base64-encoded audio MCP content block. */
 export declare interface MCPAudioContent {
     readonly type: 'audio';
     readonly data: string;
@@ -1958,7 +2607,7 @@ export declare interface MCPAudioContent {
     readonly _meta?: MCPMetaObject;
 }
 
-/** Embedded base64-encoded resource contents. */
+/** Represents embedded base64-encoded resource contents. */
 export declare interface MCPBlobResource {
     readonly uri: string;
     readonly mimeType?: string;
@@ -1980,10 +2629,11 @@ export declare interface MCPBlobResource {
  * - `progress` receives each `notifications/progress` frame the peer publishes for this
  *   request. Supplying it is what stamps the request's progress token, so a peer only
  *   reports where a caller is listening.
- * - `input` carries one input-required retry. Its `state` and `responses` leaves are
- *   required together. The retry must repeat the original `name` and byte-identical
- *   `arguments`; the client maps the leaves to the top-level `requestState` and
- *   `inputResponses` parameters.
+ * - `input` carries one input-required retry. `responses` is required; `state` is optional
+ *   because a peer may issue a round with no `requestState` to return, and the client sends
+ *   the `requestState` parameter exactly when a state is supplied. The retry must repeat the
+ *   original `name` and byte-identical `arguments`; the client maps the leaves to the
+ *   top-level `requestState` and `inputResponses` parameters.
  *
  * No option survives the call: the continuation data is placed only on that request, and when
  * the request settles — answered, refused, timed out, aborted, or drained by a `disconnect` —
@@ -1994,15 +2644,15 @@ export declare interface MCPCallOptions {
     readonly signal?: AbortSignal;
     /** Receives this request's progress frames; supplying it stamps the progress token. */
     readonly progress?: MCPProgressHandler;
-    /** Carries the protected state and responses for one input-required retry. */
+    /** Carries the responses, and any protected state, for one input-required retry. */
     readonly input?: {
-        readonly state: string;
+        readonly state?: string;
         readonly responses: Readonly<Record<string, unknown>>;
     };
 }
 
 /**
- * What one remote `tools/call` answered — the arms the dated protocol permits.
+ * Represents what one remote `tools/call` answered — the arms the dated protocol permits.
  *
  * @remarks
  * The peer chooses the arm, so the caller narrows on `resultType`:
@@ -2021,19 +2671,19 @@ export declare interface MCPCallOptions {
  */
 export declare type MCPCallOutcome = {
     readonly resultType: 'complete';
-    /** The remote tool's value — its `structuredContent`, or its parsed text. */
+    /** Holds the remote tool's value — its `structuredContent`, or its parsed text. */
     readonly value: unknown;
 } | MCPTaskResult | MCPInputResult;
 
-/** A required complete modern `tools/call` result. */
+/** Represents a required complete modern `tools/call` result. */
 export declare type MCPCallResult = MCPUnstampedCallResult & {
     readonly resultType: 'complete';
 };
 
 /**
- * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP server
- * over an injected {@link MCPClientTransportInterface}, negotiates the modern revision, and
- * exposes the server's tools as local {@link ToolInterface}s an agent can run.
+ * Connects to a REMOTE MCP server over any injected {@link MCPMessageTransportInterface},
+ * negotiates the modern revision, and exposes the server's tools as local
+ * {@link ToolInterface}s an agent can run.
  *
  * @remarks
  * - **The mirror of `MCPServer`.** The server DISPATCHES requests over a tool registry;
@@ -2097,7 +2747,7 @@ export declare class MCPClient implements MCPClientInterface {
     get emitter(): EmitterInterface<MCPClientEventMap>;
     get connected(): boolean;
     get version(): MCPModernVersion | undefined;
-    get transport(): MCPClientTransportInterface;
+    get transport(): MCPMessageTransportInterface;
     get tasks(): MCPTaskClientInterface;
     connect(): Promise<void>;
     discover(): Promise<MCPDiscoverResult>;
@@ -2107,7 +2757,7 @@ export declare class MCPClient implements MCPClientInterface {
     call(name: string, args: Readonly<Record<string, unknown>>, options?: MCPCallOptions): Promise<MCPCallOutcome>;
 }
 
-/** The open dated client-capability declaration carried by modern requests. */
+/** Represents the open dated client-capability declaration carried by modern requests. */
 export declare type MCPClientCapabilities = Readonly<Record<string, MCPMetaObject>> & {
     readonly experimental?: Readonly<Record<string, MCPMetaObject>>;
     readonly roots?: MCPMetaObject;
@@ -2123,7 +2773,7 @@ export declare type MCPClientCapabilities = Readonly<Record<string, MCPMetaObjec
 };
 
 /**
- * The push observation surface of an {@link MCPClientInterface} — the moments a
+ * Represents the push observation surface of an {@link MCPClientInterface} — the moments a
  * fire-and-forget observer (logging, tracing) subscribes to through `client.emitter.on`.
  *
  * @remarks
@@ -2144,20 +2794,19 @@ export declare type MCPClientCapabilities = Readonly<Record<string, MCPMetaObjec
  *   Declared as a `type` alias so the literal satisfies `EventMap`.
  */
 export declare type MCPClientEventMap = {
-    /** Era negotiation completed — the client is connected. */
+    /** Reports that era negotiation completed — the client is connected. */
     readonly connect: readonly [];
-    /** The client disconnected — pending requests rejected, the connection it owned closed or its close failed. */
+    /** Reports that the client disconnected — pending requests rejected, the connection it owned closed or its close failed. */
     readonly disconnect: readonly [];
-    /** A server-initiated notification arrived (not a response to a pending request). */
+    /** Reports that a server-initiated notification arrived (not a response to a pending request). */
     readonly notification: readonly [message: JSONRPCMessage];
-    /** A client-level fault surfaced for observation (typed `unknown`). */
+    /** Reports a client-level fault surfaced for observation (typed `unknown`). */
     readonly error: readonly [error: unknown];
 };
 
 /**
- * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP
- * server over an injected {@link MCPClientTransportInterface}, negotiates the
- * modern wire revision, and exposes the server's tools as local
+ * Connects to a REMOTE MCP server over any injected {@link MCPMessageTransportInterface},
+ * negotiates the modern wire revision, and exposes the server's tools as local
  * {@link ToolInterface}s an agent can run.
  *
  * @remarks
@@ -2176,7 +2825,7 @@ export declare type MCPClientEventMap = {
  *   non-`'complete'` arm throws there instead.
  * - **Per-request cancellation.** `call`'s `options.signal` cancels ONE in-flight request:
  *   it rejects locally on every carrier, and additionally writes `notifications/cancelled`
- *   where the transport declares itself {@link MCPClientTransportInterface.duplex}. It
+ *   where the transport declares itself {@link MCPMessageTransportInterface.duplex}. It
  *   never cancels the connection, and never a durable task — a call that already answered
  *   `resultType: 'task'` is a request that is over. Cancellation is advisory, so a
  *   response arriving after the abort is discarded rather than raised.
@@ -2209,14 +2858,15 @@ export declare type MCPClientEventMap = {
  */
 export declare interface MCPClientInterface {
     readonly emitter: EmitterInterface<MCPClientEventMap>;
-    /** Whether modern revision negotiation has completed and the client is connected. */
+    /** Reports whether modern revision negotiation has completed and the client is connected. */
     readonly connected: boolean;
-    /** The negotiated protocol revision, or `undefined` while disconnected. */
+    /** Holds the negotiated protocol revision, or `undefined` while disconnected. */
     readonly version: MCPModernVersion | undefined;
-    /** The injected transport the client drives the remote server over. */
-    readonly transport: MCPClientTransportInterface;
+    /** Holds the injected transport the client drives the remote server over. */
+    readonly transport: MCPMessageTransportInterface;
     /**
-     * The stable Tasks extension's client half — reading, answering, and stopping a durable task.
+     * Holds the stable Tasks extension's client half — reading, answering, and stopping a durable
+     * task.
      *
      * @remarks
      * Always present, because the `tasks/*` methods are ordinary requests a client may
@@ -2338,7 +2988,7 @@ export declare interface MCPClientInterface {
      *
      * `options.signal` cancels THIS request only — the caller stops waiting, the pending
      * request rejects, and the peer is TOLD on a carrier that can carry a client
-     * notification (see {@link MCPClientTransportInterface.duplex}). MCP cancellation is
+     * notification (see {@link MCPMessageTransportInterface.duplex}). MCP cancellation is
      * advisory: the peer may answer anyway, and that late answer is discarded rather than
      * raised. `options.progress` receives this request's progress frames.
      *
@@ -2351,7 +3001,7 @@ export declare interface MCPClientInterface {
 }
 
 /**
- * Options for `createMCPClient` — the {@link MCPClientTransportInterface} to drive, the
+ * Options for `createMCPClient` — the {@link MCPMessageTransportInterface} to drive, the
  * optional client {@link MCPIdentity}, the per-request `timeout`, and the reserved
  * `on` hooks.
  *
@@ -2378,176 +3028,52 @@ export declare interface MCPClientInterface {
  */
 export declare interface MCPClientOptions {
     readonly on?: EmitterHooks<MCPClientEventMap>;
-    /** The emitter's listener-error handler — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
-    readonly transport: MCPClientTransportInterface;
+    readonly transport: MCPMessageTransportInterface;
     readonly identity?: MCPIdentity;
-    /** The open client-capability record carried by modern requests. */
+    /** Holds the open client-capability record carried by modern requests. */
     readonly capabilities?: MCPClientCapabilities;
     /**
-     * An optional exact modern protocol revision pin; absence permits modern negotiation. A defined
+     * Pins an optional exact modern protocol revision; absence permits modern negotiation. A defined
      * pin must match the peer's discovery advertisement. An unsupported runtime value throws an
      * {@link MCPError} synchronously during construction.
      */
     readonly version?: MCPModernVersion;
-    /** The per-request deadline in milliseconds (default {@link import('./constants.js').DEFAULT_MCP_REQUEST_TIMEOUT}). */
+    /** Sets the per-request deadline in milliseconds (default {@link import('./constants.js').DEFAULT_MCP_REQUEST_TIMEOUT}). */
     readonly timeout?: number;
 }
 
-/**
- * The observable events of a {@link MCPClientTransportInterface} — the moments the
- * {@link MCPClientInterface} (and any tracer) subscribes to through `transport.emitter.on`.
- *
- * @remarks
- * - `message` — a JSON-RPC message ARRIVED from the remote server (a response the
- *   client correlates to a pending request by `id`, or a server-initiated
- *   notification). The transport decodes the wire bytes (a JSON body or an SSE
- *   `data:` event) and emits the parsed {@link JSONRPCMessage}.
- * - `close` — the transport's connection ended (a stream closed, `close()` ran).
- * - `error` — a transport-level fault (a malformed message, a network error); the
- *   payload is typed `unknown`. This is a DOMAIN event, distinct from the emitter's
- *   own listener-error channel: a listener throw is routed to the emitter's `error` handler
- *   (the `error` option), never onto this map. Declared as a `type` alias so the
- *   type-literal satisfies `EventMap` structurally.
- */
-export declare type MCPClientTransportEventMap = {
-    /** A JSON-RPC message arrived from the remote server (a response, or a notification). */
-    readonly message: readonly [message: JSONRPCMessage];
-    /** The transport's connection ended. */
-    readonly close: readonly [];
-    /** A transport-level fault — the caught error (typed `unknown`). */
-    readonly error: readonly [error: unknown];
-};
-
-/**
- * A transport-agnostic MCP message carrier — pumps JSON-RPC messages to a peer and
- * surfaces received messages on its `emitter`'s `message` event, with no knowledge
- * of the protocol role on either side.
- *
- * @remarks
- * A client hands the transport one {@link JSONRPCMessage} through `send`, and the
- * transport delivers each decoded reply through the `message` event. Server bridges
- * use the same carrier for bidirectional WebSocket and stdio channels. The minimal surface is a
- * `start` (open the connection / arm any reader), `send` (write one message),
- * and `close` (tear down). `session` exposes a server-assigned session id once a
- * stateful transport has one (`undefined` for the stateless v1) — reserved for the
- * later sessions tier. Concrete transports live in the browser and server environments;
- * the in-process loopback transport in the tests implements the same contract.
- */
-export declare interface MCPClientTransportInterface {
-    readonly emitter: EmitterInterface<MCPClientTransportEventMap>;
-    /** A server-assigned session id once a stateful transport has one; `undefined` otherwise. */
-    readonly session: string | undefined;
-    /**
-     * Whether this carrier accepts a CLIENT-INITIATED notification — one written with no
-     * `id`, which no response will ever answer.
-     *
-     * @remarks
-     * The transport states it because only the transport knows it, and getting it wrong is
-     * invisible: `send` accepts any {@link JSONRPCMessage}, so a carrier with no
-     * client→server notification channel will happily write one and drop it silently.
-     *
-     * `true` for a genuinely bidirectional channel — a WebSocket, a stdio pipe pair, an
-     * in-process duplex port — where a frame the client writes at any moment reaches the
-     * peer. `false` for a request/response carrier such as Streamable HTTP: the dated
-     * revision defines NO client-to-server notification over it, and the cancellation
-     * signal there is closing the response stream rather than a frame. A `false` carrier
-     * is not a degraded one — it has its own signal — so the client withholds the frame
-     * rather than writing one nothing will read.
-     */
-    readonly duplex: boolean;
-    /**
-     * Opens the transport — establishes the connection and arms any reply reader.
-     *
-     * @remarks
-     * A `start` that REJECTS must first release whatever it had already acquired. The
-     * {@link MCPClientInterface} claims a connection only once `start` resolves, so a rejection
-     * leaves it holding an error and no claim: a socket, session, or reader the transport opened
-     * before failing is reachable by nothing the client can call, and no client-side mechanism can
-     * be added that would reach it.
-     *
-     * @returns Resolves once the transport is ready to `send`
-     */
-    start(): Promise<void>;
-    /**
-     * Sends one JSON-RPC message to the remote server.
-     *
-     * @remarks
-     * Each decoded reply is surfaced on the `emitter`'s `message` event — `send`
-     * itself resolves once the message has been written (and, for a request/response
-     * transport, its synchronous reply emitted), not when a logical response arrives;
-     * the {@link MCPClientInterface} awaits the response through its `id` correlation.
-     *
-     * A `send` that FAILS must fail by REJECTING, never by throwing synchronously. The
-     * {@link MCPClientInterface} registers the write inside the same promise executor that
-     * records the request's pending entry, so a synchronous throw leaves no promise for that
-     * registration to attach to: the entry set one statement earlier is never settled, and a
-     * later abort writes `notifications/cancelled` naming a request the write never delivered.
-     * An `async send` satisfies this by construction, which is why every transport this package
-     * ships declares one; a non-`async` implementation returns a rejected promise instead of
-     * throwing. The client cannot enforce this from its side — the throw and the write are
-     * indistinguishable to it — so it is stated here, on the contract that owns it.
-     *
-     * A transport whose channel confirms the write rejects on its failure. A transport whose
-     * exchange reports through the emitter resolves. A transport whose channel cannot confirm a
-     * write answers a closed channel from its own state, and each states which in its own
-     * remarks.
-     *
-     * @param message - The message to write to the wire
-     * @returns Resolves once the message has been sent, and rejects — never throws — when the
-     * write fails
-     */
-    send(message: JSONRPCMessage): Promise<void>;
-    /**
-     * Closes the transport — ends the connection and releases resources.
-     *
-     * @remarks
-     * A `close` must SETTLE, and its settlements mean different things to its caller: resolving
-     * says the connection ended, rejecting says it did not. The
-     * {@link MCPClientInterface}'s only other bound is a deadline, which reports that the shutdown
-     * did not ANSWER and never that it did not happen — so a `close` that resolves or rejects hours
-     * late still decides the outcome, and one that never settles leaves the connection owed for the
-     * client's life. `close` is never called twice concurrently for one connection: a caller that
-     * gave up waiting JOINS the `close` still running rather than issuing another. It IS called
-     * again after an earlier `close` REJECTED, because a rejected close ended nothing.
-     *
-     * `close` is IDEMPOTENT: a call on a transport an earlier `close` already ended resolves
-     * without emitting `close` again and without releasing anything a second time. Idempotence
-     * bounds ONE closed lifetime rather than the object — a transport that reopens on `start`
-     * arms itself there, and its next `close` ends that connection and emits once for it.
-     *
-     * @returns Resolves once the transport is closed
-     */
-    close(): Promise<void>;
-}
-
-/** One completion candidate set before the protocol's 100-value projection cap. */
+/** Represents one completion candidate set before the protocol's 100-value projection cap. */
 export declare interface MCPCompletion {
     readonly values: readonly string[];
     readonly total?: number;
     readonly hasMore?: boolean;
 }
 
-/** The argument fragment being completed. */
+/** Represents the argument fragment being completed. */
 export declare interface MCPCompletionArgument {
     readonly name: string;
     readonly value: string;
 }
 
-/** Previously resolved string arguments supplied as completion context. */
+/** Holds previously resolved string arguments supplied as completion context. */
 export declare interface MCPCompletionContext {
     readonly arguments?: Readonly<Record<string, string>>;
 }
 
 /**
- * Consumer-supplied completion port for prompt and resource-template arguments.
+ * Represents the consumer-supplied completion port for prompt and resource-template arguments.
  *
  * @remarks
  * The host owns reference lookup and template-variable knowledge. MCP forwards the reference
  * verbatim and performs no template parsing or expansion. Returning `undefined` means the
  * referenced prompt or resource template does not exist.
+ *
+ * This is the PORT that produces a {@link MCPCompletion}, not the behavioural face of one: the
+ * candidate set is the data type, and this contract is the single method a host answers it from.
  */
-export declare interface MCPCompletionManagerInterface {
+export declare interface MCPCompletionInterface {
     /**
      * Completes one argument against its host-owned reference.
      *
@@ -2565,20 +3091,20 @@ export declare interface MCPCompletionParams {
     readonly context?: MCPCompletionContext;
 }
 
-/** The prompt or resource-template reference accepted by `completion/complete`. */
+/** Represents the prompt or resource-template reference accepted by `completion/complete`. */
 export declare type MCPCompletionReference = MCPPromptReference | MCPResourceTemplateReference;
 
-/** The complete `completion/complete` result. */
+/** Represents the complete `completion/complete` result. */
 export declare interface MCPCompletionResult {
     readonly resultType: 'complete';
     readonly completion: MCPCompletion;
     readonly _meta?: MCPResultMetaObject;
 }
 
-/** One exact dated-schema tool content block. */
+/** Represents one exact dated-schema tool content block. */
 export declare type MCPContent = MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceLink | MCPEmbeddedResource;
 
-/** Host-neutral integrity and storage port for opaque MRTR continuation state. */
+/** Represents the host-neutral integrity and storage port for opaque MRTR continuation state. */
 export declare interface MCPContinuationInterface {
     /** Protects a canonical state string and returns the opaque client carrier. */
     seal(value: string): Promise<string>;
@@ -2586,7 +3112,7 @@ export declare interface MCPContinuationInterface {
     open(value: string): Promise<string | undefined>;
 }
 
-/** The mandatory modern `server/discover` result. */
+/** Represents the mandatory modern `server/discover` result. */
 export declare type MCPDiscoverResult = {
     readonly supportedVersions: readonly MCPModernVersion[];
     readonly capabilities: MCPServerCapabilities;
@@ -2598,7 +3124,7 @@ export declare type MCPDiscoverResult = {
 };
 
 /**
- * The minimal transport-facing MCP dispatch surface.
+ * Represents the minimal transport-facing MCP dispatch surface.
  *
  * @remarks
  * A transport-facing dispatcher needs the resolved message limit and the `dispatch` and
@@ -2606,9 +3132,9 @@ export declare type MCPDiscoverResult = {
  * no response channel for a contained transport fault and must report that fault as an event.
  */
 export declare interface MCPDispatcherInterface {
-    /** The shared server observation surface, including contained transport faults. */
+    /** Holds the shared server observation surface, including contained transport faults. */
     readonly emitter: EmitterInterface<MCPServerEventMap>;
-    /** The resolved bounds the dispatcher enforces. */
+    /** Holds the resolved bounds the dispatcher enforces. */
     readonly limit: Required<MCPLimitOptions>;
     /**
      * Dispatches a parsed JSON-RPC request.
@@ -2645,7 +3171,7 @@ export declare interface MCPDispatcherInterface {
 }
 
 /**
- * Per-request execution options every dispatched handler receives.
+ * Represents the per-request execution options every dispatched handler receives.
  *
  * @remarks
  * `caller` is consumer-ASSERTED and NEVER VERIFIED. Sessions mint transport identity, not
@@ -2656,23 +3182,17 @@ export declare interface MCPDispatcherInterface {
 export declare interface MCPDispatchOptions {
     /** Aborts when the bound transport can observe that the caller's request has ended. */
     readonly signal?: AbortSignal;
-    /** Consumer-asserted caller context, forwarded opaquely and never protocol-verified. */
+    /** Carries consumer-asserted caller context, forwarded opaquely and never protocol-verified. */
     readonly caller?: unknown;
 }
 
-/** One consumer-requested form elicitation, before MCP assigns its map key and signs state. */
-export declare interface MCPElicitation {
-    readonly request: MCPElicitForm;
-    readonly state?: JSONValue;
-}
-
-/** One titled value in a form elicitation's single- or multi-select schema. */
+/** Represents one titled value in a form elicitation's single- or multi-select schema. */
 export declare interface MCPElicitChoice {
     readonly const: string;
     readonly title: string;
 }
 
-/** One restricted single-field schema accepted by MCP form-mode elicitation. */
+/** Represents one restricted single-field schema accepted by MCP form-mode elicitation. */
 export declare type MCPElicitFieldSchema = {
     readonly type: 'boolean';
     readonly title?: string;
@@ -2727,29 +3247,29 @@ export declare type MCPElicitFieldSchema = {
     };
 };
 
-/** The parameters of a form-mode `elicitation/create` request. */
+/** Represents the parameters of a form-mode `elicitation/create` request. */
 export declare interface MCPElicitForm {
     readonly mode?: 'form';
     readonly message: string;
     readonly requestedSchema: MCPElicitSchema;
 }
 
-/** The mode-discriminated parameters of an `elicitation/create` request. */
+/** Represents the mode-discriminated parameters of an `elicitation/create` request. */
 export declare type MCPElicitParams = MCPElicitForm | MCPElicitURL;
 
-/** An embedded MCP request asking the client to elicit input from its operator. */
+/** Represents an embedded MCP request asking the client to elicit input from its operator. */
 export declare interface MCPElicitRequest {
     readonly method: 'elicitation/create';
     readonly params: MCPElicitParams;
 }
 
-/** The result supplied by a client for one embedded {@link MCPElicitRequest}. */
+/** Represents the result supplied by a client for one embedded {@link MCPElicitRequest}. */
 export declare interface MCPElicitResult {
     readonly action: 'accept' | 'decline' | 'cancel';
     readonly content?: Readonly<Record<string, MCPElicitValue>>;
 }
 
-/** The restricted top-level object schema carried by a form-mode elicitation request. */
+/** Represents the restricted top-level object schema in a form-mode elicitation request. */
 export declare interface MCPElicitSchema extends Readonly<Record<string, unknown>> {
     readonly $schema?: string;
     readonly type: 'object';
@@ -2757,17 +3277,17 @@ export declare interface MCPElicitSchema extends Readonly<Record<string, unknown
     readonly required?: readonly string[];
 }
 
-/** The parameters of a URL-mode `elicitation/create` request. */
+/** Represents the parameters of a URL-mode `elicitation/create` request. */
 export declare interface MCPElicitURL {
     readonly mode: 'url';
     readonly message: string;
     readonly url: string;
 }
 
-/** The primitive value shapes accepted in an MCP form elicitation response. */
+/** Names the primitive value shapes accepted in an MCP form elicitation response. */
 export declare type MCPElicitValue = string | number | boolean | readonly string[];
 
-/** An MCP content block carrying embedded text or blob resource contents. */
+/** Represents an MCP content block carrying embedded text or blob resource contents. */
 export declare interface MCPEmbeddedResource {
     readonly type: 'resource';
     readonly resource: MCPTextResource | MCPBlobResource;
@@ -2776,7 +3296,7 @@ export declare interface MCPEmbeddedResource {
 }
 
 /**
- * The wire era selected by an MCP request's structure.
+ * Names the wire era selected by an MCP request's structure.
  *
  * @remarks
  * `'modern'` and `'legacy'`, and not the boolean such a union would usually be: this is
@@ -2789,7 +3309,7 @@ export declare interface MCPEmbeddedResource {
 export declare type MCPEra = 'modern' | 'legacy';
 
 /**
- * A Model Context Protocol error preserving its machine-readable numeric code and
+ * Preserves a Model Context Protocol error's machine-readable numeric code and
  * optional structured context.
  *
  * @remarks
@@ -2825,7 +3345,7 @@ export declare class MCPError extends Error {
     constructor(message: string, code: number, context?: unknown);
 }
 
-/** The explicit, host-neutral context for one modern tool execution. */
+/** Represents the explicit, host-neutral context for one modern tool execution. */
 export declare interface MCPExecutionContext {
     readonly request: JSONRPCRequest;
     readonly call: ToolCall;
@@ -2834,10 +3354,38 @@ export declare interface MCPExecutionContext {
     readonly progress?: MCPProgressInterface;
 }
 
-/** Executes one canonical tool call or return a fully formed complete MCP result. */
+/** Executes one canonical tool call or returns a fully formed complete MCP result. */
 export declare type MCPExecutionHandler = (context: MCPExecutionContext) => ToolResult | MCPCallResult | Promise<ToolResult | MCPCallResult>;
 
-/** One sized, themed icon associated with an MCP resource link. */
+/**
+ * Represents one `x-mcp-header` projection a tool's `inputSchema` declares.
+ *
+ * @remarks
+ * - `name` — the annotation's own value, appended verbatim to {@link MCP_PARAM_PREFIX} to
+ *   form the request field name.
+ * - `path` — the `properties` keys leading from the `inputSchema` root to the annotated
+ *   leaf, which is also the path the call's `arguments` carry the value at.
+ * - `primitive` — the leaf's declared type, which fixes the value's text rendering and, for
+ *   `integer`, makes the server's comparison numeric rather than textual.
+ */
+export declare interface MCPHeaderParameter {
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly primitive: MCPHeaderPrimitive;
+}
+
+/**
+ * Names the JSON Schema types an `x-mcp-header` annotation may sit on.
+ *
+ * @remarks
+ * The protocol admits primitives alone, and it splits the JSON Schema number tower: `integer`
+ * carries a decimal rendering an HTTP field can hold exactly, while `number` has no
+ * interoperable text form and is refused. `object`, `array`, and `null` are refused for the
+ * same reason — a header field carries text, not structure.
+ */
+export declare type MCPHeaderPrimitive = 'boolean' | 'integer' | 'string';
+
+/** Represents one sized, themed icon associated with an MCP resource link. */
 export declare type MCPIcon = MCPMetaObject & {
     readonly src: string;
     readonly mimeType?: string;
@@ -2845,7 +3393,7 @@ export declare type MCPIcon = MCPMetaObject & {
     readonly theme?: 'light' | 'dark';
 };
 
-/** The complete dated identity of an MCP server or client. */
+/** Represents the complete dated identity of an MCP server or client. */
 export declare type MCPIdentity = MCPMetaObject & {
     readonly name: string;
     readonly version: string;
@@ -2855,7 +3403,7 @@ export declare type MCPIdentity = MCPMetaObject & {
     readonly icons?: readonly MCPIcon[];
 };
 
-/** A base64-encoded image MCP content block. */
+/** Represents a base64-encoded image MCP content block. */
 export declare interface MCPImageContent {
     readonly type: 'image';
     readonly data: string;
@@ -2864,43 +3412,48 @@ export declare interface MCPImageContent {
     readonly _meta?: MCPMetaObject;
 }
 
-/** The call-in-hand context supplied to an {@link MCPInputHandler}. */
+/** Represents the call-in-hand context supplied to an {@link MCPInputHandler}. */
 export declare interface MCPInputContext {
     readonly request: JSONRPCRequest;
     readonly name: string;
     readonly arguments: Readonly<Record<string, unknown>>;
-    readonly response?: MCPElicitResult;
+    /** Holds every verified answer to the previous round, under the keys that round assigned. */
+    readonly responses?: MCPInputResponseMap;
     readonly state?: JSONValue;
 }
 
 /**
- * Decides whether the current `tools/call` needs operator input.
+ * Decides whether the current `tools/call` still needs input from the client.
  *
- * @param context - The original call plus a verified response/state on a retry
+ * @param context - The original call plus every verified answer and state on a retry
  * @param options - The resolved per-request method options
- * @returns A form elicitation to send, or `undefined` to continue into the tool registry
+ * @returns The next round to send, or `undefined` to continue into the tool registry
  */
-export declare type MCPInputHandler = (context: MCPInputContext, options: MCPMethodOptions) => MCPElicitation | undefined | Promise<MCPElicitation | undefined>;
+export declare type MCPInputHandler = (context: MCPInputContext, options: MCPMethodOptions) => MCPInputRound | undefined | Promise<MCPInputRound | undefined>;
 
-/** Consumer policy for the server's multi-round-trip input mechanism. */
+/** Configures the consumer policy for the server's multi-round-trip input mechanism. */
 export declare interface MCPInputOptions {
-    /** Host-neutral integrity/storage port for the opaque continuation carrier. */
+    /** Holds the host-neutral integrity/storage port for the opaque continuation carrier. */
     readonly continuation: MCPContinuationInterface;
-    /** Continuation lifetime in milliseconds; required so MCP never invents an expiry policy. */
+    /**
+     * Sets the continuation lifetime in milliseconds; required so MCP never invents an expiry policy.
+     */
     readonly ttl: number;
     /** Resolves the authenticated principal for the call in hand. */
     readonly principal: MCPPrincipalHandler;
-    /** Decides whether the call needs a form elicitation, including on verified retries. */
-    readonly elicit: MCPInputHandler;
+    /** Composes the next round of input requests, including on verified retries. */
+    readonly selector: MCPInputHandler;
 }
 
 /**
- * One embedded multi-round-trip request.
+ * Represents one embedded multi-round-trip request.
  *
  * @remarks
- * This package produces only {@link MCPElicitRequest}. The deprecated sampling and roots
- * requests remain legal protocol union members and therefore retain their open parameter
- * records here without gaining package-owned producers.
+ * A consumer composes any of the three arms into an {@link MCPInputRound}, and this server
+ * issues whichever arms that round carries. The elicitation arm is fully typed because this
+ * package issues its schema and enforces the answer against it. The sampling and roots arms
+ * keep OPEN parameter records: the dated schema leaves their request bodies to the caller, and
+ * narrowing them here would refuse parameters the protocol permits.
  */
 export declare type MCPInputRequest = MCPElicitRequest | {
     readonly method: 'sampling/createMessage';
@@ -2910,11 +3463,27 @@ export declare type MCPInputRequest = MCPElicitRequest | {
     readonly params?: Readonly<Record<string, unknown>>;
 };
 
-/** A server-keyed map of embedded requests the client must fulfil. */
+/** Represents a consumer-keyed map of embedded requests the client must fulfil. */
 export declare type MCPInputRequestMap = Readonly<Record<string, MCPInputRequest>>;
 
 /**
- * An incomplete modern result carrying input requests, protected request state, or both.
+ * Represents one client answer to one embedded input request.
+ *
+ * @remarks
+ * The arms are discriminated by their own required members — `action` for an elicitation,
+ * `roots` for a roots listing, and `model` beside `role` for a sampling completion — because
+ * the protocol gives a response no `method` of its own. The server knows which arm applies
+ * from the request it ISSUED under that key, so {@link MCPInputHandler} receives every answer
+ * already checked against the question it answers.
+ */
+export declare type MCPInputResponse = MCPElicitResult | MCPSampleResult | MCPRootResult;
+
+/** Represents a consumer-keyed map of the client's answers to one issued round. */
+export declare type MCPInputResponseMap = Readonly<Record<string, MCPInputResponse>>;
+
+/**
+ * Represents an incomplete modern result carrying input requests, protected request state,
+ * or both.
  *
  * @remarks
  * The union enforces the protocol's at-least-one-of rule at the type boundary:
@@ -2933,15 +3502,30 @@ export declare type MCPInputResult = {
 };
 
 /**
- * The integrity-protected payload carried inside an opaque `requestState` token.
+ * Represents one consumer-composed round of embedded requests, before MCP seals its
+ * continuation state.
+ *
+ * @remarks
+ * The consumer owns the keys and the request kinds, because the keys are how it correlates
+ * each answer and the kinds are what its own policy needs. MCP owns everything protective
+ * around the round: the capability gate, the seal, the expiry, and the per-answer check on
+ * the retry.
+ */
+export declare interface MCPInputRound {
+    readonly requests: MCPInputRequestMap;
+    readonly state?: JSONValue;
+}
+
+/**
+ * Represents the integrity-protected payload carried inside an opaque `requestState` token.
  *
  * @remarks
  * `id` is the FIRST round's request id and stays bound across every later round, so a
  * multi-round exchange remains one correlated call rather than a chain whose origin is lost
- * after the second hop. `schema` is the EXACT schema that was issued with the round it
- * protects: a schema that is bound but never enforced buys nothing, so an accepted response
- * is checked against this member by {@link isElicitContent} before the tool runs. `key`,
- * `expiry`, and `schema` are re-minted every round; `principal`, `id`, `version`, `method`,
+ * after the second hop. `requests` is the EXACT round that was issued: it carries the keys the
+ * retry must answer and, for a form elicitation, the schema {@link isElicitContent} enforces
+ * an accepted answer against — a round that is bound but never enforced buys nothing.
+ * `requests` and `expiry` are re-minted every round; `principal`, `id`, `version`, `method`,
  * `name`, and `digest` are the bindings that must not move.
  */
 export declare interface MCPInputState {
@@ -2950,21 +3534,20 @@ export declare interface MCPInputState {
     readonly id: JSONRPCId;
     readonly version: string;
     readonly method: string;
-    readonly key: string;
+    /** Holds the exact round issued under this state, enforced answer by answer on the retry. */
+    readonly requests: MCPInputRequestMap;
     readonly name: string;
     readonly digest: string;
-    /** The exact schema issued with this round, enforced on the accepted response. */
-    readonly schema: MCPElicitSchema;
     readonly state?: JSONValue;
 }
 
 /** Limits applied by {@link isBoundedJSON} to one JSON value. */
 export declare interface MCPJSONLimitOptions {
-    /** Maximum serialized UTF-8 bytes. */
+    /** Bounds the serialized UTF-8 bytes. */
     readonly bytes: number;
-    /** Maximum total enumerable keys; omitted when bytes alone bound breadth. */
+    /** Bounds the total enumerable keys; omitted when bytes alone bound breadth. */
     readonly keys?: number;
-    /** Maximum array/object nesting depth. */
+    /** Bounds the array/object nesting depth. */
     readonly depth: number;
 }
 
@@ -3005,7 +3588,7 @@ export declare class MCPLegacy implements MCPDispatcherInterface {
  * restores legacy results to modern complete-result shapes before delivery, and bounds retained
  * request correlations with the configured deadline.
  */
-export declare class MCPLegacyClientTransport implements MCPClientTransportInterface {
+export declare class MCPLegacyClientTransport implements MCPMessageTransportInterface {
     #private;
     /**
      * Creates a legacy client transport adapter.
@@ -3013,8 +3596,8 @@ export declare class MCPLegacyClientTransport implements MCPClientTransportInter
      * @param transport - The legacy peer transport
      * @param options - The legacy handshake identity, capabilities, revision, and deadline
      */
-    constructor(transport: MCPClientTransportInterface, options?: MCPLegacyClientTransportOptions);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap>;
+    constructor(transport: MCPMessageTransportInterface, options?: MCPLegacyClientTransportOptions);
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
@@ -3050,26 +3633,26 @@ export declare class MCPLegacyClientTransport implements MCPClientTransportInter
  * the peer. Do not send unrelated id-`0` traffic through the wrapped transport in that window.
  */
 export declare interface MCPLegacyClientTransportOptions {
-    /** The client identity sent during the legacy handshake. */
+    /** Holds the client identity sent during the legacy handshake. */
     readonly identity?: MCPIdentity;
-    /** The client capabilities sent during the legacy handshake. */
+    /** Holds the client capabilities sent during the legacy handshake. */
     readonly capabilities?: MCPClientCapabilities;
-    /** The exact legacy revision to request and require. */
+    /** Names the exact legacy revision to request and require. */
     readonly version?: MCPLegacyVersion;
-    /** The legacy handshake and forwarded-request deadline in milliseconds. */
+    /** Sets the legacy handshake and forwarded-request deadline in milliseconds. */
     readonly timeout?: number;
 }
 
-/** Construction options for the removable legacy protocol decorator. */
+/** Represents the construction options for the removable legacy protocol decorator. */
 export declare interface MCPLegacyOptions {
-    /** The sole dispatcher and execution engine. */
+    /** Holds the sole dispatcher and execution engine. */
     readonly dispatcher: MCPDispatcherInterface;
-    /** The identity returned by the legacy `initialize` handshake. */
+    /** Holds the identity returned by the legacy `initialize` handshake. */
     readonly identity: MCPIdentity;
 }
 
 /**
- * One legacy-era result — the payload of an answer produced by the fixed legacy
+ * Represents one legacy-era result — the payload of an answer produced by the fixed legacy
  * method switch.
  *
  * @remarks
@@ -3083,42 +3666,45 @@ export declare interface MCPLegacyOptions {
  * This arm exists only for the optional legacy server decorator and client transport adapter.
  */
 export declare interface MCPLegacyResult {
-    /** Forbidden — the legacy revision has no result discriminator. */
+    /** Forbids this member; the legacy revision has no result discriminator. */
     readonly resultType?: never;
     readonly [key: string]: unknown;
 }
 
-/** A legacy protocol revision supported by the optional legacy decorators. */
+/** Names a legacy protocol revision supported by the optional legacy decorators. */
 export declare type MCPLegacyVersion = '2025-11-25' | '2025-06-18';
 
-/** Configurable hostile-input and live-resource bounds for an MCP server. */
+/** Configures the hostile-input and live-resource bounds for an MCP server. */
 export declare interface MCPLimitOptions {
-    /** Maximum UTF-8 bytes accepted by the raw string boundary. */
+    /** Bounds the UTF-8 bytes accepted by the raw string boundary. */
     readonly message?: number;
-    /** Maximum serialized UTF-8 bytes accepted in one `_meta` value. */
+    /** Bounds the serialized UTF-8 bytes accepted in one `_meta` value. */
     readonly metadata?: number;
-    /** Maximum total enumerable keys accepted across one `_meta` value. */
+    /**
+     * Bounds the total enumerable keys accepted in one bounded value: one `_meta` value under
+     * `metadata`, and one produced tool-call result under `content`.
+     */
     readonly keys?: number;
-    /** Maximum UTF-8 bytes accepted in one protected `requestState`. */
+    /** Bounds the UTF-8 bytes accepted in one protected `requestState`. */
     readonly state?: number;
-    /** Maximum serialized UTF-8 bytes accepted from one complete produced tool-call result. */
+    /** Bounds the serialized UTF-8 bytes accepted from one complete produced tool-call result. */
     readonly content?: number;
-    /** Maximum simultaneously live built-in subscription streams. */
+    /** Bounds the simultaneously live built-in subscription streams. */
     readonly subscriptions?: number;
-    /** Maximum nesting depth accepted by bounded JSON values. */
+    /** Bounds the nesting depth accepted by bounded JSON values. */
     readonly depth?: number;
 }
 
-/** Per-subscription cancellation and bounded buffering policy. */
+/** Configures the per-subscription cancellation and bounded buffering policy. */
 export declare interface MCPListenOptions {
     /** Aborts the subscription and rejects its pending read with the signal reason. */
     readonly signal: AbortSignal;
-    /** The maximum number of delivered frames retained while no read is parked. */
+    /** Bounds the number of delivered frames retained while no read is parked. */
     readonly capacity?: number;
 }
 
 /**
- * The MCP `tools/list` result — tool descriptors plus optional modern result
+ * Represents the MCP `tools/list` result — tool descriptors plus optional modern result
  * stamps.
  *
  * @remarks
@@ -3134,11 +3720,138 @@ export declare type MCPListResult = {
     readonly _meta?: MCPResultMetaObject;
 };
 
-/** The dated logging levels accepted by MCP request metadata. */
+/** Names the dated logging levels accepted by MCP request metadata. */
 export declare type MCPLoggingLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
 
 /**
- * Exact finite JSON metadata carried by MCP `_meta` envelopes.
+ * Lists the observable events of a {@link MCPMessageTransportInterface} — the moments the
+ * {@link MCPClientInterface} (and any tracer) subscribes to through `transport.emitter.on`.
+ *
+ * @remarks
+ * - `message` — a JSON-RPC message ARRIVED from the remote server (a response the
+ *   client correlates to a pending request by `id`, or a server-initiated
+ *   notification). The transport decodes the wire bytes (a JSON body or an SSE
+ *   `data:` event) and emits the parsed {@link JSONRPCMessage}.
+ * - `close` — the transport's connection ended (a stream closed, `close()` ran).
+ * - `error` — a transport-level fault (a malformed message, a network error); the
+ *   payload is typed `unknown`. This is a DOMAIN event, distinct from the emitter's
+ *   own listener-error channel: a listener throw is routed to the emitter's `error` handler
+ *   (the `error` option), never onto this map. Declared as a `type` alias so the
+ *   type-literal satisfies `EventMap` structurally.
+ */
+export declare type MCPMessageTransportEventMap = {
+    /** Reports that a JSON-RPC message arrived from the remote server (a response, or a notification). */
+    readonly message: readonly [message: JSONRPCMessage];
+    /** Reports that the transport's connection ended. */
+    readonly close: readonly [];
+    /** Reports a transport-level fault — the caught error (typed `unknown`). */
+    readonly error: readonly [error: unknown];
+};
+
+/**
+ * Pumps JSON-RPC messages to a peer and surfaces received messages on its `emitter`'s
+ * `message` event, with no knowledge of the protocol role on either side — a
+ * transport-agnostic MCP message carrier.
+ *
+ * @remarks
+ * A client hands the transport one {@link JSONRPCMessage} through `send`, and the
+ * transport delivers each decoded reply through the `message` event. Server bridges
+ * use the same carrier for bidirectional WebSocket and stdio channels. The minimal surface is a
+ * `start` (open the connection / arm any reader), `send` (write one message),
+ * and `close` (tear down). `session` exposes a server-assigned session id once a
+ * stateful transport has one (`undefined` for the stateless v1) — reserved for the
+ * later sessions tier. Concrete transports live in the browser and server environments;
+ * the in-process loopback transport in the tests implements the same contract.
+ */
+export declare interface MCPMessageTransportInterface {
+    readonly emitter: EmitterInterface<MCPMessageTransportEventMap>;
+    /** Holds a server-assigned session id after a stateful transport has one; `undefined` otherwise. */
+    readonly session: string | undefined;
+    /**
+     * Reports whether this carrier accepts a CLIENT-INITIATED notification — one written with
+     * no `id`, which no response will ever answer.
+     *
+     * @remarks
+     * The transport states it because only the transport knows it, and getting it wrong is
+     * invisible: `send` accepts any {@link JSONRPCMessage}, so a carrier with no
+     * client→server notification channel will happily write one and drop it silently.
+     *
+     * `true` for a genuinely bidirectional channel — a WebSocket, a stdio pipe pair, an
+     * in-process duplex port — where a frame the client writes at any moment reaches the
+     * peer. `false` for a request/response carrier such as Streamable HTTP: the dated
+     * revision defines NO client-to-server notification over it, and the cancellation
+     * signal there is closing the response stream rather than a frame. A `false` carrier
+     * is not a degraded one — it has its own signal — so the client withholds the frame
+     * rather than writing one nothing will read.
+     */
+    readonly duplex: boolean;
+    /**
+     * Opens the transport — establishes the connection and arms any reply reader.
+     *
+     * @remarks
+     * A `start` that REJECTS must first release whatever it had already acquired. The
+     * {@link MCPClientInterface} claims a connection only once `start` resolves, so a rejection
+     * leaves it holding an error and no claim: a socket, session, or reader the transport opened
+     * before failing is reachable by nothing the client can call, and no client-side mechanism can
+     * be added that would reach it.
+     *
+     * @returns Resolves once the transport is ready to `send`
+     */
+    start(): Promise<void>;
+    /**
+     * Sends one JSON-RPC message to the remote server.
+     *
+     * @remarks
+     * Each decoded reply is surfaced on the `emitter`'s `message` event — `send`
+     * itself resolves once the message has been written (and, for a request/response
+     * transport, its synchronous reply emitted), not when a logical response arrives;
+     * the {@link MCPClientInterface} awaits the response through its `id` correlation.
+     *
+     * A `send` that FAILS must fail by REJECTING, never by throwing synchronously. The
+     * {@link MCPClientInterface} registers the write inside the same promise executor that
+     * records the request's pending entry, so a synchronous throw leaves no promise for that
+     * registration to attach to: the entry set one statement earlier is never settled, and a
+     * later abort writes `notifications/cancelled` naming a request the write never delivered.
+     * An `async send` satisfies this by construction, which is why every transport this package
+     * ships declares one; a non-`async` implementation returns a rejected promise instead of
+     * throwing. The client cannot enforce this from its side — the throw and the write are
+     * indistinguishable to it — so it is stated here, on the contract that owns it.
+     *
+     * A transport whose channel confirms the write rejects on its failure. A transport whose
+     * exchange reports through the emitter resolves. A transport whose channel cannot confirm a
+     * write answers a closed channel from its own state, and each states which in its own
+     * remarks.
+     *
+     * @param message - The message to write to the wire
+     * @returns Resolves once the message has been sent, and rejects — never throws — when the
+     * write fails
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+    /**
+     * Closes the transport — ends the connection and releases resources.
+     *
+     * @remarks
+     * A `close` must SETTLE, and its settlements mean different things to its caller: resolving
+     * says the connection ended, rejecting says it did not. The
+     * {@link MCPClientInterface}'s only other bound is a deadline, which reports that the shutdown
+     * did not ANSWER and never that it did not happen — so a `close` that resolves or rejects hours
+     * late still decides the outcome, and one that never settles leaves the connection owed for the
+     * client's life. `close` is never called twice concurrently for one connection: a caller that
+     * gave up waiting JOINS the `close` still running rather than issuing another. It IS called
+     * again after an earlier `close` REJECTED, because a rejected close ended nothing.
+     *
+     * `close` is IDEMPOTENT: a call on a transport an earlier `close` already ended resolves
+     * without emitting `close` again and without releasing anything a second time. Idempotence
+     * bounds ONE closed lifetime rather than the object — a transport that reopens on `start`
+     * arms itself there, and its next `close` ends that connection and emits once for it.
+     *
+     * @returns Resolves once the transport is closed
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Represents the exact finite JSON metadata carried by MCP `_meta` envelopes.
  *
  * @remarks
  * The `Object` suffix is not a role suffix from the type table — it NAMES THE SHAPE.
@@ -3150,7 +3863,7 @@ export declare type MCPLoggingLevel = 'debug' | 'info' | 'notice' | 'warning' |
 export declare type MCPMetaObject = Readonly<Record<string, JSONValue>>;
 
 /**
- * One modern method, registered on the seam that dispatches it.
+ * Represents one modern method, registered on the seam that dispatches it.
  *
  * @remarks
  * A registered method answers a {@link JSONRPCRequest} — with a terminating
@@ -3183,7 +3896,7 @@ export declare type MCPMetaObject = Readonly<Record<string, JSONValue>>;
 export declare type MCPMethodHandler = (request: JSONRPCRequest, options: MCPMethodOptions) => Promise<JSONRPCResponse | MCPStream>;
 
 /**
- * The modern method registry an {@link import('./types.js').MCPServerInterface}
+ * Holds the modern methods an {@link import('./types.js').MCPServerInterface}
  * dispatches through — a name-keyed store of {@link MCPMethodHandler}s that owns its
  * map rather than exposing one.
  *
@@ -3212,8 +3925,8 @@ export declare class MCPMethodManager implements MCPMethodManagerInterface {
 }
 
 /**
- * The modern method registry an {@link MCPServerInterface} dispatches through — the ONE
- * seam carrying both the built-in methods and any method a consumer adds.
+ * Represents the modern method registry an {@link MCPServerInterface} dispatches through —
+ * the ONE seam carrying both the built-in methods and any method a consumer adds.
  *
  * @remarks
  * `server/discover`, `tools/list`, `tools/call`, and `subscriptions/listen` are registered here at construction,
@@ -3241,13 +3954,13 @@ export declare interface MCPMethodManagerInterface {
 }
 
 /**
- * The RESOLVED per-request options one dispatched method receives.
+ * Represents the RESOLVED per-request options one dispatched method receives.
  *
  * @remarks
  * The mirror of {@link MCPDispatchOptions} on the far side of dispatch: a CALLER may
  * have no signal to offer, but a dispatched method always has one to observe, so
  * `signal` is REQUIRED here. Dispatch resolves it once, at the single ingress, and
- * supplies the same value to every handler, elicitation, principal, and subscription
+ * supplies the same value to every handler, input, principal, and subscription
  * producer the request reaches — none of them may reinvent a cancellation source or
  * treat absence as a case.
  *
@@ -3267,15 +3980,15 @@ export declare interface MCPMethodManagerInterface {
 export declare interface MCPMethodOptions {
     /** Aborts when the caller's request ends, or when the answer it produced is finished. */
     readonly signal: AbortSignal;
-    /** Consumer-asserted caller context, forwarded opaquely and never protocol-verified. */
+    /** Carries consumer-asserted caller context, forwarded opaquely and never protocol-verified. */
     readonly caller?: unknown;
 }
 
-/** A modern protocol revision supported by the bare MCP server. */
+/** Names a modern protocol revision supported by the bare MCP server. */
 export declare type MCPModernVersion = '2026-07-28';
 
 /**
- * Open notification metadata with the dated reserved subscription field.
+ * Carries open notification metadata with the dated reserved subscription field.
  *
  * @remarks
  * The subscription id is OPTIONAL here, and that is the schema's own split rather than
@@ -3288,19 +4001,21 @@ export declare type MCPModernVersion = '2026-07-28';
  * sits on the terminating result of a stream, so a subscription always exists to name.
  */
 export declare type MCPNotificationMetaObject = MCPMetaObject & {
-    /** The JSON-RPC id of the `subscriptions/listen` request whose stream delivered the frame. */
+    /**
+     * Holds the JSON-RPC id of the `subscriptions/listen` request whose stream delivered the frame.
+     */
     readonly 'io.modelcontextprotocol/subscriptionId'?: JSONRPCId;
 };
 
-/** Shared cursor parameters for every paginated modern list method. */
+/** Represents the cursor parameters shared by every paginated modern list method. */
 export declare interface MCPPaginationParams {
-    /** Opaque cursor returned by the preceding page. */
+    /** Holds the opaque cursor returned by the preceding page. */
     readonly cursor?: string;
 }
 
-/** Shared cursor result fields for every paginated modern list method. */
+/** Represents the cursor result fields shared by every paginated modern list method. */
 export declare interface MCPPaginationResult {
-    /** Opaque cursor for the following page; absent when this is the final page. */
+    /** Holds the opaque cursor for the following page; absent when this is the final page. */
     readonly nextCursor?: string;
 }
 
@@ -3313,7 +4028,7 @@ export declare interface MCPPaginationResult {
  */
 export declare type MCPPrincipalHandler = (request: JSONRPCRequest, options: MCPMethodOptions) => string | Promise<string>;
 
-/** One official request-scoped progress payload. */
+/** Represents one official request-scoped progress payload. */
 export declare interface MCPProgress {
     readonly progress: number;
     readonly total?: number;
@@ -3338,14 +4053,43 @@ export declare interface MCPProgress {
  */
 export declare type MCPProgressHandler = (progress: MCPProgress) => void;
 
-/** Backpressured request-scoped progress reporter supplied to an explicit executor. */
+/**
+ * Reports request-scoped progress under backpressure — the reporter supplied to an explicit
+ * executor.
+ */
 export declare interface MCPProgressInterface {
     /** Reports one finite, strictly increasing progress value and awaits its consumption. */
     report(progress: MCPProgress): Promise<void>;
 }
 
 /**
- * A bounded, request-scoped progress handoff between one producer and one serial consumer.
+ * Represents the OWNING half of one progress slot — {@link MCPProgressInterface} plus the
+ * consuming and stopping the slot's owner performs.
+ *
+ * @remarks
+ * Two interfaces over one entity because two parties hold it and they are owed different
+ * powers. An executor receives the narrow {@link MCPProgressInterface} through
+ * {@link MCPExecutionContext} and can publish and nothing else; the MCP-owned response stream
+ * that created the slot holds this one and also drains it and shuts it down. Naming the owner's
+ * half is what keeps `take` and `stop` documented as contract rather than as extra surface a
+ * class happens to expose.
+ *
+ * @example
+ * ```ts
+ * const owner: MCPProgressOwnerInterface = new MCPProgressReporter(id, limits, signal)
+ * const notification = await owner.take()
+ * owner.stop()
+ * ```
+ */
+export declare interface MCPProgressOwnerInterface extends MCPProgressInterface {
+    /** Takes the next progress notification, waiting for the single producer slot when empty. */
+    take(): Promise<JSONRPCNotification>;
+    /** Stops the reporter permanently, rejects pending work, and detaches its abort listener. */
+    stop(): void;
+}
+
+/**
+ * Hands bounded, request-scoped progress from one producer to one serial consumer.
  *
  * The reporter holds at most one owned progress item. {@link report} applies backpressure until
  * {@link take} consumes that slot. It has no replay, queue, concurrent-consumer coordination,
@@ -3367,7 +4111,7 @@ export declare interface MCPProgressInterface {
  * reporter.stop()
  * ```
  */
-export declare class MCPProgressReporter implements MCPProgressInterface {
+export declare class MCPProgressReporter implements MCPProgressOwnerInterface {
     #private;
     /**
      * Creates one non-durable progress slot for an active request.
@@ -3403,7 +4147,7 @@ export declare class MCPProgressReporter implements MCPProgressInterface {
     stop(): void;
 }
 
-/** One prompt descriptor advertised by `prompts/list`. */
+/** Represents one prompt descriptor advertised by `prompts/list`. */
 export declare interface MCPPrompt {
     readonly name: string;
     readonly title?: string;
@@ -3413,7 +4157,7 @@ export declare interface MCPPrompt {
     readonly _meta?: MCPMetaObject;
 }
 
-/** One argument descriptor advertised with an MCP prompt. */
+/** Represents one argument descriptor advertised with an MCP prompt. */
 export declare interface MCPPromptArgument {
     readonly name: string;
     readonly title?: string;
@@ -3429,7 +4173,7 @@ export declare interface MCPPromptGetParams {
     readonly requestState?: string;
 }
 
-/** The complete, non-cacheable `prompts/get` result. */
+/** Represents the complete, non-cacheable `prompts/get` result. */
 export declare interface MCPPromptGetResult {
     readonly resultType: 'complete';
     readonly description?: string;
@@ -3437,7 +4181,7 @@ export declare interface MCPPromptGetResult {
     readonly _meta?: MCPResultMetaObject;
 }
 
-/** The complete cacheable `prompts/list` result. */
+/** Represents the complete cacheable `prompts/list` result. */
 export declare type MCPPromptListResult = MCPPromptPage & {
     readonly resultType: 'complete';
     readonly ttlMs: number;
@@ -3446,7 +4190,7 @@ export declare type MCPPromptListResult = MCPPromptPage & {
 };
 
 /**
- * Consumer-supplied prompt registry port.
+ * Represents the consumer-supplied prompt registry port.
  *
  * @remarks
  * MCP owns no prompt storage. The host projects one shared-cursor page at a time and resolves
@@ -3471,25 +4215,25 @@ export declare interface MCPPromptManagerInterface {
     prompt(params: MCPPromptGetParams, options: MCPMethodOptions): MCPPromptGetResult | MCPInputResult | undefined | Promise<MCPPromptGetResult | MCPInputResult | undefined>;
 }
 
-/** One user or assistant message returned by `prompts/get`. */
+/** Represents one user or assistant message returned by `prompts/get`. */
 export declare interface MCPPromptMessage {
     readonly role: 'user' | 'assistant';
     readonly content: MCPContent;
 }
 
-/** One consumer-owned page projected by `prompts/list`. */
+/** Represents one consumer-owned page projected by `prompts/list`. */
 export declare interface MCPPromptPage extends MCPPaginationResult {
     readonly prompts: readonly MCPPrompt[];
 }
 
-/** A completion reference to one named prompt. */
+/** Represents a completion reference to one named prompt. */
 export declare interface MCPPromptReference {
     readonly type: 'ref/prompt';
     readonly name: string;
 }
 
 /**
- * The validated per-request context projected from a modern request's reserved
+ * Represents the validated per-request context projected from a modern request's reserved
  * `_meta` keys.
  *
  * @remarks
@@ -3526,7 +4270,7 @@ export declare interface MCPRequestContext {
  */
 export declare type MCPRequestFunction = (method: string, params: Readonly<Record<string, unknown>> | undefined, deadline: number | undefined) => Promise<unknown>;
 
-/** One resource descriptor advertised by `resources/list`. */
+/** Represents one resource descriptor advertised by `resources/list`. */
 export declare interface MCPResource {
     readonly uri: string;
     readonly name: string;
@@ -3540,7 +4284,7 @@ export declare interface MCPResource {
 }
 
 /**
- * Resource contents returned by `resources/read`.
+ * Represents the resource contents returned by `resources/read`.
  *
  * @remarks
  * The wire has no tag field. Presence of `text` or `blob` is the structural
@@ -3552,7 +4296,7 @@ export declare type MCPResourceContents = (MCPTextResource & {
     readonly text?: never;
 });
 
-/** A link to an MCP resource, including its exact dated-schema metadata. */
+/** Represents a link to an MCP resource, including its exact dated-schema metadata. */
 export declare interface MCPResourceLink {
     readonly type: 'resource_link';
     readonly name: string;
@@ -3566,7 +4310,7 @@ export declare interface MCPResourceLink {
     readonly _meta?: MCPMetaObject;
 }
 
-/** The complete cacheable `resources/list` result. */
+/** Represents the complete cacheable `resources/list` result. */
 export declare type MCPResourceListResult = MCPResourcePage & {
     readonly resultType: 'complete';
     readonly ttlMs: number;
@@ -3575,7 +4319,7 @@ export declare type MCPResourceListResult = MCPResourcePage & {
 };
 
 /**
- * Consumer-supplied resource registry port.
+ * Represents the consumer-supplied resource registry port.
  *
  * @remarks
  * MCP owns no storage. The host may back this port with memory, a workspace, a database,
@@ -3614,7 +4358,7 @@ export declare interface MCPResourceManagerInterface {
     templates(pagination: MCPPaginationParams, options: MCPMethodOptions): MCPResourceTemplatePage | Promise<MCPResourceTemplatePage>;
 }
 
-/** One consumer-owned page projected by `resources/list`. */
+/** Represents one consumer-owned page projected by `resources/list`. */
 export declare interface MCPResourcePage extends MCPPaginationResult {
     readonly resources: readonly MCPResource[];
 }
@@ -3626,7 +4370,7 @@ export declare interface MCPResourceReadParams {
     readonly requestState?: string;
 }
 
-/** The complete cacheable `resources/read` result. */
+/** Represents the complete cacheable `resources/read` result. */
 export declare type MCPResourceReadResult = {
     readonly contents: readonly MCPResourceContents[];
     readonly resultType: 'complete';
@@ -3635,7 +4379,7 @@ export declare type MCPResourceReadResult = {
     readonly _meta?: MCPResultMetaObject;
 };
 
-/** One RFC 6570 resource-template descriptor advertised by `resources/templates/list`. */
+/** Represents one RFC 6570 resource-template descriptor advertised by `resources/templates/list`. */
 export declare interface MCPResourceTemplate {
     readonly uriTemplate: string;
     readonly name: string;
@@ -3647,7 +4391,7 @@ export declare interface MCPResourceTemplate {
     readonly _meta?: MCPMetaObject;
 }
 
-/** The complete cacheable `resources/templates/list` result. */
+/** Represents the complete cacheable `resources/templates/list` result. */
 export declare type MCPResourceTemplateListResult = MCPResourceTemplatePage & {
     readonly resultType: 'complete';
     readonly ttlMs: number;
@@ -3655,19 +4399,19 @@ export declare type MCPResourceTemplateListResult = MCPResourceTemplatePage & {
     readonly _meta?: MCPResultMetaObject;
 };
 
-/** One consumer-owned page projected by `resources/templates/list`. */
+/** Represents one consumer-owned page projected by `resources/templates/list`. */
 export declare interface MCPResourceTemplatePage extends MCPPaginationResult {
     readonly resourceTemplates: readonly MCPResourceTemplate[];
 }
 
-/** A completion reference to one resource-template URI descriptor. */
+/** Represents a completion reference to one resource-template URI descriptor. */
 export declare interface MCPResourceTemplateReference {
     readonly type: 'ref/resource';
     readonly uri: string;
 }
 
 /**
- * One modern MCP result — the open contract every dated-revision result satisfies.
+ * Represents one modern MCP result — the open contract every dated-revision result satisfies.
  *
  * @remarks
  * The dated schema requires a `resultType` on EVERY modern result and leaves the
@@ -3685,24 +4429,69 @@ export declare interface MCPResourceTemplateReference {
  * answer any registered method through, and nowhere else.
  */
 export declare interface MCPResult {
-    /** The result's protocol discriminator (`'complete'`, `'input_required'`, or a later value). */
+    /**
+     * Names the result's protocol discriminator (`'complete'`, `'input_required'`, or a later value).
+     */
     readonly resultType: string;
-    /** Open modern protocol metadata, including reserved namespaced keys. */
+    /** Carries open modern protocol metadata, including reserved namespaced keys. */
     readonly _meta?: MCPResultMetaObject;
     readonly [key: string]: unknown;
 }
 
-/** Open result metadata with the dated reserved server identity field. */
+/** Carries open result metadata with the dated reserved server identity field. */
 export declare type MCPResultMetaObject = MCPMetaObject & {
     readonly 'io.modelcontextprotocol/serverInfo'?: MCPIdentity;
 };
 
-/** The intended recipient of annotated MCP content. */
+/** Names the intended recipient of annotated MCP content. */
 export declare type MCPRole = 'user' | 'assistant';
 
+/** Represents one filesystem root a client exposes to a server. */
+export declare interface MCPRoot {
+    readonly uri: string;
+    readonly name?: string;
+    readonly _meta?: MCPMetaObject;
+}
+
+/** Represents the client's answer to one embedded `roots/list` request. */
+export declare interface MCPRootResult {
+    readonly roots: readonly MCPRoot[];
+    readonly _meta?: MCPMetaObject;
+}
+
+/**
+ * Represents one block a sampling completion may carry.
+ *
+ * @remarks
+ * The dated schema's `SamplingMessageContentBlock`: the text, image, and audio blocks
+ * {@link MCPContent} also admits, plus the two tool blocks a tool-using model produces. The
+ * resource arms of {@link MCPContent} are deliberately absent — the schema leaves them out of
+ * a sampling completion.
+ */
+export declare type MCPSampleContent = MCPTextContent | MCPImageContent | MCPAudioContent | MCPToolUseContent | MCPToolResultContent;
+
+/**
+ * Represents the client's answer to one embedded `sampling/createMessage` request.
+ *
+ * @remarks
+ * `content` is the dated schema's own `anyOf`: one {@link MCPSampleContent} block, or an array
+ * of them. A tool-using model answers with `tool_use` and `tool_result` blocks, and a model
+ * answering in several parts answers with the array, so narrowing this to a single text, image,
+ * or audio block would refuse completions the schema permits. `stopReason` is an open string
+ * because the schema names `endTurn`, `stopSequence`, `maxTokens`, and `toolUse` while
+ * permitting any other value a provider reports.
+ */
+export declare interface MCPSampleResult {
+    readonly role: 'user' | 'assistant';
+    readonly content: MCPSampleContent | readonly MCPSampleContent[];
+    readonly model: string;
+    readonly stopReason?: string;
+    readonly _meta?: MCPMetaObject;
+}
+
 /**
- * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
- * requests over a live {@link ToolManagerInterface}, with NO transport coupling.
+ * Dispatches JSON-RPC 2.0 requests over a live {@link ToolManagerInterface}, with NO
+ * transport coupling.
  *
  * @remarks
  * - **`dispatch` and `handle`.** `dispatch(invocation)` runs an already-parsed invocation and
@@ -3748,7 +4537,7 @@ export declare class MCPServer implements MCPServerInterface {
     handle(message: string, options?: MCPDispatchOptions): Promise<string | MCPTextStreamControllerInterface | undefined>;
 }
 
-/** The open dated server-capability declaration returned by discovery. */
+/** Represents the open dated server-capability declaration returned by discovery. */
 export declare type MCPServerCapabilities = Readonly<Record<string, MCPMetaObject>> & {
     readonly experimental?: Readonly<Record<string, MCPMetaObject>>;
     readonly logging?: MCPMetaObject;
@@ -3767,7 +4556,7 @@ export declare type MCPServerCapabilities = Readonly<Record<string, MCPMetaObjec
 };
 
 /**
- * The push observation surface of an {@link MCPServerInterface} — the
+ * Represents the push observation surface of an {@link MCPServerInterface} — the
  * dispatch moments a fire-and-forget observer (logging, tracing) subscribes to
  * through `server.emitter.on`.
  *
@@ -3781,7 +4570,7 @@ export declare type MCPServerCapabilities = Readonly<Record<string, MCPMetaObjec
  */
 export declare type MCPServerEventMap = {
     /**
-     * An invocation is being dispatched — its method, correlating id (absent for a
+     * Reports that an invocation is being dispatched — its method, correlating id (absent for a
      * notification), and structural wire era.
      *
      * @remarks
@@ -3791,10 +4580,20 @@ export declare type MCPServerEventMap = {
      * inbound traffic. Only SCALARS are reported: nothing read out of the request graph
      * escapes here, so a listener can never observe a value the ownership seam has not yet
      * bounded.
+     *
+     * Not every reported invocation arrived from a peer. A modern `tools/call` reaching the
+     * HTTP POST handler (`createMCPPostHandler`) reports the SYNTHETIC `tools/list` that
+     * handler dispatches to read the called tool's `x-mcp-header` annotations, ahead of the
+     * call itself. Each carries the RESERVED id `0`, and one fires per page the handler
+     * walks, up to {@link MCP_LOOKUP_PAGES}. So an observer accounting for inbound traffic
+     * subtracts a `('tools/list', 0, 'modern')` that precedes a `tools/call`, and one
+     * tracing the server's own work keeps it. The id is reserved by convention rather than
+     * enforced: a peer sending its own `tools/list` under id `0` is not told apart here.
      */
     readonly request: readonly [method: string, id: JSONRPCId | undefined, era: MCPEra];
     /**
-     * An operational fault the server CONTAINED — the caught value, exactly once per fault.
+     * Reports an operational fault the server CONTAINED — the caught value, exactly once per
+     * fault.
      *
      * @remarks
      * Every fault this server answers with an internal-error response reports here first: a
@@ -3815,8 +4614,7 @@ export declare type MCPServerEventMap = {
 };
 
 /**
- * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
- * modern requests over a live
+ * Dispatches JSON-RPC 2.0 modern requests over a live
  * {@link ToolManagerInterface}, with NO transport coupling (a transport layer
  * pumps strings through `handle`).
  *
@@ -3845,10 +4643,10 @@ export declare type MCPServerEventMap = {
  */
 export declare interface MCPServerInterface extends MCPDispatcherInterface {
     readonly identity: MCPIdentity;
-    /** The modern method registry this server dispatches through (built-ins included). */
+    /** Holds the modern method registry this server dispatches through (built-ins included). */
     readonly methods: MCPMethodManagerInterface;
     /**
-     * The bounds this server actually enforces — every leaf resolved, none optional.
+     * Holds the bounds this server actually enforces — every leaf resolved, none optional.
      *
      * @remarks
      * Derived from {@link MCPServerOptions.limit} at construction and stored nowhere else, so
@@ -3951,19 +4749,21 @@ export declare interface MCPServerInterface extends MCPDispatcherInterface {
  */
 export declare interface MCPServerOptions {
     readonly on?: EmitterHooks<MCPServerEventMap>;
-    /** The emitter's listener-error handler — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly identity: MCPIdentity;
-    /** The live tool registry the server exposes over `tools/list` / `tools/call`. */
+    /** Holds the live tool registry the server exposes over `tools/list` / `tools/call`. */
     readonly tools: ToolManagerInterface;
-    /** Optional consumer-owned resource registry exposed over the modern resource methods. */
+    /**
+     * Holds the optional consumer-owned resource registry exposed over the modern resource methods.
+     */
     readonly resources?: MCPResourceManagerInterface;
-    /** Optional consumer-owned prompt registry exposed over the modern prompt methods. */
+    /** Holds the optional consumer-owned prompt registry exposed over the modern prompt methods. */
     readonly prompts?: MCPPromptManagerInterface;
-    /** Optional host-owned prompt and resource-template completion provider. */
-    readonly completion?: MCPCompletionManagerInterface;
+    /** Holds the optional host-owned prompt and resource-template completion provider. */
+    readonly completion?: MCPCompletionInterface;
     /**
-     * Optional explicit execution policy above the canonical live tool registry.
+     * Holds the optional explicit execution policy above the canonical live tool registry.
      *
      * @remarks
      * This is also the ONLY way a tool observes cancellation. The default path calls
@@ -3972,21 +4772,30 @@ export declare interface MCPServerOptions {
      * completion even after the request that asked for it has ended, and abandons the result.
      * An {@link MCPExecutionHandler} receives `signal` on its {@link MCPExecutionContext} and
      * can stop the work itself.
+     *
+     * A handler returning a complete {@link MCPCallResult} is taken at its word: the server
+     * bounds it and re-proves its shape, then sends what the handler composed. Nothing stamps
+     * the `_meta` server identity `buildModernResult` puts on a normalized result, so a handler
+     * whose peer reads that key composes it through `buildModernResult` itself.
      */
     readonly execution?: MCPExecutionHandler;
-    /** Optional human guidance exposed by `server/discover`. */
+    /** Holds the optional human guidance exposed by `server/discover`. */
     readonly instructions?: string;
-    /** Modern cache stamps; omitted values use the protocol-safe defaults. */
+    /** Holds the modern cache stamps; omitted values use the protocol-safe defaults. */
     readonly cache?: {
         readonly ttl?: number;
         readonly scope?: 'public' | 'private';
     };
-    /** Optional multi-round-trip input mechanism; all continuation and expiry policy is consumer-supplied. */
+    /**
+     * Holds the optional multi-round-trip input mechanism; all continuation and expiry policy is
+     * consumer-supplied.
+     */
     readonly input?: MCPInputOptions;
-    /** Optional event-driven producer for the modern `subscriptions/listen` method. */
+    /** Holds the optional event-driven producer for the modern `subscriptions/listen` method. */
     readonly subscription?: MCPSubscriptionOptions;
     /**
-     * Optional Tasks extension; the durable store and the deferral decision are consumer-supplied.
+     * Holds the optional Tasks extension; the durable store and the deferral decision are
+     * consumer-supplied.
      *
      * @remarks
      * Omitting it leaves every existing path untouched — nothing is advertised, no call is
@@ -3994,12 +4803,12 @@ export declare interface MCPServerOptions {
      * snapshot dated 2026-07-28, so the shape this option admits is fixed.
      */
     readonly task?: MCPTaskOptions;
-    /** Hostile-input and live-resource bounds; omitted leaves use secure defaults. */
+    /** Holds the hostile-input and live-resource bounds; omitted leaves use secure defaults. */
     readonly limit?: MCPLimitOptions;
 }
 
 /**
- * A held-open modern result: each `yield` is a {@link JSONRPCNotification}; the
+ * Represents a held-open modern result: each `yield` is a {@link JSONRPCNotification}; the
  * `return` value is the terminating response.
  *
  * @remarks
@@ -4017,7 +4826,8 @@ export declare interface MCPServerOptions {
 export declare type MCPStream = AsyncGenerator<JSONRPCNotification, JSONRPCResponse, unknown>;
 
 /**
- * The one cancellation engine every modern held-open result leaves `MCPServer` through.
+ * Provides the one cancellation engine every modern held-open result leaves `MCPServer`
+ * through.
  *
  * @remarks
  * A native async generator decides cancellation with a QUEUE: `return()` and `throw()` wait
@@ -4123,8 +4933,8 @@ export declare class MCPStreamController implements MCPStreamControllerInterface
 }
 
 /**
- * A held-open modern result whose cancellation ONE owner arbitrates — the arm every
- * stream leaving `MCPServer.dispatch` takes.
+ * Represents a held-open modern result whose cancellation ONE owner arbitrates — the arm
+ * every stream leaving `MCPServer.dispatch` takes.
  *
  * @remarks
  * The generator protocol states what a stream yields and says nothing about who ends one,
@@ -4213,7 +5023,7 @@ export declare interface MCPStreamControllerInterface extends MCPStream {
 }
 
 /**
- * The notification families a client may opt in to on a `subscriptions/listen` stream.
+ * Names the notification families a client may opt in to on a `subscriptions/listen` stream.
  *
  * @remarks
  * Every key here is a WIRE SPELLING, carried verbatim from the dated schema's
@@ -4267,31 +5077,35 @@ export declare interface MCPSubscriptionFilter {
  */
 export declare type MCPSubscriptionHandler = (notifications: MCPSubscriptionFilter, options: MCPMethodOptions) => AsyncIterable<JSONRPCNotification> | Promise<AsyncIterable<JSONRPCNotification>>;
 
-/** Configuration for the server's built-in `subscriptions/listen` method. */
+/** Configures the server's built-in `subscriptions/listen` method. */
 export declare interface MCPSubscriptionOptions {
-    /** The notification filter this server can actually honour. */
+    /** Holds the notification filter this server can actually honour. */
     readonly notifications: MCPSubscriptionFilter;
     /** Opens the producer for one honoured filter. */
-    readonly listen: MCPSubscriptionHandler;
+    readonly producer: MCPSubscriptionHandler;
 }
 
-/** The terminating result returned when a `subscriptions/listen` stream closes gracefully. */
+/**
+ * Represents the terminating result returned when a `subscriptions/listen` stream closes
+ * gracefully.
+ */
 export declare type MCPSubscriptionResult = {
     readonly resultType: 'complete';
     readonly _meta: MCPSubscriptionResultMetaObject;
 };
 
-/** The required metadata on a graceful `subscriptions/listen` result. */
+/** Represents the required metadata on a graceful `subscriptions/listen` result. */
 export declare type MCPSubscriptionResultMetaObject = MCPResultMetaObject & {
-    /** The JSON-RPC id of the `subscriptions/listen` request whose stream is closing. */
+    /** Holds the JSON-RPC id of the `subscriptions/listen` request whose stream is closing. */
     readonly 'io.modelcontextprotocol/subscriptionId': JSONRPCId;
 };
 
-/** A client subscription's owned notifications and graceful terminal result. */
+/** Represents a client subscription's owned notifications and graceful terminal result. */
 export declare type MCPSubscriptionStream = AsyncGenerator<JSONRPCNotification, MCPSubscriptionResult, unknown>;
 
 /**
- * One durable task's wire snapshot — the payload a deferred `tools/call` answers with.
+ * Represents one durable task's wire snapshot — the payload a deferred `tools/call` answers
+ * with.
  *
  * @remarks
  * Every field name here is a WIRE SPELLING carried verbatim from the extension's
@@ -4304,22 +5118,22 @@ export declare type MCPSubscriptionStream = AsyncGenerator<JSONRPCNotification,
  * again; a manager that pushes notifications instead simply omits it.
  */
 export declare type MCPTask = {
-    /** The durable handle a later `tasks/get` / `tasks/update` / `tasks/cancel` names. */
+    /** Holds the durable handle a later `tasks/get` / `tasks/update` / `tasks/cancel` names. */
     readonly taskId: string;
     readonly status: MCPTaskStatus;
-    /** Optional human-readable detail about the current status. */
+    /** Carries optional human-readable detail about the current status. */
     readonly statusMessage?: string;
     readonly createdAt: string;
     readonly lastUpdatedAt: string;
-    /** Remaining lifetime in milliseconds, or `null` when the task does not expire. */
+    /** Reports the remaining lifetime in milliseconds, or `null` when the task does not expire. */
     readonly ttlMs: number | null;
-    /** Suggested milliseconds between polls; absent when the manager suggests none. */
+    /** Suggests the milliseconds between polls; absent when the manager suggests none. */
     readonly pollIntervalMs?: number;
 };
 
 /**
- * The CLIENT half of the stable Tasks extension — the `tasks/*` methods over one
- * correlated-request door, exposed as an {@link import('./types.js').MCPClientInterface}'s
+ * Issues the `tasks/*` methods over one correlated-request door — the CLIENT half of the
+ * stable Tasks extension, exposed as an {@link import('./types.js').MCPClientInterface}'s
  * `tasks`.
  *
  * @remarks
@@ -4362,8 +5176,8 @@ export declare class MCPTaskClient implements MCPTaskClientInterface {
 }
 
 /**
- * The CLIENT half of the stable Tasks extension — reading, answering, and stopping a durable
- * task the peer created.
+ * Reads, answers, and stops a durable task the peer created — the CLIENT half of the stable
+ * Tasks extension.
  *
  * @remarks
  * The mirror of {@link MCPTaskManagerInterface} minus `start`, because creating a task is
@@ -4464,7 +5278,7 @@ export declare interface MCPTaskClientInterface {
 }
 
 /**
- * Construction options for an {@link MCPTaskClientInterface}.
+ * Represents the construction options for an {@link MCPTaskClientInterface}.
  *
  * @remarks
  * `request` is the correlated-request door (see {@link MCPRequestFunction}); an
@@ -4473,14 +5287,14 @@ export declare interface MCPTaskClientInterface {
  * to its own calls, stated here because this client does not read the other one's options.
  */
 export declare interface MCPTaskClientOptions {
-    /** The correlated-request door every task request is issued through. */
+    /** Holds the correlated-request door every task request is issued through. */
     readonly request: MCPRequestFunction;
-    /** The deadline each task request carries; omitted waits on the peer indefinitely. */
+    /** Sets the deadline each task request carries; omitted waits on the peer indefinitely. */
     readonly timeout?: number;
 }
 
 /**
- * The call-in-hand context supplied to an {@link MCPTaskHandler} and to
+ * Represents the call-in-hand context supplied to an {@link MCPTaskHandler} and to
  * {@link MCPTaskManagerInterface.start}.
  *
  * @remarks
@@ -4505,8 +5319,8 @@ export declare interface MCPTaskContext {
 }
 
 /**
- * One task snapshot together with whatever its status carries — the shape `tasks/get`
- * and a task notification report.
+ * Represents one task snapshot together with whatever its status carries — the shape
+ * `tasks/get` and a task notification report.
  *
  * @remarks
  * The union is the schema's own: `input_required` carries the requests to answer,
@@ -4536,7 +5350,7 @@ export declare type MCPTaskDetail = (MCPTask & {
 });
 
 /**
- * The wire answer to `tasks/get` — one snapshot under the completed-result stamp.
+ * Represents the wire answer to `tasks/get` — one snapshot under the completed-result stamp.
  *
  * @remarks
  * DISTINCT from {@link MCPTaskDetail}, and the distinction is the whole point. A detail is
@@ -4552,7 +5366,7 @@ export declare type MCPTaskDetail = (MCPTask & {
  */
 export declare type MCPTaskDetailResult = MCPTaskDetail & {
     readonly resultType: 'complete';
-    /** Open modern protocol metadata, including reserved namespaced keys. */
+    /** Carries open modern protocol metadata, including reserved namespaced keys. */
     readonly _meta?: MCPResultMetaObject;
 };
 
@@ -4584,8 +5398,8 @@ export declare type MCPTaskDetailResult = MCPTaskDetail & {
 export declare type MCPTaskHandler = (context: MCPTaskContext, options: MCPMethodOptions) => string | undefined | Promise<string | undefined>;
 
 /**
- * The consumer-owned durable store behind the Tasks extension — the port this package
- * creates tasks through and reads them back from.
+ * Represents the consumer-owned durable store behind the Tasks extension — the port this
+ * package creates tasks through and reads them back from.
  *
  * @remarks
  * There is deliberately NO plural accessor. The extension defines no `tasks/list`, and
@@ -4604,7 +5418,7 @@ export declare type MCPTaskHandler = (context: MCPTaskContext, options: MCPMetho
  */
 export declare interface MCPTaskManagerInterface {
     /**
-     * Creates — or return the existing — durable task for one stable operation key.
+     * Creates — or returns the existing — durable task for one stable operation key.
      *
      * @remarks
      * The obligations this package cannot enforce, and one consequence that is easy
@@ -4656,7 +5470,7 @@ export declare interface MCPTaskManagerInterface {
      * VERBATIM — it holds none of the task's keys, so the ignoring is this method's to do.
      *
      * This is the SECOND multi-round-trip mechanism in the package, and it is the weaker one.
-     * The elicitation path binds each round with a sealed `requestState`, an argument digest,
+     * The built-in input path binds each round with a sealed `requestState`, an argument digest,
      * an absolute expiry, and the resolved principal; this path has none of them, because MCP
      * neither issued the question nor owns the channel it is answered on. Anything equivalent
      * has to live here: bind each published key to the principal that may answer it, expire
@@ -4682,8 +5496,22 @@ export declare interface MCPTaskManagerInterface {
 }
 
 /**
- * The parameters of a `notifications/tasks` frame — one snapshot, flat, optionally stamped
- * with the subscription that delivered it.
+ * Represents one well-formed `notifications/tasks` frame — the notification
+ * {@link import('./validators.js').isMCPTaskNotification} admits.
+ *
+ * @remarks
+ * The name of what that guard proves. A consumer reading `notification.params.taskId` off an
+ * admitted frame narrows to this type, so the narrowing has a name it can annotate, pass, and
+ * return rather than an anonymous intersection re-spelled at each site.
+ */
+export declare type MCPTaskNotification = JSONRPCNotification & {
+    readonly method: 'notifications/tasks';
+    readonly params: MCPTaskNotificationParams;
+};
+
+/**
+ * Represents the parameters of a `notifications/tasks` frame — one snapshot, flat, optionally
+ * stamped with the subscription that delivered it.
  *
  * @remarks
  * FLAT, and that is the schema's shape rather than a choice: the extension types these
@@ -4697,13 +5525,13 @@ export declare interface MCPTaskManagerInterface {
  * {@link MCPNotificationMetaObject}.
  */
 export declare type MCPTaskNotificationParams = MCPTaskDetail & {
-    /** Open notification metadata, including the reserved subscription stamp. */
+    /** Carries open notification metadata, including the reserved subscription stamp. */
     readonly _meta?: MCPNotificationMetaObject;
     readonly [key: string]: unknown;
 };
 
 /**
- * Consumer policy for the server's stable Tasks extension.
+ * Configures the consumer policy for the server's stable Tasks extension.
  *
  * @remarks
  * Supplying this is what turns the extension on: an unconfigured server advertises
@@ -4711,14 +5539,14 @@ export declare type MCPTaskNotificationParams = MCPTaskDetail & {
  * reply from a server that does not implement an optional extension.
  */
 export declare interface MCPTaskOptions {
-    /** The durable store the server creates tasks in and reads them back from. */
+    /** Holds the durable store the server creates tasks in and reads them back from. */
     readonly tasks: MCPTaskManagerInterface;
     /** Decides whether the call in hand is deferred, and under which stable key. */
-    readonly defer: MCPTaskHandler;
+    readonly deferral: MCPTaskHandler;
 }
 
 /**
- * The modern `tools/call` result announcing that the call became a durable task.
+ * Represents the modern `tools/call` result announcing that the call became a durable task.
  *
  * @remarks
  * The only result in this package whose `resultType` is `'task'`. It is FLAT — the
@@ -4728,12 +5556,12 @@ export declare interface MCPTaskOptions {
  */
 export declare type MCPTaskResult = MCPTask & {
     readonly resultType: 'task';
-    /** Open modern protocol metadata, including reserved namespaced keys. */
+    /** Carries open modern protocol metadata, including reserved namespaced keys. */
     readonly _meta?: MCPResultMetaObject;
 };
 
 /**
- * The lifecycle state of one durable task.
+ * Names the lifecycle state of one durable task.
  *
  * @remarks
  * `completed`, `failed`, and `cancelled` are TERMINAL: a task that reaches one never
@@ -4750,7 +5578,7 @@ export declare type MCPTaskResult = MCPTask & {
  */
 export declare type MCPTaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
 
-/** A textual MCP content block. */
+/** Represents a textual MCP content block. */
 export declare interface MCPTextContent {
     readonly type: 'text';
     readonly text: string;
@@ -4758,7 +5586,7 @@ export declare interface MCPTextContent {
     readonly _meta?: MCPMetaObject;
 }
 
-/** Embedded textual resource contents. */
+/** Represents embedded textual resource contents. */
 export declare interface MCPTextResource {
     readonly uri: string;
     readonly mimeType?: string;
@@ -4766,11 +5594,11 @@ export declare interface MCPTextResource {
     readonly text: string;
 }
 
-/** The string-boundary mirror of {@link MCPStream} — the same sequence, already serialized. */
+/** Mirrors {@link MCPStream} at the string boundary — the same sequence, already serialized. */
 export declare type MCPTextStream = AsyncGenerator<string, string, unknown>;
 
 /**
- * The string-boundary mirror of a controlled held-open result — the same exchange, already
+ * Mirrors a controlled held-open result at the string boundary — the same exchange, already
  * serialized.
  *
  * @remarks
@@ -4870,7 +5698,7 @@ export declare class MCPTextStreamController implements MCPTextStreamControllerI
 }
 
 /**
- * The string-boundary mirror of {@link MCPStreamControllerInterface} — the same exchange,
+ * Mirrors {@link MCPStreamControllerInterface} at the string boundary — the same exchange,
  * already serialized.
  *
  * @remarks
@@ -4944,7 +5772,7 @@ export declare interface MCPTextStreamControllerInterface extends MCPTextStream
 }
 
 /**
- * One entry of the MCP `tools/list` result — a tool's `name`, optional
+ * Represents one entry of the MCP `tools/list` result — a tool's `name`, optional
  * `description`, and its JSON-Schema `inputSchema`.
  *
  * @remarks
@@ -4958,8 +5786,27 @@ export declare interface MCPToolDescriptor {
     readonly inputSchema: Readonly<Record<string, unknown>>;
 }
 
+/** Represents one tool's outcome returned to the model, carried in a sampling completion. */
+export declare interface MCPToolResultContent {
+    readonly type: 'tool_result';
+    readonly toolUseId: string;
+    readonly content: readonly MCPContent[];
+    readonly isError?: boolean;
+    readonly structuredContent?: JSONValue;
+    readonly _meta?: MCPMetaObject;
+}
+
+/** Represents a model's request to call one tool, carried inside a sampling completion. */
+export declare interface MCPToolUseContent {
+    readonly type: 'tool_use';
+    readonly id: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly _meta?: MCPMetaObject;
+}
+
 /**
- * A duplex message channel an environment face provides to the pure engine — the
+ * Represents a duplex message channel an environment face provides to the pure engine — the
  * one port `bindServer` and `bindClient` (`./helpers.js`) pipe an
  * {@link MCPServerInterface} / {@link MCPClientInterface} over.
  *
@@ -4993,7 +5840,7 @@ export declare interface MCPTransportInterface {
 }
 
 /**
- * A `tools/call` result BEFORE the modern stamp — the executed tool's output as
+ * Represents a `tools/call` result BEFORE the modern stamp — the executed tool's output as
  * `content` blocks, with `isError` flagging a tool failure.
  *
  * @remarks
@@ -5013,15 +5860,15 @@ export declare interface MCPTransportInterface {
  */
 export declare type MCPUnstampedCallResult = {
     readonly content: readonly MCPContent[];
-    /** The successful tool value in its original structure; absent when no value was returned. */
+    /** Holds the successful tool value in its original structure; absent when none was returned. */
     readonly structuredContent?: JSONValue;
-    /** `true` when the tool failed — its error text is in `content`. */
+    /** Flags a failed tool — its error text is in `content`. */
     readonly isError?: boolean;
-    /** Open modern protocol metadata, including reserved namespaced keys. */
+    /** Carries open modern protocol metadata, including reserved namespaced keys. */
     readonly _meta?: MCPResultMetaObject;
 };
 
-/** A protocol revision supported by an MCP package surface. */
+/** Names a protocol revision supported by an MCP package surface. */
 export declare type MCPVersion = MCPModernVersion | MCPLegacyVersion;
 
 /**
@@ -5104,17 +5951,18 @@ export declare function parseJSONRPCMessage(value: unknown, limits?: MCPJSONLimi
  * This parser does not open the opaque continuation carrier; the configured
  * continuation port performs that boundary first. The protected
  * payload binds the authenticated principal, absolute expiry, ORIGINAL request id, version,
- * method, server-assigned key, tool name, argument digest, the exact issued elicitation
- * schema, and optional application state. Every member is required except application state:
- * a payload missing its schema cannot have its accepted response enforced, so it is refused
- * rather than admitted unenforced. Total over malformed or hostile input.
+ * method, the exact round that was issued, tool name, argument digest, and optional
+ * application state. Every member is required except application state: a payload missing its
+ * round cannot have the client's answers enforced, so it is refused rather than admitted
+ * unenforced. An EMPTY round is refused for the same reason — a retry against it would answer
+ * no question at all. Total over malformed or hostile input.
  *
  * @param value - The opened canonical continuation value to parse
  * @returns The protected input state, or `undefined` when malformed
  *
  * @example
  * ```ts
- * parseMCPInputState('{"principal":"user-1","expiry":2000,"id":1,"version":"2026-07-28","method":"tools/call","key":"k","name":"reply","digest":"abc","schema":{"type":"object","properties":{}}}')
+ * parseMCPInputState('{"principal":"user-1","expiry":2000,"id":1,"version":"2026-07-28","method":"tools/call","requests":{"k":{"method":"roots/list"}},"name":"reply","digest":"abc"}')
  * ```
  */
 export declare function parseMCPInputState(value: unknown): MCPInputState | undefined;
@@ -5161,6 +6009,55 @@ export declare function parseRequestContext(value: unknown, limits?: MCPJSONLimi
  */
 export declare function readCancelledId(message: JSONRPCMessage): JSONRPCId | undefined;
 
+/**
+ * Decodes a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
+ * carried — the CLIENT-side inverse of a server's Streamable-HTTP SSE response.
+ *
+ * @remarks
+ * Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({ stream: true
+ * })` (handling a multi-byte character split across reads) and `@orkestrel/sse`'s
+ * {@link SSEParserInterface} (handling a partial line or in-progress event split across
+ * reads), then narrows each dispatched event's `data` to a {@link JSONRPCMessage} through
+ * {@link decodeEvent} (so a non-message or non-JSON `data:` event is DROPPED, never thrown —
+ * total). It reuses the SAME `SSEParser` a server's `createStream` seam serializes against, so
+ * the wire round-trips. A `null` body (no stream) yields no messages;
+ * {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport} reads a
+ * request/response SSE reply (the server sends one `data:` event then ends), so this drains to
+ * completion.
+ *
+ * @param response - The SSE `fetch` Response to decode (its `body` is read to completion)
+ * @returns Every {@link JSONRPCMessage} the stream carried, in order
+ *
+ * @example
+ * ```ts
+ * const messages = await readEventStream(await fetch(url, { method: 'POST', body }))
+ * ```
+ */
+export declare function readEventStream(response: Response): Promise<readonly JSONRPCMessage[]>;
+
+/**
+ * Renders one projected argument as the text its `Mcp-Param-*` header carries.
+ *
+ * @remarks
+ * The protocol's conversion table, and the ONE place it is stated: a string travels as
+ * itself, an integer in decimal, and a boolean as lowercase `true` or `false`. The value's
+ * runtime shape must match the leaf's declared type, so a schema that declares `integer` and
+ * an argument that supplies a string, a fraction, or a magnitude outside the IEEE 754 safe
+ * range carries NOTHING — a header that cannot round-trip the body value is worse than an
+ * absent one, and the tool's own argument validation owns the disagreement.
+ *
+ * @param value - The argument value read at the parameter's path
+ * @param primitive - The leaf's declared type
+ * @returns The header text, or `undefined` when the value cannot travel as that type
+ *
+ * @example
+ * ```ts
+ * renderHeaderValue(42, 'integer') // '42'
+ * renderHeaderValue(false, 'boolean') // 'false'
+ * ```
+ */
+export declare function renderHeaderValue(value: unknown, primitive: MCPHeaderPrimitive): string | undefined;
+
 /**
  * Pumps a controlled serialized exchange onto a transport — every notification in order, then
  * the terminating response — and END the exchange however the pump leaves.
@@ -5264,14 +6161,17 @@ export declare function snapshotToolResult(value: unknown, limits: MCPJSONLimitO
  */
 export declare function stampSubscriptionNotification(notification: JSONRPCNotification, id: JSONRPCId): JSONRPCNotification;
 
-/** The protocol revisions accepted by the optional legacy decorator. */
+/** Lists the protocol revisions accepted by the optional legacy decorator. */
 export declare const SUPPORTED_LEGACY_PROTOCOL_VERSIONS: readonly MCPLegacyVersion[];
 
-/** The protocol revisions the `isMCPVersion` guard admits, spanning the modern and legacy eras. */
+/**
+ * Lists the protocol revisions the `isMCPVersion` guard admits, spanning the modern and legacy
+ * eras.
+ */
 export declare const SUPPORTED_MCP_VERSIONS: readonly MCPVersion[];
 
 /**
- * The modern MCP protocol revisions a bare server accepts and advertises.
+ * Lists the modern MCP protocol revisions a bare server accepts and advertises.
  *
  * @remarks
  * Frozen in discovery-advertisement order. Legacy revisions are absent because
@@ -5280,4 +6180,51 @@ export declare const SUPPORTED_MCP_VERSIONS: readonly MCPVersion[];
  */
 export declare const SUPPORTED_MODERN_PROTOCOL_VERSIONS: readonly MCPModernVersion[];
 
+/**
+ * Determines whether a client capability record declares form-mode elicitation.
+ *
+ * @remarks
+ * The protocol's empty `elicitation` object is the implicit form-only declaration.
+ * A non-empty declaration must carry a record-valued `form` member; URL-only support
+ * does not authorize a form request. Total over hostile input.
+ *
+ * @param value - The client capability record to inspect
+ * @returns True if form-mode elicitation is declared; false otherwise
+ *
+ * @example
+ * ```ts
+ * supportsFormElicitation({ elicitation: {} }) // true — implicit form mode
+ * supportsFormElicitation({ elicitation: { url: {} } }) // false
+ * ```
+ */
+export declare function supportsFormElicitation(value: unknown): boolean;
+
+/**
+ * Determines whether a client capability record declares the stable Tasks extension.
+ *
+ * @remarks
+ * The declaration lives at `extensions['io.modelcontextprotocol/tasks']` and the schema
+ * types its value EXACTLY EMPTY — `Record<string, never>`, an object with no additional
+ * properties. So the key's presence is the whole declaration, and the value carries the
+ * whole of the check: a `true` or a string there is a client speaking a different protocol
+ * rather than a shorthand, and a member inside the object is a client declaring an option
+ * this extension does not define. Both are refused, because a server that accepted either
+ * would be reading a shape no peer can produce from the snapshot's own schema.
+ *
+ * A client declares this PER REQUEST. Nothing here consults a session, because the modern
+ * revision is stateless and a capability declared once at connect time says nothing about
+ * the request in hand. Total over hostile input.
+ *
+ * @param value - The client capability record to inspect
+ * @returns True if the tasks extension is declared as the schema's empty object; false otherwise
+ *
+ * @example
+ * ```ts
+ * supportsTask({ extensions: { 'io.modelcontextprotocol/tasks': {} } }) // true
+ * supportsTask({ extensions: {} }) // false — the key is the declaration
+ * supportsTask({ extensions: { 'io.modelcontextprotocol/tasks': { on: true } } }) // false
+ * ```
+ */
+export declare function supportsTask(value: unknown): boolean;
+
 export { }