@orkestrel/mcp 0.0.26 → 0.0.27

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

@@ -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 should have carried. 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.
@@ -358,6 +412,65 @@ 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 isFormElicitationSupported} 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
@@ -525,6 +638,55 @@ export declare function createMCPServer(options: MCPServerOptions): MCPServerInt
  */
 export declare function decodeBoundedMessage(message: string, limits: MCPJSONLimitOptions): 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;
+
 /**
  * Default modern result freshness lifetime in milliseconds.
  *
@@ -547,10 +709,11 @@ export declare const DEFAULT_MCP_CLIENT_VERSION = "1.0.0";
  * 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;
@@ -596,6 +759,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 +817,56 @@ 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;
+
 /**
  * Infers the wire era for an MCP protocol revision.
  *
@@ -758,6 +1009,27 @@ 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 value is one RFC 9110 field token.
+ *
+ * @remarks
+ * 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 unknown value to inspect
+ * @returns Whether the value is a non-empty RFC 9110 token
+ *
+ * @example
+ * ```ts
+ * isFieldToken('Region') // true
+ * isFieldToken('My Region') // false
+ * ```
+ */
+export declare function isFieldToken(value: unknown): value is string;
+
 /**
  * Determines whether a client capability record declares form-mode elicitation.
  *
@@ -1144,6 +1416,25 @@ 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 Whether the value is one of `'string'`, `'integer'`, or `'boolean'`
+ *
+ * @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.
  *
@@ -1159,7 +1450,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` for an embedded elicitation, sampling, or roots request
  *
  * @example
  * ```ts
@@ -1169,7 +1460,7 @@ 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}
@@ -1181,6 +1472,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` when the answer is legal for that request
+ *
+ * @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.
  *
@@ -1391,6 +1706,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` when `value` carries an absolute `uri` and an optional string `name`
+ *
+ * @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` when `value` carries an array of valid roots
+ *
+ * @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` when `value` is one legal sampling content block
+ *
+ * @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` when `value` has the sampling-completion shape
+ *
+ * @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;
 
@@ -1903,9 +2307,36 @@ export declare const MCP_FALLBACK_VERSION: MCPLegacyVersion;
  */
 export declare const MCP_HANDSHAKE_VERSION: MCPLegacyVersion;
 
+/**
+ * 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";
+
 /** MCP reserved error: required HTTP metadata does not match the request body. */
 export declare const MCP_HEADER_MISMATCH = -32020;
 
+/**
+ * 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;
+
 /** Reserved modern `_meta` key carrying the client's open capability record. */
 export declare const MCP_META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
 
@@ -1939,6 +2370,31 @@ export declare const MCP_MISSING_CAPABILITY = -32021;
 /** The modern revision offered by an unpinned client during discovery. */
 export declare const MCP_MODERN_VERSION: MCPModernVersion;
 
+/**
+ * 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-";
+
+/**
+ * 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?";
+
+/** The closing marker of the Base64 sentinel a standard MCP header value travels in. */
+export declare const MCP_SENTINEL_SUFFIX = "?=";
+
 /** MCP reserved error: a request names an unsupported protocol revision. */
 export declare const MCP_UNSUPPORTED_VERSION = -32022;
 
@@ -1980,10 +2436,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,9 +2451,9 @@ 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>>;
     };
 }
@@ -2660,12 +3117,6 @@ export declare interface MCPDispatchOptions {
     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. */
 export declare interface MCPElicitChoice {
     readonly const: string;
@@ -2837,6 +3288,34 @@ export declare interface MCPExecutionContext {
 /** Executes one canonical tool call or return a fully formed complete MCP result. */
 export declare type MCPExecutionHandler = (context: MCPExecutionContext) => ToolResult | MCPCallResult | Promise<ToolResult | MCPCallResult>;
 
+/**
+ * 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;
+}
+
+/**
+ * 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';
+
 /** One sized, themed icon associated with an MCP resource link. */
 export declare type MCPIcon = MCPMetaObject & {
     readonly src: string;
@@ -2869,18 +3348,19 @@ export declare interface MCPInputContext {
     readonly request: JSONRPCRequest;
     readonly name: string;
     readonly arguments: Readonly<Record<string, unknown>>;
-    readonly response?: MCPElicitResult;
+    /** 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. */
 export declare interface MCPInputOptions {
@@ -2890,17 +3370,19 @@ export declare interface MCPInputOptions {
     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.
  *
  * @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,9 +3392,24 @@ export declare type MCPInputRequest = MCPElicitRequest | {
     readonly params?: Readonly<Record<string, unknown>>;
 };
 
-/** A server-keyed map of embedded requests the client must fulfil. */
+/** A consumer-keyed map of embedded requests the client must fulfil. */
 export declare type MCPInputRequestMap = Readonly<Record<string, MCPInputRequest>>;
 
+/**
+ * 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;
+
+/** A consumer-keyed map of the client's answers to one issued round. */
+export declare type MCPInputResponseMap = Readonly<Record<string, MCPInputResponse>>;
+
 /**
  * An incomplete modern result carrying input requests, protected request state, or both.
  *
@@ -2932,16 +3429,30 @@ export declare type MCPInputResult = {
     readonly _meta?: MCPResultMetaObject;
 };
 
+/**
+ * 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;
+}
+
 /**
  * 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,11 +3461,10 @@ export declare interface MCPInputState {
     readonly id: JSONRPCId;
     readonly version: string;
     readonly method: string;
-    readonly key: string;
+    /** 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;
 }
 
@@ -3097,7 +3607,10 @@ export declare interface MCPLimitOptions {
     readonly message?: number;
     /** Maximum serialized UTF-8 bytes accepted in one `_meta` value. */
     readonly metadata?: number;
-    /** Maximum total enumerable keys accepted across one `_meta` value. */
+    /**
+     * Maximum 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`. */
     readonly state?: number;
@@ -3247,7 +3760,7 @@ export declare interface MCPMethodManagerInterface {
  * 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.
  *
@@ -3700,6 +4213,49 @@ export declare type MCPResultMetaObject = MCPMetaObject & {
 /** The intended recipient of annotated MCP content. */
 export declare type MCPRole = 'user' | 'assistant';
 
+/** One filesystem root a client exposes to a server. */
+export declare interface MCPRoot {
+    readonly uri: string;
+    readonly name?: string;
+    readonly _meta?: MCPMetaObject;
+}
+
+/** The client's answer to one embedded `roots/list` request. */
+export declare interface MCPRootResult {
+    readonly roots: readonly MCPRoot[];
+    readonly _meta?: MCPMetaObject;
+}
+
+/**
+ * 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;
+
+/**
+ * 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.
@@ -3791,6 +4347,15 @@ 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];
     /**
@@ -3972,6 +4537,11 @@ 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`. */
@@ -4656,7 +5226,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
@@ -4958,6 +5528,25 @@ export declare interface MCPToolDescriptor {
     readonly inputSchema: Readonly<Record<string, unknown>>;
 }
 
+/** One tool's outcome returned to the model, carried inside 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;
+}
+
+/** 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
  * one port `bindServer` and `bindClient` (`./helpers.js`) pipe an
@@ -5104,17 +5693,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 +5751,29 @@ export declare function parseRequestContext(value: unknown, limits?: MCPJSONLimi
  */
 export declare function readCancelledId(message: JSONRPCMessage): JSONRPCId | undefined;
 
+/**
+ * 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.