@orkestrel/mcp 0.0.8 → 0.0.10

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

@@ -1,6 +1,8 @@
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { JSONValue } from '@orkestrel/contract';
+import { TokenSecret } from '@orkestrel/server';
 import { ToolInterface } from '@orkestrel/tool';
 import { ToolManagerInterface } from '@orkestrel/tool';
 import { ToolResult } from '@orkestrel/tool';
@@ -54,7 +56,11 @@ export declare function bindClient(client: MCPClientInterface, transport: MCPTra
  * @remarks
  * `server.handle` already turns a malformed message into a serialized `-32700` /
  * `-32600` reply and a notification into `undefined` (no reply), so this binder adds
- * no parsing of its own. A `transport.send` throw or rejection is caught and routed
+ * no parsing of its own. A HELD-OPEN reply arrives as an
+ * {@link import('./types.js').MCPTextStream} instead of a string: this is the one place
+ * that pumps it, writing each notification in order and then the generator's returned
+ * terminating response ({@link sendStream}). A `transport.send` throw or rejection —
+ * mid-stream included — is caught and routed
  * to `server.emitter`'s `error` event (never rethrown, never an unhandled rejection);
  * a listener on that event that itself throws is swallowed (the end of the line —
  * the caller's own bug, never this binder's). The returned unbind DETACHES this
@@ -80,6 +86,128 @@ export declare function bindClient(client: MCPClientInterface, transport: MCPTra
  */
 export declare function bindServer(server: MCPServerInterface, transport: MCPTransportInterface): () => void;
 
+/**
+ * Map an executed tool's {@link ToolResult} to an MCP {@link MCPCallResult} — the
+ * value as structured content plus a backwards-compatible `text` block, or the
+ * error as a `text` block.
+ *
+ * @remarks
+ * The {@link ToolManagerInterface} already isolates a thrown tool into a
+ * `success: false` result (so the server adds NO try/catch around `execute`):
+ * that branch builds an `isError: true` result carrying `result.error`, so the
+ * model sees the failure as a tool result it can react to rather than a protocol
+ * error; a valued `success: true` branch carries `result.value` unchanged as
+ * `structuredContent` and serializes it (via `JSON.stringify`) into one `text`
+ * block. A value-less success retains the required empty `content` block and
+ * omits `structuredContent`.
+ *
+ * @param result - The tool's execution outcome
+ * @returns The MCP tool-call result
+ */
+export declare function buildCallResult(result: ToolResult): MCPCallResult;
+
+/**
+ * Build the mandatory modern `server/discover` result.
+ *
+ * @param options - The server identity, instructions, and cache configuration
+ * @returns The supported revisions, tools capability, and required modern cache stamps
+ */
+export declare function buildDiscoverResult(options: MCPServerOptions): MCPDiscoverResult;
+
+/**
+ * Build the MCP `initialize` result — the negotiated protocol version, the
+ * advertised capabilities, and the server identity.
+ *
+ * @remarks
+ * Version negotiation echoes the client's `requested` version when it is one of the
+ * supported legacy revisions. A modern or unsupported request receives the newest
+ * supported legacy revision; the client decides whether to continue.
+ * `capabilities.tools` is an empty object — this server advertises the tools
+ * capability with no sub-options (no list-changed notification yet).
+ *
+ * @param name - The server name (echoed in `serverInfo`)
+ * @param version - The server version (echoed in `serverInfo`)
+ * @param requested - The client's requested protocol version (negotiated when supported)
+ * @returns The `initialize` result payload
+ */
+export declare function buildInitializeResult(name: string, version: string, requested?: string): Readonly<Record<string, unknown>>;
+
+/**
+ * Build a JSON-RPC error {@link JSONRPCResponse} — the `id` echoed, the failure as
+ * an `error` object.
+ *
+ * @param id - The request's id (`null` for a parse / invalid-request error)
+ * @param code - One of the reserved JSON-RPC codes (see `./constants.js`)
+ * @param message - A short human description of the failure
+ * @param data - An OPTIONAL machine-readable payload (omitted from the envelope when absent)
+ * @returns The error response envelope
+ */
+export declare function buildJSONRPCError(id: string | number | null, code: number, message: string, data?: unknown): JSONRPCResponse;
+
+/**
+ * Build a JSON-RPC success {@link JSONRPCResponse} — the `id` echoed, the method's
+ * value as `result`.
+ *
+ * @param id - The request's id (`null` only for a parse / invalid-request error)
+ * @param result - The method's return value
+ * @returns The success response envelope
+ */
+export declare function buildJSONRPCResult(id: string | number | null, result: unknown): JSONRPCResponse;
+
+/**
+ * Stamp a result with the modern complete-result discriminator and server
+ * metadata, plus cache fields when the result is cacheable.
+ *
+ * @remarks
+ * This is the single stamping site shared by modern result builders. Supplying
+ * `ttl` adds both schema-coupled fields (`ttlMs` and `cacheScope`); omitting it
+ * adds neither, which keeps `tools/call` distinct from cacheable results.
+ *
+ * @param result - The unstamped result payload
+ * @param identity - The server identity carried under the reserved `_meta` key
+ * @param ttl - Required freshness lifetime for a cacheable result; omit for a non-cacheable result
+ * @param scope - The cache visibility, defaulting to `'private'` when `ttl` is supplied
+ * @returns A copy of the payload with its modern stamps
+ */
+export declare function buildModernResult<T extends object>(result: T, identity: MCPIdentity, ttl: number, scope?: 'public' | 'private'): T & {
+    readonly resultType: 'complete';
+    readonly _meta: Readonly<Record<string, unknown>>;
+    readonly ttlMs: number;
+    readonly cacheScope: 'public' | 'private';
+};
+
+export declare function buildModernResult<T extends object>(result: T, identity: MCPIdentity): T & {
+    readonly resultType: 'complete';
+    readonly _meta: Readonly<Record<string, unknown>>;
+};
+
+/**
+ * Build the first notification carrying a subscription id for a listen request.
+ *
+ * @param notifications - The exact notification filter the server will honour
+ * @param id - The `subscriptions/listen` request id
+ * @returns The stamped subscription acknowledgement notification
+ */
+export declare function buildSubscriptionAcknowledgement(notifications: SubscriptionFilter, id: string | number): JSONRPCRequest;
+
+/**
+ * Intersect a requested subscription filter with the notification families a server supports.
+ *
+ * @param requested - The notification families requested by the client
+ * @param supported - The notification families the server can actually produce
+ * @returns The exact subset the server will honour
+ */
+export declare function buildSubscriptionFilter(requested: SubscriptionFilter, supported: SubscriptionFilter): SubscriptionFilter;
+
+/**
+ * Build the terminating response for a subscription source that closes gracefully.
+ *
+ * @param id - The `subscriptions/listen` request id
+ * @param identity - The server identity included by the modern result stamping site
+ * @returns The complete modern result carrying the required subscription id metadata
+ */
+export declare function buildSubscriptionResult(id: string | number, identity: MCPIdentity): JSONRPCResponse;
+
 /**
  * Map a {@link ToolManagerInterface}'s definitions to MCP `tools/list` descriptors
  * — renaming `parameters` to the wire's `inputSchema`.
@@ -95,22 +223,12 @@ export declare function bindServer(server: MCPServerInterface, transport: MCPTra
  */
 export declare function buildToolDescriptors(manager: ToolManagerInterface): readonly MCPToolDescriptor[];
 
-/**
- * Map an executed tool's {@link ToolResult} to an MCP {@link MCPToolResult} — the
- * value (or error) as a `text` content block.
- *
- * @remarks
- * The {@link ToolManagerInterface} already isolates a thrown tool into a
- * `success: false` result (so the server adds NO try/catch around `execute`):
- * that branch builds an `isError: true` result carrying `result.error`, so the
- * model sees the failure as a tool result it can react to rather than a protocol
- * error; the `success: true` branch serializes `result.value` (via
- * `JSON.stringify`) into one `text` block.
- *
- * @param result - The tool's execution outcome
- * @returns The MCP tool-call result
- */
-export declare function buildToolResult(result: ToolResult): MCPToolResult;
+/** A successful JSON-RPC response to `tools/call`. */
+export declare interface CallToolResultResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: string | number;
+    readonly result: MCPCallResult | InputRequiredResult;
+}
 
 /**
  * The observable events of a {@link ClientTransportInterface} (§13) — the moments the
@@ -233,8 +351,8 @@ export declare function createDuplexClientTransport(transport: MCPTransportInter
  * to `connect` / `disconnect` / `notification` via `client.on(...)` (or
  * `client.emitter.on(...)`).
  *
- * @param options - `transport` (the carrier; REQUIRED), `name` / `version` (the client
- *   identity), `timeout` (the per-request deadline), and the reserved `on`
+ * @param options - `transport` (the carrier; REQUIRED), an optional `identity`
+ *   (the client identity), `timeout` (the per-request deadline), and the reserved `on`
  *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPClientOptions})
  * @returns A working {@link MCPClientInterface}
  *
@@ -267,8 +385,8 @@ export declare function createMCPClient(options: MCPClientOptions): MCPClientInt
  * `isError: true` tool result), so a misbehaving tool never crashes a dispatch. Subscribe to the
  * `request` event via `server.emitter.on('request', …)` for tracing.
  *
- * @param options - `name` / `version` (the server identity), `tools` (the live
- *   registry to expose), an optional `description`, and the reserved `on`
+ * @param options - `identity` (the server identity), `tools` (the live
+ *   registry to expose), optional `instructions`, and the reserved `on`
  *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPServerOptions})
  * @returns A working {@link MCPServerInterface}
  *
@@ -279,7 +397,7 @@ export declare function createMCPClient(options: MCPClientOptions): MCPClientInt
  * const tools = createToolManager()
  * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
  *
- * const server = createMCPServer({ name: 'calculator', version: '1.0.0', tools })
+ * const server = createMCPServer({ identity: { name: 'calculator', version: '1.0.0' }, tools })
  * server.emitter.on('request', (method, id) => log(method, id))
  *
  * // A transport pumps message strings through `handle`:
@@ -289,34 +407,320 @@ export declare function createMCPClient(options: MCPClientOptions): MCPClientInt
  */
 export declare function createMCPServer(options: MCPServerOptions): MCPServerInterface;
 
+/**
+ * Default modern result freshness lifetime in milliseconds.
+ *
+ * @remarks
+ * `ttlMs` is required on cacheable results, while zero means immediately stale
+ * rather than uncached, so the neutral usable default is one minute.
+ */
+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";
 
 /** 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.
+ *
+ * @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.
+ */
+export declare const DEFAULT_MCP_LIMITS: Readonly<{
+    message: 1048576;
+    metadata: 16384;
+    keys: 64;
+    state: 16384;
+    content: 4194304;
+    subscriptions: 128;
+    depth: 32;
+}>;
+
+/** The maximum discovery-probe deadline used when a client deadline is configured. */
+export declare const DEFAULT_MCP_PROBE_TIMEOUT = 50;
+
 /**
  * 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;
 
+/** One titled value in a form elicitation's single- or multi-select schema. */
+export declare interface ElicitChoice {
+    readonly const: string;
+    readonly title: string;
+}
+
+/** One restricted primitive schema accepted by MCP form-mode elicitation. */
+export declare type ElicitPrimitiveSchema = {
+    readonly type: 'boolean';
+    readonly title?: string;
+    readonly description?: string;
+    readonly default?: boolean;
+} | {
+    readonly type: 'number' | 'integer';
+    readonly title?: string;
+    readonly description?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly default?: number;
+} | {
+    readonly type: 'string';
+    readonly title?: string;
+    readonly description?: string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly format?: 'uri' | 'email' | 'date' | 'date-time';
+    readonly default?: string;
+    readonly enum?: readonly string[];
+    readonly enumNames?: readonly string[];
+    readonly oneOf?: readonly ElicitChoice[];
+} | {
+    readonly type: 'array';
+    readonly title?: string;
+    readonly description?: string;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly default?: readonly string[];
+    readonly items: {
+        readonly type: 'string';
+        readonly enum: readonly string[];
+    } | {
+        readonly anyOf: readonly ElicitChoice[];
+    };
+};
+
+/** An embedded MCP request asking the client to elicit input from its operator. */
+export declare interface ElicitRequest {
+    readonly method: 'elicitation/create';
+    readonly params: ElicitRequestParams;
+}
+
+/** The restricted top-level object schema carried by a form-mode elicitation request. */
+export declare interface ElicitRequestedSchema extends Readonly<Record<string, unknown>> {
+    readonly $schema?: string;
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ElicitPrimitiveSchema>>;
+    readonly required?: readonly string[];
+}
+
+/** The parameters of a form-mode `elicitation/create` request. */
+export declare interface ElicitRequestFormParams {
+    readonly mode?: 'form';
+    readonly message: string;
+    readonly requestedSchema: ElicitRequestedSchema;
+}
+
+/** The mode-discriminated parameters of an `elicitation/create` request. */
+export declare type ElicitRequestParams = ElicitRequestFormParams | ElicitRequestURLParams;
+
+/** The parameters of a URL-mode `elicitation/create` request. */
+export declare interface ElicitRequestURLParams {
+    readonly mode: 'url';
+    readonly message: string;
+    readonly url: string;
+}
+
+/** The result supplied by a client for one embedded {@link ElicitRequest}. */
+export declare interface ElicitResult {
+    readonly action: 'accept' | 'decline' | 'cancel';
+    readonly content?: Readonly<Record<string, ElicitValue>>;
+}
+
+/** The primitive value shapes accepted in an MCP form elicitation response. */
+export declare type ElicitValue = string | number | boolean | readonly string[];
+
 /**
- * Build the MCP `initialize` result — the negotiated protocol version, the
- * advertised capabilities, and the server identity.
+ * Infer the wire era for an MCP protocol revision.
+ *
+ * @param version - The protocol revision to classify
+ * @returns `'modern'` for `2026-07-28`, `'legacy'` for either supported legacy
+ * revision, or `undefined` when the revision is unsupported
+ */
+export declare function inferEra(version: string): MCPEra | undefined;
+
+/**
+ * Infer the newest supported protocol revision present in a peer's offer.
+ *
+ * @param offered - The protocol revisions offered by the peer
+ * @returns The newest locally supported offered revision, or `undefined`
+ */
+export declare function inferVersion(offered: readonly string[]): MCPVersion | undefined;
+
+/**
+ * One embedded multi-round-trip request.
  *
  * @remarks
- * Version negotiation echoes the client's `requested` version when it is one of the
- * {@link SUPPORTED_PROTOCOL_VERSIONS}, else falls back to {@link MCP_PROTOCOL_VERSION}.
- * `capabilities.tools` is an empty object — this server advertises the tools
- * capability with no sub-options (no list-changed notification yet).
+ * This package produces only {@link ElicitRequest}. The deprecated sampling and roots
+ * requests remain legal protocol union members and therefore retain their open parameter
+ * records here without gaining package-owned producers.
+ */
+export declare type InputRequest = ElicitRequest | {
+    readonly method: 'sampling/createMessage';
+    readonly params: Readonly<Record<string, unknown>>;
+} | {
+    readonly method: 'roots/list';
+    readonly params?: Readonly<Record<string, unknown>>;
+};
+
+/** A server-keyed map of embedded requests the client must fulfil. */
+export declare type InputRequests = Readonly<Record<string, InputRequest>>;
+
+/**
+ * An incomplete modern result carrying input requests, protected request state, or both.
  *
- * @param name - The server name (echoed in `serverInfo`)
- * @param version - The server version (echoed in `serverInfo`)
- * @param requested - The client's requested protocol version (negotiated when supported)
- * @returns The `initialize` result payload
+ * @remarks
+ * The two-arm union enforces the protocol's at-least-one-of rule at the type boundary:
+ * every value has `inputRequests`, `requestState`, or both.
+ */
+export declare type InputRequiredResult = {
+    readonly resultType: 'input_required';
+    readonly inputRequests: InputRequests;
+    readonly requestState?: string;
+    readonly _meta?: Readonly<Record<string, unknown>>;
+} | {
+    readonly resultType: 'input_required';
+    readonly inputRequests?: InputRequests;
+    readonly requestState: string;
+    readonly _meta?: Readonly<Record<string, unknown>>;
+};
+
+/** A map of client results keyed by the corresponding server-assigned input-request key. */
+export declare type InputResponses = Readonly<Record<string, unknown>>;
+
+/**
+ * Determine whether a value is bounded, cycle-free JSON with safe property names.
+ *
+ * @remarks
+ * Traversal is iterative, ancestor-aware, and contained by {@link attempt}; deep input,
+ * cycles, accessors, hostile proxies, `Map`/`Set`, and the prototype-pollution keys
+ * `__proto__`, `constructor`, and `prototype` return `false` rather than throwing.
+ * The byte count matches `JSON.stringify` without first allocating the serialization.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * isBoundedJSON({ ok: true }, { bytes: 16, keys: 1, depth: 1 }) // true
+ * ```
+ */
+export declare function isBoundedJSON<T>(value: T, limits: MCPJSONLimitOptions): value is T & JSONValue;
+
+/**
+ * Determine whether a value is a string within a UTF-8 byte bound.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * isBoundedString('€', 3) // true
+ * isBoundedString('€', 2) // false
+ * ```
+ */
+export declare function isBoundedString(value: unknown, bytes: number): value is string;
+
+/**
+ * Determine 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
+ *
+ * @example
+ * ```ts
+ * isElicitPrimitiveSchema({ type: 'boolean', default: true }) // true
+ * isElicitPrimitiveSchema({ type: 'object' }) // false
+ * ```
+ */
+export declare function isElicitPrimitiveSchema(value: unknown): value is ElicitPrimitiveSchema;
+
+/**
+ * Determine 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
+ *
+ * @example
+ * ```ts
+ * isElicitRequest({
+ *   method: 'elicitation/create',
+ *   params: { message: 'Continue?', requestedSchema: { type: 'object', properties: {} } },
+ * }) // true
+ * ```
+ */
+export declare function isElicitRequest(value: unknown): value is ElicitRequest;
+
+/**
+ * Determine 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
+ *
+ * @example
+ * ```ts
+ * isElicitRequestFormParams({
+ *   message: 'Continue?',
+ *   requestedSchema: { type: 'object', properties: {} },
+ * }) // true
+ * ```
+ */
+export declare function isElicitRequestFormParams(value: unknown): value is ElicitRequestFormParams;
+
+/**
+ * Determine 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
+ *
+ * @example
+ * ```ts
+ * isElicitRequestURLParams({ mode: 'url', message: 'Authenticate', url: 'https://example.test' })
+ * ```
  */
-export declare function initializeResult(name: string, version: string, requested?: string): Readonly<Record<string, unknown>>;
+export declare function isElicitRequestURLParams(value: unknown): value is ElicitRequestURLParams;
+
+/**
+ * Determine whether a value is one elicitation response.
+ *
+ * @param value - The unknown value to inspect
+ * @returns `true` when action/content have the protocol shape
+ *
+ * @example
+ * ```ts
+ * isElicitResult({ action: 'accept', content: { approved: true } }) // true
+ * ```
+ */
+export declare function isElicitResult(value: unknown): value is ElicitResult;
+
+/**
+ * Determine 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` when form-mode elicitation is declared
+ *
+ * @example
+ * ```ts
+ * isFormElicitationSupported({ elicitation: {} }) // true — implicit form mode
+ * isFormElicitationSupported({ elicitation: { url: {} } }) // false
+ * ```
+ */
+export declare function isFormElicitationSupported(value: unknown): boolean;
 
 /**
  * Determine whether a parsed value is an MCP `initialize` request — a
@@ -333,6 +737,50 @@ export declare function initializeResult(name: string, version: string, requeste
  */
 export declare function isInitializeRequest(value: unknown): value is JSONRPCRequest;
 
+/**
+ * Determine 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
+ *
+ * @example
+ * ```ts
+ * isInputRequest({ method: 'roots/list' }) // true — legal but not produced by this package
+ * ```
+ */
+export declare function isInputRequest(value: unknown): value is InputRequest;
+
+/**
+ * Determine whether a value is a server-keyed map of embedded input requests.
+ *
+ * @param value - The unknown value to inspect
+ * @returns `true` when every own value is a legal {@link InputRequest}
+ *
+ * @example
+ * ```ts
+ * isInputRequests({ confirm: { method: 'roots/list' } }) // true; maps, never arrays
+ * ```
+ */
+export declare function isInputRequests(value: unknown): value is InputRequests;
+
+/**
+ * Determine whether a value is an MCP input-required result.
+ *
+ * @remarks
+ * Enforces the at-least-one-of rule at runtime: `inputRequests`, `requestState`, or
+ * 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
+ *
+ * @example
+ * ```ts
+ * isInputRequiredResult({ resultType: 'input_required', requestState: 'opaque' }) // true
+ * isInputRequiredResult({ resultType: 'input_required' }) // false
+ * ```
+ */
+export declare function isInputRequiredResult(value: unknown): value is InputRequiredResult;
+
 /**
  * Determine whether a parsed value is a {@link JSONRPCMessage} — a request or a
  * response.
@@ -394,6 +842,29 @@ export declare function isJSONRPCResponse(value: unknown): value is JSONRPCRespo
  */
 export declare function isMCPError(value: unknown): value is MCPError;
 
+/**
+ * Determine 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_PROTOCOL_VERSIONS}
+ */
+export declare function isMCPVersion(value: unknown): value is MCPVersion;
+
+/**
+ * Determine whether a JSON-RPC request uses the modern per-request MCP wire shape.
+ *
+ * @remarks
+ * Presence routes and validity answers: this guard checks only that
+ * `params._meta` carries the reserved protocol-version key. The key's value is
+ * deliberately not narrowed here, so a present non-string version remains modern
+ * and is rejected later by `parseRequestContext` rather than falling through to
+ * legacy dispatch. Total over hostile and malformed input.
+ *
+ * @param value - The already-parsed value to inspect
+ * @returns `true` when the value is a request carrying the reserved version key
+ */
+export declare function isModernRequest(value: unknown): value is JSONRPCRequest;
+
 /**
  * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,
  * or absent.
@@ -416,6 +887,20 @@ export declare function isMCPError(value: unknown): value is MCPError;
  */
 export declare function isRequestId(value: unknown): value is string | number | undefined;
 
+/**
+ * Determine whether a value is an MCP {@link SubscriptionFilter}.
+ *
+ * @remarks
+ * Every filter field is optional. Boolean notification families accept only booleans, and
+ * `resourceSubscriptions` accepts only an array of string URIs. Unknown fields remain open
+ * for protocol extensions and are ignored by the built-in subscription matcher. Total over
+ * hostile input.
+ *
+ * @param value - The unknown value to inspect
+ * @returns `true` when every recognized filter field has its protocol shape
+ */
+export declare function isSubscriptionFilter(value: unknown): value is SubscriptionFilter;
+
 /** JSON-RPC 2.0 reserved error: the method's parameters were invalid. */
 export declare const JSONRPC_INVALID_PARAMS = -32602;
 
@@ -431,18 +916,6 @@ export declare const JSONRPC_PARSE_ERROR = -32700;
 /** JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range). */
 export declare const JSONRPC_SERVER_ERROR = -32000;
 
-/**
- * Build a JSON-RPC error {@link JSONRPCResponse} — the `id` echoed, the failure as
- * an `error` object.
- *
- * @param id - The request's id (`null` for a parse / invalid-request error)
- * @param code - One of the reserved JSON-RPC codes (see `./constants.js`)
- * @param message - A short human description of the failure
- * @param data - An OPTIONAL machine-readable payload (omitted from the envelope when absent)
- * @returns The error response envelope
- */
-export declare function jsonRPCError(id: string | number | null, code: number, message: string, data?: unknown): JSONRPCResponse;
-
 /**
  * A JSON-RPC 2.0 error object — the `error` member of a failed
  * {@link JSONRPCResponse}.
@@ -498,28 +971,88 @@ export declare interface JSONRPCResponse {
 }
 
 /**
- * Build a JSON-RPC success {@link JSONRPCResponse} — the `id` echoed, the method's
- * value as `result`.
+ * Determine whether a produced notification belongs to an honoured subscription filter.
  *
- * @param id - The request's id (`null` only for a parse / invalid-request error)
- * @param result - The method's return value
- * @returns The success response envelope
+ * @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
  */
-export declare function jsonRPCResult(id: string | number | null, result: unknown): JSONRPCResponse;
+export declare function matchesSubscriptionNotification(notification: JSONRPCRequest, filter: SubscriptionFilter): boolean;
+
+/** MCP reserved error: required HTTP metadata does not match the request body. */
+export declare const MCP_HEADER_MISMATCH = -32020;
+
+/** The legacy fallback anchor used when an initialize request cannot be accepted as modern. */
+export declare const MCP_LEGACY_VERSION: MCPVersion;
+
+/** 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. */
+export declare const MCP_META_CLIENT = "io.modelcontextprotocol/clientInfo";
+
+/** 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. */
+export declare const MCP_META_SUBSCRIPTION = "io.modelcontextprotocol/subscriptionId";
+
+/** 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. */
+export declare const MCP_MISSING_CAPABILITY = -32021;
+
+/** The modern revision offered by an unpinned client during discovery. */
+export declare const MCP_MODERN_VERSION: MCPVersion;
+
+/**
+ * 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
+ * and defines no `initialize`, so it can never be the handshake's version — a client that offers
+ * it is asking to negotiate a revision with no negotiation.
+ */
+export declare const MCP_PROTOCOL_VERSION: MCPVersion;
+
+/** MCP reserved error: a request names an unsupported protocol revision. */
+export declare const MCP_UNSUPPORTED_VERSION = -32022;
 
-/** The MCP protocol revision this server implements (the default negotiated version). */
-export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * The MCP `tools/call` result — the executed tool's output as `content` blocks,
+ * with `isError` flagging a tool failure.
+ *
+ * @remarks
+ * A success carries the tool's value unchanged as `structuredContent` alongside
+ * its serialized form in one `text` content block. A value-less success omits
+ * `structuredContent`. A tool FAILURE (the `success: false` branch the registry
+ * isolated) carries its `error` text in `content` AND sets `isError: true`, so the
+ * model sees the failure as a tool result it can react to rather than a protocol
+ * error.
+ */
+export declare interface MCPCallResult {
+    readonly content: readonly MCPContent[];
+    /** The successful tool value in its original structure; absent when no value was returned. */
+    readonly structuredContent?: unknown;
+    /** `true` when the tool failed — its error text is in `content`. */
+    readonly isError?: boolean;
+    /** The modern result discriminator; absent on a legacy result. */
+    readonly resultType?: 'complete';
+    /** Open modern protocol metadata, including reserved namespaced keys. */
+    readonly _meta?: Readonly<Record<string, unknown>>;
+}
 
 /**
  * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP server
- * over an injected {@link ClientTransportInterface}, runs the `initialize` handshake,
- * and exposes the server's tools as local {@link ToolInterface}s an agent can run.
+ * over an injected {@link ClientTransportInterface}, negotiates the modern or legacy
+ * wire era, 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;
- *   this client ISSUES them over a transport. `connect` runs `initialize`, validates and
- *   exposes the negotiated `protocol`, then sends `notifications/initialized`; `tools()`
- *   lists the remote tools and wraps each as a
+ *   this client ISSUES them over a transport. `connect` probes `server/discover` unless
+ *   pinned legacy, falls back to `initialize` only for a legacy peer, and exposes the
+ *   negotiated `version`; `tools()` lists the remote tools and wraps each as a
  *   local {@link ToolInterface} whose `execute` calls back through `call`; `call` runs a
  *   remote `tools/call` and returns the tool's value (a remote `isError: true` throws
  *   locally, so an agent's {@link import('@orkestrel/tool').ToolManagerInterface}
@@ -528,9 +1061,9 @@ export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
  *   `id` ({@link #nextId}); a single transport `message` subscription resolves / rejects
  *   the matching {@link #pending} entry by `id`. A message that is NOT a response to a
  *   pending request is a server NOTIFICATION — re-surfaced on the `notification` event.
- * - **Per-request deadline.** `#request` races `AbortSignal.timeout(this.#timeout)` (the
- *   taverna idiom — never a raw `setTimeout`): a server that never replies REJECTS the
- *   pending request once the deadline fires, never hanging.
+ * - **Per-request deadline.** Each `#request` receives its own deadline: ordinary calls use
+ *   `this.#timeout`, while an explicitly bounded discovery uses the shorter probe deadline.
+ *   `AbortSignal.timeout` (never a raw `setTimeout`) rejects only that pending request.
  * - **Transport-agnostic.** Imports only core siblings (JSON-RPC + the tool vocabulary);
  *   the concrete transport is injected. Wire fields are narrowed via the contracts
  *   guards (no `as`).
@@ -540,7 +1073,7 @@ export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
  *
  * @example
  * ```ts
- * const client = new MCPClient({ transport, name: 'agent', version: '1.0.0' })
+ * const client = new MCPClient({ transport, identity: { name: 'agent', version: '1.0.0' } })
  * await client.connect()
  * const tools = await client.tools()
  * agent.context.tools.add(tools) // the remote tools are now the agent's
@@ -552,10 +1085,11 @@ export declare class MCPClient implements MCPClientInterface {
     constructor(options: MCPClientOptions);
     get emitter(): EmitterInterface<MCPClientEventMap>;
     get connected(): boolean;
-    get protocol(): string | undefined;
+    get version(): MCPVersion | undefined;
     get transport(): ClientTransportInterface;
     on<K extends keyof MCPClientEventMap>(event: K, handler: (...args: MCPClientEventMap[K]) => void): void;
     connect(): Promise<void>;
+    discover(): Promise<MCPDiscoverResult>;
     disconnect(): Promise<void>;
     tools(): Promise<readonly ToolInterface[]>;
     call(name: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
@@ -590,15 +1124,16 @@ export declare type MCPClientEventMap = {
 
 /**
  * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP
- * server over an injected {@link ClientTransportInterface}, performs the
- * `initialize` handshake, and exposes the server's tools as local
+ * server over an injected {@link ClientTransportInterface}, negotiates the
+ * modern or legacy wire era, and exposes the server's tools as local
  * {@link ToolInterface}s an agent can run.
  *
  * @remarks
  * - **The mirror of {@link MCPServerInterface}.** Where the server DISPATCHES requests
- *   over a tool registry, the client ISSUES them over a transport: `connect` runs the
- *   `initialize` handshake, validates and exposes the negotiated `protocol` (then sends
- *   `notifications/initialized`); `tools()` lists
+ *   over a tool registry, the client ISSUES them over a transport: `connect` probes
+ *   `server/discover` first unless pinned to a legacy revision, falling back to the
+ *   legacy `initialize` handshake only when the peer does not speak the modern era.
+ *   The negotiated revision is exposed through `version`; `tools()` lists
  *   the remote tools and wraps each as a local {@link ToolInterface} whose `execute`
  *   calls back through `call`; `call(name, args)` runs a remote `tools/call` and
  *   returns the tool's value (a remote tool FAILURE — `isError: true` — throws locally,
@@ -620,13 +1155,10 @@ export declare type MCPClientEventMap = {
  */
 export declare interface MCPClientInterface {
     readonly emitter: EmitterInterface<MCPClientEventMap>;
-    /** Whether the `initialize` handshake has completed and the client is connected. */
+    /** Whether era negotiation has completed and the client is connected. */
     readonly connected: boolean;
-    /**
-     * The MCP protocol revision negotiated by {@link connect}, or `undefined` before
-     * connecting and after {@link disconnect}.
-     */
-    readonly protocol: string | undefined;
+    /** The negotiated protocol revision, or `undefined` while disconnected. */
+    readonly version: MCPVersion | undefined;
     /** The injected transport the client drives the remote server over. */
     readonly transport: ClientTransportInterface;
     /**
@@ -638,19 +1170,29 @@ export declare interface MCPClientInterface {
      */
     on<K extends keyof MCPClientEventMap>(event: K, handler: (...args: MCPClientEventMap[K]) => void): void;
     /**
-     * Connect to the remote server — open the transport and run the `initialize`
-     * handshake, validate its negotiated protocol, then send
-     * `notifications/initialized`.
+     * Connect to the remote server — open the transport and negotiate the modern or
+     * legacy wire era without exposing that choice to the caller.
      *
      * @remarks
-     * Idempotent — a second `connect` while already connected is a no-op. On success
-     * {@link protocol} contains a supported revision and the `connect` event fires. A
-     * non-string or unsupported revision closes the transport and rejects without
-     * connecting or sending the initialized notification.
+     * Idempotent — a second `connect` while already connected is a no-op. An unpinned
+     * client probes `server/discover`; a pinned legacy client and a legacy fallback run
+     * `initialize` and send `notifications/initialized`. On success {@link version}
+     * contains a supported revision and the `connect` event fires.
      *
      * @returns Resolves once the handshake completes and the client is connected
      */
     connect(): Promise<void>;
+    /**
+     * Discover a modern server's supported revisions and capabilities.
+     *
+     * @remarks
+     * The request carries the modern per-request metadata stamp. Unknown revisions in
+     * the peer's advertisement are ignored because {@link MCPDiscoverResult} exposes
+     * only revisions this client can negotiate.
+     *
+     * @returns The validated modern discovery result
+     */
+    discover(): Promise<MCPDiscoverResult>;
     /**
      * Disconnect from the remote server — reject every pending request and close the
      * transport.
@@ -680,7 +1222,7 @@ export declare interface MCPClientInterface {
      * result's `text` content blocks, and either parses the JSON value or throws.
      *
      * @remarks
-     * The inverse of the server's `buildToolResult`: a SUCCESS parses the concatenated
+     * The inverse of the server's `buildCallResult`: a SUCCESS parses the concatenated
      * `text` as JSON (falling back to the raw string when it is not JSON); a remote tool
      * FAILURE (`isError: true`) THROWS an `Error` carrying the error text — so an agent's
      * {@link ToolManagerInterface} isolates the remote failure into a `success: false`
@@ -695,15 +1237,18 @@ export declare interface MCPClientInterface {
 
 /**
  * Options for `createMCPClient` — the {@link ClientTransportInterface} to drive, the
- * client identity (`name` / `version`), the per-request `timeout`, and the reserved
+ * optional client {@link MCPIdentity}, the per-request `timeout`, and the reserved
  * `on` hooks (§8).
  *
  * @remarks
  * - `transport` — the carrier the client drives a remote MCP server over (REQUIRED;
  *   a concrete one from `src/server/mcp`, or an in-process loopback).
- * - `name` / `version` — identify the client in the `initialize` handshake
- *   (`clientInfo`); default to {@link import('./constants.js').DEFAULT_MCP_CLIENT_NAME}
- *   / {@link import('./constants.js').DEFAULT_MCP_CLIENT_VERSION}.
+ * - `identity` — identifies the client in the `initialize` handshake (`clientInfo`);
+ *   defaults to {@link import('./constants.js').DEFAULT_MCP_CLIENT_NAME} /
+ *   {@link import('./constants.js').DEFAULT_MCP_CLIENT_VERSION}.
+ * - `capabilities` — the open client-capability record carried by every modern
+ *   request; defaults to an empty record when the modern client implementation lands.
+ * - `version` — an optional protocol pin; absence lets the modern client negotiate.
  * - `timeout` — the per-request deadline in milliseconds: a `tools/list` / `tools/call`
  *   / `initialize` that the server does not answer within it REJECTS (the pending
  *   request is settled by an `AbortSignal.timeout(timeout)` deadline — never a raw
@@ -717,18 +1262,57 @@ export declare interface MCPClientOptions {
     /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly transport: ClientTransportInterface;
-    readonly name?: string;
-    readonly version?: string;
+    readonly identity?: MCPIdentity;
+    /** The open client-capability record carried by modern requests. */
+    readonly capabilities?: Readonly<Record<string, unknown>>;
+    /** An optional protocol revision pin; absence permits negotiation. */
+    readonly version?: MCPVersion;
     /** The per-request deadline in milliseconds (default {@link import('./constants.js').DEFAULT_MCP_REQUEST_TIMEOUT}). */
     readonly timeout?: number;
 }
 
-/** One content item of an MCP {@link MCPToolResult} — a `text` block carrying the tool's output. */
+/** One content item of an MCP {@link MCPCallResult} — a `text` block carrying the tool's output. */
 export declare interface MCPContent {
     readonly type: 'text';
     readonly text: string;
 }
 
+/** The mandatory modern `server/discover` result. */
+export declare interface MCPDiscoverResult {
+    readonly supportedVersions: readonly MCPVersion[];
+    readonly capabilities: Readonly<Record<string, unknown>>;
+    readonly resultType: 'complete';
+    readonly ttlMs: number;
+    readonly cacheScope: 'public' | 'private';
+    readonly instructions?: string;
+    readonly _meta?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Per-request execution options every dispatched handler receives.
+ *
+ * @remarks
+ * `caller` is consumer-ASSERTED and NEVER VERIFIED. Sessions mint transport identity, not
+ * caller identity, and nothing in MCP authenticates this value. This package carries it
+ * opaquely without inspecting, validating, or serializing it. A consumer must narrow it with
+ * its own total guard and treat absence as unauthenticated.
+ */
+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. */
+    readonly caller?: unknown;
+}
+
+/** One consumer-requested form elicitation, before MCP assigns its map key and signs state. */
+export declare interface MCPElicitation {
+    readonly request: ElicitRequestFormParams;
+    readonly state?: string;
+}
+
+/** The wire era selected by an MCP request's structure. */
+export declare type MCPEra = 'modern' | 'legacy';
+
 /**
  * A remote Model Context Protocol JSON-RPC error, preserving its machine-readable
  * numeric code and optional structured context.
@@ -737,13 +1321,19 @@ export declare interface MCPContent {
  * {@link MCPClient} throws this error only for a remote JSON-RPC `error` response.
  * Local lifecycle and transport conditions such as disconnects and request timeouts
  * remain plain `Error`s. `context` carries the response's optional `error.data`
- * unchanged and is `undefined` when the peer omitted it.
+ * unchanged and is `undefined` when the peer omitted it. This includes the modern
+ * reserved paths: `-32020` carries no context, `-32021` may carry
+ * `requiredCapabilities`, and `-32022` carries the peer's `supported` revisions and
+ * `requested` revision for negotiation recovery.
  *
  * @example
  * ```ts
- * const error = new MCPError('Method not found', -32601, { method: 'missing' })
- * error.code // -32601
- * error.context // { method: 'missing' }
+ * const error = new MCPError('Unsupported protocol version', -32022, {
+ * 	supported: ['2026-07-28'],
+ * 	requested: '2024-11-05',
+ * })
+ * error.code // -32022
+ * error.context // { supported: ['2026-07-28'], requested: '2024-11-05' }
  * ```
  */
 export declare class MCPError extends Error {
@@ -760,6 +1350,195 @@ export declare class MCPError extends Error {
     constructor(message: string, code: number, context?: unknown);
 }
 
+/** The identity (`name` / `version`) of an MCP server or client. */
+export declare interface MCPIdentity {
+    readonly name: string;
+    readonly version: string;
+}
+
+/** 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?: ElicitResult;
+    readonly state?: string;
+}
+
+/**
+ * Decide whether the current `tools/call` needs operator input.
+ *
+ * @param context - The original call plus a verified response/state on a retry
+ * @param options - The per-request execution options
+ * @returns A form elicitation to send, or `undefined` to continue into the tool registry
+ */
+export declare type MCPInputHandler = (context: MCPInputContext, options: MCPDispatchOptions) => MCPElicitation | undefined | Promise<MCPElicitation | undefined>;
+
+/** Consumer policy for the server's multi-round-trip input mechanism. */
+export declare interface MCPInputOptions {
+    /** HMAC secret or `[current, ...older]` rotation list used by `signToken` / `verifyToken`. */
+    readonly secret: TokenSecret;
+    /** Token lifetime in milliseconds; required so MCP never invents an expiry policy. */
+    readonly ttl: number;
+    /** Resolve the authenticated principal for the call in hand. */
+    readonly principal: MCPPrincipalHandler;
+    /** Decide whether the call needs a form elicitation, including on verified retries. */
+    readonly elicit: MCPInputHandler;
+}
+
+/** The integrity-protected payload carried inside an opaque `requestState` token. */
+export declare interface MCPInputState {
+    readonly principal: string;
+    readonly ttl: number;
+    readonly origin: string | number;
+    readonly key: string;
+    readonly name: string;
+    readonly state?: string;
+}
+
+/** Limits applied by {@link isBoundedJSON} to one JSON value. */
+export declare interface MCPJSONLimitOptions {
+    /** Maximum serialized UTF-8 bytes. */
+    readonly bytes: number;
+    /** Maximum total enumerable keys; omitted when bytes alone bound breadth. */
+    readonly keys?: number;
+    /** Maximum array/object nesting depth. */
+    readonly depth: number;
+}
+
+/** Configurable hostile-input and live-resource bounds for an MCP server. */
+export declare interface MCPLimitOptions {
+    /** Maximum UTF-8 bytes accepted by the raw string boundary. */
+    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. */
+    readonly keys?: number;
+    /** Maximum UTF-8 bytes accepted in one protected `requestState`. */
+    readonly state?: number;
+    /** Maximum serialized UTF-8 bytes accepted from one produced tool content value. */
+    readonly content?: number;
+    /** Maximum simultaneously live built-in subscription streams. */
+    readonly subscriptions?: number;
+    /** Maximum nesting depth accepted by bounded JSON values. */
+    readonly depth?: number;
+}
+
+/**
+ * The MCP `tools/list` result — tool descriptors plus optional modern result
+ * stamps.
+ *
+ * @remarks
+ * The wire field names remain verbatim. A modern result requires `resultType`,
+ * `ttlMs`, and `cacheScope`; they remain optional here because the same result
+ * shape also models the unstamped legacy response.
+ */
+export declare interface MCPListResult {
+    readonly tools: readonly MCPToolDescriptor[];
+    readonly resultType?: 'complete';
+    readonly ttlMs?: number;
+    readonly cacheScope?: 'public' | 'private';
+    readonly _meta?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * One modern method, registered on the seam that dispatches it.
+ *
+ * @remarks
+ * `undefined` answers nothing (the notification arm); an {@link MCPStream} holds the
+ * request open. `options.signal` aborts when the caller's request ends — what a handler
+ * does with it is the handler's decision, never this package's. `options.caller` is
+ * consumer-asserted and never verified by this package.
+ *
+ * @param request - The parsed modern request being dispatched
+ * @param options - The per-request execution options (see {@link MCPDispatchOptions})
+ * @returns The terminating response, a held-open {@link MCPStream}, or `undefined` for no answer
+ */
+export declare type MCPMethodHandler = (request: JSONRPCRequest, options: MCPDispatchOptions) => Promise<JSONRPCResponse | MCPStream | undefined>;
+
+/**
+ * The modern method registry an {@link import('./types.js').MCPServerInterface}
+ * dispatches through — a name-keyed store of {@link MCPMethodHandler}s that owns its
+ * map rather than exposing one.
+ *
+ * @remarks
+ * - **One seam.** The server registers its built-in modern methods here at construction
+ *   and resolves EVERY modern method from here, so a consumer's method and a built-in
+ *   are the same kind of thing on the same path.
+ * - **Registration is a write, not a merge.** `add` under a name already present
+ *   REPLACES it, which is how a consumer overrides a built-in; there is no precedence
+ *   rule to remember.
+ * - **A narrower contract than a `Map`.** Callers register and resolve; they cannot
+ *   iterate, clear, or otherwise reach the server's internal state through it.
+ *
+ * @example
+ * ```ts
+ * const methods = new MCPMethodManager()
+ * methods.add('tools/list', async (request) => buildJSONRPCResult(request.id ?? null, { tools: [] }))
+ * methods.method('tools/list') // the handler
+ * methods.method('tools/nope') // undefined → the dispatch branch answers -32601
+ * ```
+ */
+export declare class MCPMethodManager implements MCPMethodManagerInterface {
+    #private;
+    add(name: string, handler: MCPMethodHandler): void;
+    method(name: string): MCPMethodHandler | undefined;
+}
+
+/**
+ * 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,
+ * so they travel the SAME path as every later method: there is no second dispatch route
+ * and no precedence puzzle. `add` under an existing name REPLACES that method — a
+ * consumer overriding a built-in is an ordinary registration, not a special case. A name
+ * with no handler is not an error state to model: {@link method} answers `undefined` and
+ * the dispatch branch turns that into `-32601`.
+ */
+export declare interface MCPMethodManagerInterface {
+    /**
+     * Register one modern method — replacing any handler already under that name.
+     *
+     * @param name - The JSON-RPC method name to answer (e.g. `'tools/call'`)
+     * @param handler - The handler dispatched for that method
+     */
+    add(name: string, handler: MCPMethodHandler): void;
+    /**
+     * Find the handler registered for one method name.
+     *
+     * @param name - The JSON-RPC method name to resolve
+     * @returns The registered handler, or `undefined` when the method is unregistered
+     */
+    method(name: string): MCPMethodHandler | undefined;
+}
+
+/**
+ * Derive the deployment-authenticated principal bound into signed request state.
+ *
+ * @param request - The parsed `tools/call` request
+ * @param options - The per-request execution options
+ * @returns The authenticated principal to bind into protected state
+ */
+export declare type MCPPrincipalHandler = (request: JSONRPCRequest, options: MCPDispatchOptions) => string | Promise<string>;
+
+/**
+ * The validated per-request context projected from a modern request's reserved
+ * `_meta` keys.
+ *
+ * @remarks
+ * `version` remains a string so a syntactically valid but unsupported revision
+ * reaches the dedicated unsupported-version path. `capabilities` is an open wire
+ * record; `identity` is optional because client information is recommended but
+ * not required.
+ */
+export declare interface MCPRequestContext {
+    readonly version: string;
+    readonly capabilities: Readonly<Record<string, unknown>>;
+    readonly identity?: MCPIdentity;
+}
+
 /**
  * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
  * requests over a live {@link ToolManagerInterface}, with NO transport coupling.
@@ -771,14 +1550,15 @@ export declare class MCPError extends Error {
  *   `JSON.parse`s the raw message (a failure → a `-32700` response), narrows it to
  *   a request (a non-request → a `-32600` response), dispatches, and serializes the
  *   response back to a string (`undefined` for a notification).
- * - **The method switch.** `initialize` negotiates the protocol version + advertises
- *   the tools capability; `notifications/initialized` is a notification (no
- *   response); `ping` returns `{}`; `tools/list` lists the registry's tools (its
- *   `parameters` renamed to `inputSchema`); `tools/call` runs a tool by name (the
- *   {@link ToolManagerInterface} isolates a tool throw into a `success: false`
- *   result, which maps to an `isError: true` tool result — so the server adds NO
- *   try/catch). An unknown method → `-32601`; a `tools/call` with a missing /
- *   non-string `name` → `-32602`.
+ * - **Dual-era dispatch.** A request carrying the reserved modern version key uses
+ *   modern metadata validation and the registered method seam. Every other request
+ *   uses the legacy `initialize` / `ping` / `tools/list` / `tools/call` switch. The
+ *   wire era is selected per request and never stored.
+ * - **One modern seam.** `server/discover`, `tools/list`, `tools/call`, and
+ *   `subscriptions/listen` are
+ *   registered on `methods` at construction and resolved from it on every dispatch —
+ *   the same path a later method or a consumer's own takes, with an unregistered
+ *   method still answering `-32601`.
  * - **Provider-agnostic.** Imports only core siblings — JSON-RPC + the tool registry,
  *   no HTTP, no model. Wire fields are narrowed via the contracts guards (no `as`).
  * - **Observable (§13).** The owned `emitter` fires `request` at the top of every
@@ -789,7 +1569,7 @@ export declare class MCPError extends Error {
  * ```ts
  * const tools = createToolManager()
  * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
- * const server = new MCPServer({ name: 'demo', version: '1.0.0', tools })
+ * const server = new MCPServer({ identity: { name: 'demo', version: '1.0.0' }, tools })
  * await server.handle('{"jsonrpc":"2.0","method":"ping","id":1}') // '{"jsonrpc":"2.0","id":1,"result":{}}'
  * ```
  */
@@ -797,10 +1577,10 @@ export declare class MCPServer implements MCPServerInterface {
     #private;
     constructor(options: MCPServerOptions);
     get emitter(): EmitterInterface<MCPServerEventMap>;
-    get name(): string;
-    get version(): string;
-    dispatch(request: JSONRPCRequest): Promise<JSONRPCResponse | undefined>;
-    handle(message: string): Promise<string | undefined>;
+    get identity(): MCPIdentity;
+    get methods(): MCPMethodManagerInterface;
+    dispatch(request: JSONRPCRequest, options?: MCPDispatchOptions): Promise<JSONRPCResponse | MCPStream | undefined>;
+    handle(message: string, options?: MCPDispatchOptions): Promise<string | MCPTextStream | undefined>;
 }
 
 /**
@@ -809,16 +1589,16 @@ export declare class MCPServer implements MCPServerInterface {
  * via `server.emitter.on`.
  *
  * @remarks
- * `request` fires at the TOP of every `dispatch` with the method and the
- * correlating id (`null` for a notification), BEFORE the method runs — so an
- * observer sees every inbound call. Listener isolation is the emitter's (§13): a
+ * `request` fires at the TOP of every `dispatch` with the method, correlating id
+ * (`null` for a notification), and structurally selected wire era, BEFORE the
+ * method runs — so an observer sees every inbound call. Listener isolation is the emitter's (§13): a
  * listener throw is routed to the emitter's `error` handler (the `error` option),
  * never onto this map, so a buggy observer can never corrupt a dispatch. Declared as
  * a `type` alias (§4.5) so the type-literal satisfies `EventMap` structurally.
  */
 export declare type MCPServerEventMap = {
-    /** A request is being dispatched — its `method` and correlating `id` (`null` for a notification). */
-    readonly request: readonly [method: string, id: string | number | null];
+    /** A request is being dispatched — its method, correlating id, and structural wire era. */
+    readonly request: readonly [method: string, id: string | number | null, era: MCPEra];
     /**
      * A transport-level fault surfaced while a bound {@link MCPTransportInterface} was
      * piping a reply out (a `send` throw or rejection from {@link bindServer}). A DOMAIN
@@ -827,26 +1607,26 @@ export declare type MCPServerEventMap = {
     readonly error: readonly [error: unknown];
 };
 
-/** The server identity echoed in the MCP `initialize` result's `serverInfo`. */
-export declare interface MCPServerInfo {
-    readonly name: string;
-    readonly version: string;
-}
-
 /**
  * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
- * requests (`initialize` / `ping` / `tools/list` / `tools/call`) over a live
+ * requests (the fixed legacy methods plus the modern subscription method) over a live
  * {@link ToolManagerInterface}, with NO transport coupling (a transport layer
  * pumps strings through `handle`).
  *
  * @remarks
  * - **Two entry points.** `dispatch(request)` is the TYPED core: it takes an
  *   already-parsed {@link JSONRPCRequest}, runs the method, and resolves a
- *   {@link JSONRPCResponse} — or `undefined` for a NOTIFICATION (a request with no
- *   `id`). `handle(message)` is the STRING boundary: it `JSON.parse`s the raw
- *   message, narrows it to a request, dispatches, and serializes the response back
- *   to a string — turning a parse failure into a `-32700` response and a non-request
- *   into a `-32600` response, and returning `undefined` for a notification.
+ *   {@link JSONRPCResponse} — or an {@link MCPStream} for a held-open modern method, or
+ *   `undefined` for a NOTIFICATION (a request with no `id`). `handle(message)` is the
+ *   STRING boundary: it `JSON.parse`s the raw message, narrows it to a request,
+ *   dispatches, and serializes the answer back to a string (or an {@link MCPTextStream},
+ *   the same sequence already serialized) — turning a parse failure into a `-32700`
+ *   response and a non-request into a `-32600` response, and returning `undefined` for a
+ *   notification.
+ * - **One method seam.** Every modern method — the built-in `server/discover` /
+ *   `tools/list` / `tools/call` / `subscriptions/listen` included — is registered on `methods` and dispatched
+ *   from it, so a method added later travels the identical path and an unregistered one
+ *   still answers `-32601`.
  * - **Provider-agnostic.** Imports only core siblings; it speaks JSON-RPC + the
  *   tool registry, with no HTTP, no model, and no backend coupling.
  * - **Observable (§13).** The owned `emitter` ({@link MCPServerEventMap}) fires
@@ -855,57 +1635,120 @@ export declare interface MCPServerInfo {
  */
 export declare interface MCPServerInterface {
     readonly emitter: EmitterInterface<MCPServerEventMap>;
-    readonly name: string;
-    readonly version: string;
+    readonly identity: MCPIdentity;
+    /** The modern method registry this server dispatches through (built-ins included). */
+    readonly methods: MCPMethodManagerInterface;
     /**
-     * Dispatch an already-parsed request — run its method and resolve the response,
-     * or `undefined` for a notification (a request with no `id`).
+     * Dispatch an already-parsed request — run its method and resolve the answer, or
+     * `undefined` for a notification (a request with no `id`).
+     *
+     * @remarks
+     * A held-open modern method answers with an {@link MCPStream} instead of a response:
+     * narrow the two apart with `Symbol.asyncIterator in result`. `options` is optional,
+     * so a caller that cannot abort simply never supplies one.
      *
      * @param request - The parsed JSON-RPC request to dispatch
-     * @returns The response, or `undefined` when the request was a notification
+     * @param options - Per-request execution options (see {@link MCPDispatchOptions})
+     * @returns The response, a held-open {@link MCPStream}, or `undefined` for a notification
      */
-    dispatch(request: JSONRPCRequest): Promise<JSONRPCResponse | undefined>;
+    dispatch(request: JSONRPCRequest, options?: MCPDispatchOptions): Promise<JSONRPCResponse | MCPStream | undefined>;
     /**
-     * Handle a raw message string — parse it, dispatch, and serialize the response.
+     * Handle a raw message string — parse it, dispatch, and serialize the answer.
      *
      * @remarks
      * A `JSON.parse` failure resolves a serialized `-32700` (Parse error) response;
      * a parsed value that is not a valid request resolves a serialized `-32600`
-     * (Invalid Request) response; a notification resolves `undefined` (no response).
+     * (Invalid Request) response; a notification resolves `undefined` (no response). A
+     * held-open method resolves an {@link MCPTextStream} — the typed stream's mirror,
+     * already serialized — so a transport writes each message with no second parse.
      *
      * @param message - The raw JSON-RPC message string
-     * @returns The serialized response string, or `undefined` for a notification
+     * @param options - Per-request execution options (see {@link MCPDispatchOptions})
+     * @returns The serialized response string, an {@link MCPTextStream}, or `undefined` for a notification
      */
-    handle(message: string): Promise<string | undefined>;
+    handle(message: string, options?: MCPDispatchOptions): Promise<string | MCPTextStream | undefined>;
 }
 
 /**
- * Options for `createMCPServer` — the server identity (`name` / `version`), the
- * live {@link ToolManagerInterface} it exposes, an optional `description`, and the
+ * Options for `createMCPServer` — the server {@link MCPIdentity}, the live
+ * {@link ToolManagerInterface} it exposes, optional `instructions`, and the
  * reserved `on` hooks (§8).
  *
  * @remarks
- * `name` / `version` identify the server in the `initialize` handshake
- * (`serverInfo`). `tools` is the live registry the server dispatches `tools/list`
- * / `tools/call` over — its `definitions()` advertise the tools and its
- * `execute()` runs a call (the manager already isolates a tool throw into a
- * `success: false` result, so the server adds none). `description` is a human label for
- * the server (reserved for a future `instructions` capability — unused by the
- * current dispatch). `on` is the §8 reserved key: initial listeners for the
- * server's {@link MCPServerEventMap}, wired at construction.
+ * `identity` identifies the server in the `initialize` handshake (`serverInfo`).
+ * `tools` is the live registry the server dispatches `tools/list` / `tools/call`
+ * over — its `definitions()` advertise the tools and its `execute()` runs a call
+ * (the manager already isolates a tool throw into a `success: false` result, so
+ * the server adds none). `instructions` is the optional human guidance exposed
+ * by `server/discover`. `cache` configures the modern cache stamps: `ttl` is the
+ * freshness lifetime in milliseconds and `scope` defaults to `'private'`. `on`
+ * is the §8 reserved key: initial listeners for the server's
+ * {@link MCPServerEventMap}, wired at construction. `input` enables modern
+ * `tools/call` multi-round trips: the consumer decides when input is needed and
+ * supplies principal/signing/TTL policy, while MCP assigns the request key and
+ * owns the protected wire round trip. `limit` configures the server's hostile-input
+ * and live-subscription bounds; every omitted leaf uses {@link DEFAULT_MCP_LIMITS}.
  */
 export declare interface MCPServerOptions {
     readonly on?: EmitterHooks<MCPServerEventMap>;
     /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
-    readonly name: string;
-    readonly version: string;
+    readonly identity: MCPIdentity;
     /** The live tool registry the server exposes over `tools/list` / `tools/call`. */
     readonly tools: ToolManagerInterface;
-    /** A human label for the server (reserved for a future capability; unused by dispatch). */
-    readonly description?: string;
+    /** Optional human guidance exposed by `server/discover`. */
+    readonly instructions?: string;
+    /** 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 signing and expiry policy is consumer-supplied. */
+    readonly input?: MCPInputOptions;
+    /** Optional event-driven producer for the modern `subscriptions/listen` method. */
+    readonly subscription?: MCPSubscriptionOptions;
+    /** Hostile-input and live-resource bounds; omitted leaves use secure defaults. */
+    readonly limit?: MCPLimitOptions;
+}
+
+/**
+ * A held-open modern result: each `yield` is a notification (a {@link JSONRPCRequest}
+ * with no `id`); the `return` value is the terminating response.
+ *
+ * @remarks
+ * Held-open closure is a RESULT in the modern revision, not an out-of-band event, so it
+ * arrives where a result arrives — the generator's `return`. Consuming a stream and
+ * consuming a unary response therefore end the same way, and a transport narrows the two
+ * apart at ONE point (`Symbol.asyncIterator in result`), at the place that already pumps
+ * messages onto the wire.
+ */
+export declare type MCPStream = AsyncGenerator<JSONRPCRequest, JSONRPCResponse>;
+
+/**
+ * Produce notifications for one honoured `subscriptions/listen` filter.
+ *
+ * @remarks
+ * The producer parks on its own event source while idle and ends its iterable to close the
+ * subscription gracefully. `options.signal` is the per-request cancellation signal; a
+ * producer that needs cancellation observes it directly rather than polling.
+ *
+ * @param notifications - The requested filter intersected with the server's supported filter
+ * @param options - The per-request execution options
+ * @returns An event-driven source of server notifications
+ */
+export declare type MCPSubscriptionHandler = (notifications: SubscriptionFilter, options: MCPDispatchOptions) => AsyncIterable<JSONRPCRequest> | Promise<AsyncIterable<JSONRPCRequest>>;
+
+/** Configuration for the server's built-in `subscriptions/listen` method. */
+export declare interface MCPSubscriptionOptions {
+    /** The notification filter this server can actually honour. */
+    readonly notifications: SubscriptionFilter;
+    /** Open the producer for one honoured filter. */
+    readonly listen: MCPSubscriptionHandler;
 }
 
+/** The string-boundary mirror of {@link MCPStream} — the same sequence, already serialized. */
+export declare type MCPTextStream = AsyncGenerator<string, string>;
+
 /**
  * One entry of the MCP `tools/list` result — a tool's `name`, optional
  * `description`, and its JSON-Schema `inputSchema`.
@@ -921,22 +1764,6 @@ export declare interface MCPToolDescriptor {
     readonly inputSchema: Readonly<Record<string, unknown>>;
 }
 
-/**
- * The MCP `tools/call` result — the executed tool's output as `content` blocks,
- * with `isError` flagging a tool failure.
- *
- * @remarks
- * A success carries the tool's value serialized into one `text` content block; a
- * tool FAILURE (the `success: false` branch the registry isolated) carries its
- * `error` text in `content` AND sets `isError: true`, so the model sees the
- * failure as a tool result it can react to rather than a protocol error.
- */
-export declare interface MCPToolResult {
-    readonly content: readonly MCPContent[];
-    /** `true` when the tool failed — its error text is in `content`. */
-    readonly isError?: boolean;
-}
-
 /**
  * A duplex message channel an environment face provides to the pure engine — the
  * one port `bindServer` and `bindClient` (`./helpers.js`) pipe an
@@ -962,6 +1789,9 @@ export declare interface MCPTransportInterface {
     readonly close: () => void | Promise<void>;
 }
 
+/** A protocol revision supported by this MCP package. */
+export declare type MCPVersion = '2026-07-28' | '2025-11-25' | '2025-06-18';
+
 /**
  * Narrow an already-parsed value to a {@link JSONRPCMessage}, or `undefined` when
  * it is not one.
@@ -984,16 +1814,132 @@ export declare interface MCPTransportInterface {
  */
 export declare function parseJSONRPCMessage(value: unknown): JSONRPCMessage | undefined;
 
+/**
+ * Parse the verified value embedded in an opaque signed `requestState` token.
+ *
+ * @remarks
+ * This parser does not verify the HMAC; {@link import('@orkestrel/server').verifyToken}
+ * performs that boundary first and returns the JSON string parsed here. The protected
+ * payload binds the authenticated principal, token lifetime, originating request id,
+ * server-assigned input key, tool name, and optional consumer state. Total over malformed
+ * or hostile input.
+ *
+ * @param value - The HMAC-verified token value to parse
+ * @returns The protected input state, or `undefined` when malformed
+ *
+ * @example
+ * ```ts
+ * parseMCPInputState('{"principal":"user-1","ttl":1000,"origin":1,"key":"k","name":"reply"}')
+ * // { principal: 'user-1', ttl: 1000, origin: 1, key: 'k', name: 'reply' }
+ * ```
+ */
+export declare function parseMCPInputState(value: unknown): MCPInputState | undefined;
+
+/**
+ * Parse the reserved modern request metadata into an {@link MCPRequestContext}.
+ *
+ * @remarks
+ * This is the validity step after {@link isModernRequest}: a defined result can
+ * only come from a guard-positive request, while a guard-positive request returns
+ * `undefined` exactly when its required modern metadata is malformed. The version
+ * must be a string but need not be supported; unsupported strings belong to the
+ * dedicated protocol-version error path. Client identity is optional, but when
+ * present it must carry string `name` and `version` members. Total over hostile and
+ * malformed input.
+ *
+ * @param value - The already-parsed request candidate to coerce
+ * @returns The validated modern request context, or `undefined`
+ */
+export declare function parseRequestContext(value: unknown): MCPRequestContext | undefined;
+
+/**
+ * Pump an {@link MCPTextStream} onto a transport — every notification in order, then the
+ * terminating response.
+ *
+ * @remarks
+ * The generator's `return` value is a message like any other on the wire: it is sent
+ * LAST and closes the exchange. Sends are awaited one at a time so the transport
+ * receives the sequence in the order the method produced it.
+ *
+ * @param stream - The serialized held-open result to write out
+ * @param transport - The duplex channel to write each message to
+ * @returns Resolves once the terminating response has been sent
+ *
+ * @example
+ * ```ts
+ * const answer = await server.handle(message)
+ * if (typeof answer !== 'string') await sendStream(answer, transport)
+ * ```
+ */
+export declare function sendStream(stream: MCPTextStream, transport: MCPTransportInterface): Promise<void>;
+
+/**
+ * Serialize a typed {@link MCPStream} into its string mirror — each yielded
+ * notification and the terminating response, already `JSON.stringify`d.
+ *
+ * @remarks
+ * The string-boundary half of the held-open arm: `handle` returns this so a transport
+ * writes each message with no second parse, exactly as it writes a unary reply string.
+ * The terminating response arrives as the returned generator's OWN `return` value, so a
+ * consumer distinguishes "one more notification" from "this is the answer" without a
+ * sentinel.
+ *
+ * @param stream - The typed held-open result to serialize
+ * @returns The same sequence with every message serialized to a string
+ *
+ * @example
+ * ```ts
+ * const text = serializeStream(stream)
+ * for (let next = await text.next(); ; next = await text.next()) {
+ * 	if (next.done === true) return next.value // the terminating response, serialized
+ * 	log(next.value) // one serialized notification
+ * }
+ * ```
+ */
+export declare function serializeStream(stream: MCPStream): MCPTextStream;
+
+/**
+ * Stamp a subscription notification with the request id reserved for its held-open stream.
+ *
+ * @param notification - The notification to copy and stamp
+ * @param id - The `subscriptions/listen` request id
+ * @returns The stamped notification, preserving its other params and metadata
+ */
+export declare function stampSubscriptionNotification(notification: JSONRPCRequest, id: string | number): JSONRPCRequest;
+
+/** The notification families a client may opt in to on a `subscriptions/listen` stream. */
+export declare interface SubscriptionFilter {
+    /** Receive `notifications/tools/list_changed` when the server produces it. */
+    readonly toolsListChanged?: boolean;
+    /** Receive `notifications/prompts/list_changed` when the server produces it. */
+    readonly promptsListChanged?: boolean;
+    /** Receive `notifications/resources/list_changed` when the server produces it. */
+    readonly resourcesListChanged?: boolean;
+    /** Receive `notifications/resources/updated` for these resource URIs. */
+    readonly resourceSubscriptions?: readonly string[];
+}
+
+/** The terminating result returned when a `subscriptions/listen` stream closes gracefully. */
+export declare interface SubscriptionsListenResult {
+    readonly resultType: 'complete';
+    readonly _meta: SubscriptionsListenResultMetaObject;
+}
+
+/** The required metadata on a graceful `subscriptions/listen` result. */
+export declare interface SubscriptionsListenResultMetaObject extends Readonly<Record<string, unknown>> {
+    /** The JSON-RPC id of the `subscriptions/listen` request whose stream is closing. */
+    readonly 'io.modelcontextprotocol/subscriptionId': string | number;
+}
+
 /**
  * The MCP protocol revisions this server can negotiate.
  *
  * @remarks
  * `initialize` echoes the client's requested `protocolVersion` when it appears in
- * this list, else falls back to {@link MCP_PROTOCOL_VERSION}. Frozen so the list is
- * an immutable contract. The package does not advertise `2025-03-26` because that
- * revision mandates JSON-RPC batching, while this package accepts only individual
- * JSON-RPC messages.
+ * this list. Frozen in client-preference and discovery-advertisement order. The
+ * package does not advertise `2025-03-26` because that revision mandates JSON-RPC
+ * batching, while this package accepts only individual JSON-RPC messages.
  */
-export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly MCPVersion[];
 
 export { }