@orkestrel/mcp 0.0.7 → 0.0.9

package/dist/src/core/index.js

@@ -1,20 +1,80 @@
-import { isArray, isNumber, isRecord, isString, isUndefined } from "@orkestrel/contract";
+import { arrayOf, attempt, enumerableKeys, isArray, isBoolean, isNumber, isRecord, isString, isUndefined, sanitizeBudget } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
-import { Tool } from "@orkestrel/agent";
+import { signToken, verifyToken } from "@orkestrel/server";
+import { Tool } from "@orkestrel/tool";
 //#region src/core/constants.ts
-/** The MCP protocol revision this server implements (the default negotiated version). */
-var MCP_PROTOCOL_VERSION = "2025-06-18";
+/**
+* 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.
+*/
+var MCP_PROTOCOL_VERSION = "2025-11-25";
+/** The legacy fallback anchor used when an initialize request cannot be accepted as modern. */
+var MCP_LEGACY_VERSION = "2025-06-18";
+/** The modern revision offered by an unpinned client during discovery. */
+var MCP_MODERN_VERSION = "2026-07-28";
 /**
 * 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.
+*/
+var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([
+	"2026-07-28",
+	"2025-11-25",
+	"2025-06-18"
+]);
+/** Reserved modern `_meta` key carrying the request's protocol revision. */
+var MCP_META_VERSION = "io.modelcontextprotocol/protocolVersion";
+/** Reserved modern `_meta` key carrying the client's open capability record. */
+var MCP_META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+/** Reserved modern `_meta` key carrying the optional client identity. */
+var MCP_META_CLIENT = "io.modelcontextprotocol/clientInfo";
+/** Reserved modern `_meta` key carrying the server identity on results. */
+var MCP_META_SERVER = "io.modelcontextprotocol/serverInfo";
+/** Reserved modern `_meta` key carrying a `subscriptions/listen` request id. */
+var MCP_META_SUBSCRIPTION = "io.modelcontextprotocol/subscriptionId";
+/** MCP reserved error: required HTTP metadata does not match the request body. */
+var MCP_HEADER_MISMATCH = -32020;
+/** MCP reserved error: an operation needs a client capability that was not declared. */
+var MCP_MISSING_CAPABILITY = -32021;
+/** MCP reserved error: a request names an unsupported protocol revision. */
+var MCP_UNSUPPORTED_VERSION = -32022;
+/**
+* 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.
+*/
+var DEFAULT_MCP_CACHE_TTL = 6e4;
+/**
+* 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.
 */
-var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-06-18"]);
+var DEFAULT_MCP_LIMITS = Object.freeze({
+	message: 1048576,
+	metadata: 16384,
+	keys: 64,
+	state: 16384,
+	content: 4194304,
+	subscriptions: 128,
+	depth: 32
+});
 /** JSON-RPC 2.0 reserved error: invalid JSON was received (the message did not parse). */
 var JSONRPC_PARSE_ERROR = -32700;
 /** JSON-RPC 2.0 reserved error: the payload was not a valid Request object. */
@@ -34,6 +94,8 @@ var DEFAULT_MCP_CLIENT_VERSION = "1.0.0";
 * is unset — a request the remote server does not answer within it rejects.
 */
 var DEFAULT_MCP_REQUEST_TIMEOUT = 3e4;
+/** The maximum discovery-probe deadline used when a client deadline is configured. */
+var DEFAULT_MCP_PROBE_TIMEOUT = 50;
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -44,13 +106,19 @@ var DEFAULT_MCP_REQUEST_TIMEOUT = 3e4;
 * {@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' }
 * ```
 */
 var MCPError = class extends Error {
@@ -92,6 +160,161 @@ function isMCPError(value) {
 //#endregion
 //#region src/core/validators.ts
 /**
+* 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
+* ```
+*/
+function isBoundedString(value, bytes) {
+	if (!isString(value) || !Number.isFinite(bytes) || !Number.isInteger(bytes) || bytes < 0) return false;
+	let measured = 0;
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code <= 127) measured += 1;
+		else if (code <= 2047) measured += 2;
+		else if (code >= 55296 && code <= 56319) {
+			const next = value.charCodeAt(index + 1);
+			if (next >= 56320 && next <= 57343) {
+				measured += 4;
+				index += 1;
+			} else measured += 3;
+		} else measured += 3;
+		if (measured > bytes) return false;
+	}
+	return true;
+}
+/**
+* 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
+* ```
+*/
+function isBoundedJSON(value, limits) {
+	const outcome = attempt(() => {
+		const limit = sanitizeBudget(limits.bytes, 0);
+		const depth = sanitizeBudget(limits.depth, 0);
+		const breadth = limits.keys === void 0 ? void 0 : sanitizeBudget(limits.keys, 0);
+		let bytes = 0;
+		let keys = 0;
+		const ancestors = /* @__PURE__ */ new WeakSet();
+		const pending = [{
+			value,
+			depth: 0,
+			closing: false
+		}];
+		while (pending.length > 0) {
+			const frame = pending.pop();
+			if (frame === void 0) return false;
+			const entry = frame.value;
+			if (frame.closing) {
+				if (typeof entry !== "object" || entry === null) return false;
+				ancestors.delete(entry);
+				continue;
+			}
+			if (frame.depth > depth) return false;
+			if (entry === null) bytes += 4;
+			else if (isBoolean(entry)) bytes += entry ? 4 : 5;
+			else if (isNumber(entry)) bytes += Number.isFinite(entry) ? String(entry).length : 4;
+			else if (isString(entry)) {
+				bytes += 2;
+				if (bytes > limit) return false;
+				for (let index = 0; index < entry.length; index += 1) {
+					const code = entry.charCodeAt(index);
+					if (code === 34 || code === 92 || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) bytes += 2;
+					else if (code <= 31) bytes += 6;
+					else if (code <= 127) bytes += 1;
+					else if (code <= 2047) bytes += 2;
+					else if (code >= 55296 && code <= 56319) {
+						const next = entry.charCodeAt(index + 1);
+						if (next >= 56320 && next <= 57343) {
+							bytes += 4;
+							index += 1;
+						} else bytes += 6;
+					} else if (code >= 56320 && code <= 57343) bytes += 6;
+					else bytes += 3;
+					if (bytes > limit) return false;
+				}
+				continue;
+			} else if (typeof entry === "object") {
+				if (ancestors.has(entry)) return false;
+				const names = enumerableKeys(entry);
+				if (names === void 0) return false;
+				for (const name of names) if (name === "__proto__" || name === "constructor" || name === "prototype") return false;
+				if (Array.isArray(entry)) {
+					bytes += 2 + Math.max(0, entry.length - 1);
+					if (bytes > limit || names.length !== entry.length) return false;
+					ancestors.add(entry);
+					pending.push({
+						value: entry,
+						depth: frame.depth,
+						closing: true
+					});
+					for (let index = entry.length - 1; index >= 0; index -= 1) {
+						const descriptor = Object.getOwnPropertyDescriptor(entry, String(index));
+						if (descriptor === void 0 || !Object.hasOwn(descriptor, "value")) return false;
+						pending.push({
+							value: descriptor.value,
+							depth: frame.depth + 1,
+							closing: false
+						});
+					}
+					continue;
+				}
+				if (!isRecord(entry)) return false;
+				keys += names.length;
+				if (breadth !== void 0 && keys > breadth) return false;
+				bytes += 2 + Math.max(0, names.length - 1) + names.length;
+				if (bytes > limit) return false;
+				ancestors.add(entry);
+				pending.push({
+					value: entry,
+					depth: frame.depth,
+					closing: true
+				});
+				for (let index = names.length - 1; index >= 0; index -= 1) {
+					const name = names[index];
+					if (name === void 0) return false;
+					const descriptor = Object.getOwnPropertyDescriptor(entry, name);
+					if (descriptor === void 0 || !Object.hasOwn(descriptor, "value")) return false;
+					pending.push({
+						value: descriptor.value,
+						depth: frame.depth + 1,
+						closing: false
+					});
+					pending.push({
+						value: name,
+						depth: frame.depth,
+						closing: false
+					});
+				}
+				continue;
+			} else return false;
+			if (bytes > limit) return false;
+		}
+		return bytes <= limit;
+	});
+	return outcome.success && outcome.value;
+}
+/**
 * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,
 * or absent.
 *
@@ -115,6 +338,263 @@ function isRequestId(value) {
 	return isUndefined(value) || isString(value) || isNumber(value);
 }
 /**
+* 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}
+*/
+function isMCPVersion(value) {
+	return isString(value) && SUPPORTED_PROTOCOL_VERSIONS.some((version) => version === value);
+}
+/**
+* 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
+*/
+function isSubscriptionFilter(value) {
+	if (!isRecord(value)) return false;
+	const tools = value["toolsListChanged"];
+	if (!isUndefined(tools) && !isBoolean(tools)) return false;
+	const prompts = value["promptsListChanged"];
+	if (!isUndefined(prompts) && !isBoolean(prompts)) return false;
+	const resources = value["resourcesListChanged"];
+	if (!isUndefined(resources) && !isBoolean(resources)) return false;
+	const subscriptions = value["resourceSubscriptions"];
+	return isUndefined(subscriptions) || arrayOf(isString)(subscriptions);
+}
+/**
+* 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
+* ```
+*/
+function isFormElicitationSupported(value) {
+	try {
+		if (!isRecord(value)) return false;
+		const elicitation = value["elicitation"];
+		if (!isRecord(elicitation)) return false;
+		if (isRecord(elicitation["form"])) return true;
+		return Object.keys(elicitation).length === 0;
+	} catch {
+		return false;
+	}
+}
+/**
+* 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
+* ```
+*/
+function isElicitPrimitiveSchema(value) {
+	try {
+		if (!isRecord(value)) return false;
+		const title = value["title"];
+		const description = value["description"];
+		if (!isUndefined(title) && !isString(title)) return false;
+		if (!isUndefined(description) && !isString(description)) return false;
+		const fallback = value["default"];
+		if (value["type"] === "boolean") return isUndefined(fallback) || isBoolean(fallback);
+		if (value["type"] === "number" || value["type"] === "integer") {
+			const minimum = value["minimum"];
+			const maximum = value["maximum"];
+			return (isUndefined(minimum) || isNumber(minimum)) && (isUndefined(maximum) || isNumber(maximum)) && (isUndefined(fallback) || isNumber(fallback));
+		}
+		if (value["type"] === "string") {
+			const minimum = value["minLength"];
+			const maximum = value["maxLength"];
+			const format = value["format"];
+			const choices = value["enum"];
+			const names = value["enumNames"];
+			const titled = value["oneOf"];
+			return (isUndefined(minimum) || isNumber(minimum)) && (isUndefined(maximum) || isNumber(maximum)) && (isUndefined(format) || format === "uri" || format === "email" || format === "date" || format === "date-time") && (isUndefined(fallback) || isString(fallback)) && (isUndefined(choices) || arrayOf(isString)(choices)) && (isUndefined(names) || arrayOf(isString)(names)) && (isUndefined(titled) || arrayOf(isRecord)(titled) && titled.every((choice) => isString(choice["const"]) && isString(choice["title"])));
+		}
+		if (value["type"] !== "array") return false;
+		const minimum = value["minItems"];
+		const maximum = value["maxItems"];
+		const items = value["items"];
+		if (!isUndefined(minimum) && !isNumber(minimum) || !isUndefined(maximum) && !isNumber(maximum) || !isUndefined(fallback) && !arrayOf(isString)(fallback) || !isRecord(items)) return false;
+		if (items["type"] === "string") return arrayOf(isString)(items["enum"]);
+		const choices = items["anyOf"];
+		return arrayOf(isRecord)(choices) && choices.every((choice) => isString(choice["const"]) && isString(choice["title"]));
+	} catch {
+		return false;
+	}
+}
+/**
+* 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
+* ```
+*/
+function isElicitRequestFormParams(value) {
+	try {
+		if (!isRecord(value)) return false;
+		const mode = value["mode"];
+		if (!isUndefined(mode) && mode !== "form") return false;
+		if (!isString(value["message"])) return false;
+		const schema = value["requestedSchema"];
+		if (!isRecord(schema) || schema["type"] !== "object" || !isRecord(schema["properties"])) return false;
+		const dialect = schema["$schema"];
+		if (!isUndefined(dialect) && !isString(dialect)) return false;
+		const required = schema["required"];
+		return (isUndefined(required) || arrayOf(isString)(required)) && Object.values(schema["properties"]).every((property) => isElicitPrimitiveSchema(property));
+	} catch {
+		return false;
+	}
+}
+/**
+* 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' })
+* ```
+*/
+function isElicitRequestURLParams(value) {
+	return isRecord(value) && value["mode"] === "url" && isString(value["message"]) && isString(value["url"]);
+}
+/**
+* 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
+* ```
+*/
+function isElicitRequest(value) {
+	if (!isRecord(value) || value["method"] !== "elicitation/create") return false;
+	return isElicitRequestFormParams(value["params"]) || isElicitRequestURLParams(value["params"]);
+}
+/**
+* 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
+* ```
+*/
+function isInputRequest(value) {
+	if (isElicitRequest(value)) return true;
+	if (!isRecord(value)) return false;
+	const params = value["params"];
+	if (value["method"] === "sampling/createMessage") return isRecord(params);
+	return value["method"] === "roots/list" && (isUndefined(params) || isRecord(params));
+}
+/**
+* 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
+* ```
+*/
+function isInputRequests(value) {
+	try {
+		return isRecord(value) && Object.values(value).every((request) => isInputRequest(request));
+	} catch {
+		return false;
+	}
+}
+/**
+* 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
+* ```
+*/
+function isElicitResult(value) {
+	try {
+		if (!isRecord(value)) return false;
+		const action = value["action"];
+		if (action !== "accept" && action !== "decline" && action !== "cancel") return false;
+		const content = value["content"];
+		if (isUndefined(content)) return true;
+		if (!isRecord(content)) return false;
+		return Object.values(content).every((item) => isString(item) || isNumber(item) || isBoolean(item) || arrayOf(isString)(item));
+	} catch {
+		return false;
+	}
+}
+/**
+* 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
+* ```
+*/
+function isInputRequiredResult(value) {
+	try {
+		if (!isRecord(value) || value["resultType"] !== "input_required") return false;
+		const inputRequests = value["inputRequests"];
+		const requestState = value["requestState"];
+		if (!isUndefined(inputRequests) && !isInputRequests(inputRequests)) return false;
+		if (!isUndefined(requestState) && !isString(requestState)) return false;
+		return !isUndefined(inputRequests) || !isUndefined(requestState);
+	} catch {
+		return false;
+	}
+}
+/**
 * Determine whether a parsed value is a {@link JSONRPCRequest}.
 *
 * @remarks
@@ -193,6 +673,28 @@ function isJSONRPCMessage(value) {
 function isInitializeRequest(value) {
 	return isJSONRPCRequest(value) && value.method === "initialize";
 }
+/**
+* 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
+*/
+function isModernRequest(value) {
+	try {
+		if (!isJSONRPCRequest(value)) return false;
+		const metadata = value.params?.["_meta"];
+		return isRecord(metadata) && Object.hasOwn(metadata, "io.modelcontextprotocol/protocolVersion");
+	} catch {
+		return false;
+	}
+}
 //#endregion
 //#region src/core/parsers.ts
 /**
@@ -218,6 +720,122 @@ function isInitializeRequest(value) {
 function parseJSONRPCMessage(value) {
 	return isJSONRPCMessage(value) ? value : void 0;
 }
+/**
+* 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`
+*/
+function parseRequestContext(value) {
+	try {
+		if (!isModernRequest(value)) return void 0;
+		const metadata = value.params?.["_meta"];
+		if (!isRecord(metadata)) return void 0;
+		const version = metadata[MCP_META_VERSION];
+		const capabilities = metadata[MCP_META_CAPABILITIES];
+		if (!isString(version) || !isRecord(capabilities)) return void 0;
+		const client = metadata[MCP_META_CLIENT];
+		if (client === void 0) return {
+			version,
+			capabilities
+		};
+		if (!isRecord(client)) return void 0;
+		const name = client["name"];
+		const clientVersion = client["version"];
+		if (!isString(name) || !isString(clientVersion)) return void 0;
+		return {
+			version,
+			capabilities,
+			identity: {
+				name,
+				version: clientVersion
+			}
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* 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' }
+* ```
+*/
+function parseMCPInputState(value) {
+	try {
+		if (!isString(value)) return void 0;
+		const parsed = JSON.parse(value);
+		if (!isRecord(parsed)) return void 0;
+		const principal = parsed["principal"];
+		const ttl = parsed["ttl"];
+		const origin = parsed["origin"];
+		const key = parsed["key"];
+		const name = parsed["name"];
+		const state = parsed["state"];
+		if (!isString(principal) || !isNumber(ttl) || !Number.isFinite(ttl)) return void 0;
+		if (!isString(origin) && !isNumber(origin)) return void 0;
+		if (!isString(key) || !isString(name)) return void 0;
+		if (!isUndefined(state) && !isString(state)) return void 0;
+		return {
+			principal,
+			ttl,
+			origin,
+			key,
+			name,
+			...isString(state) ? { state } : {}
+		};
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/core/inferers.ts
+/**
+* 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
+*/
+function inferEra(version) {
+	switch (version) {
+		case "2026-07-28": return "modern";
+		case "2025-11-25":
+		case "2025-06-18": return "legacy";
+		default: return;
+	}
+}
+/**
+* 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`
+*/
+function inferVersion(offered) {
+	for (const version of SUPPORTED_PROTOCOL_VERSIONS) if (offered.includes(version)) return version;
+}
 //#endregion
 //#region src/core/helpers.ts
 /**
@@ -228,7 +846,7 @@ function parseJSONRPCMessage(value) {
 * @param result - The method's return value
 * @returns The success response envelope
 */
-function jsonRPCResult(id, result) {
+function buildJSONRPCResult(id, result) {
 	return {
 		jsonrpc: "2.0",
 		id,
@@ -245,7 +863,7 @@ function jsonRPCResult(id, result) {
 * @param data - An OPTIONAL machine-readable payload (omitted from the envelope when absent)
 * @returns The error response envelope
 */
-function jsonRPCError(id, code, message, data) {
+function buildJSONRPCError(id, code, message, data) {
 	return {
 		jsonrpc: "2.0",
 		id,
@@ -264,7 +882,7 @@ function jsonRPCError(id, code, message, data) {
 * — renaming `parameters` to the wire's `inputSchema`.
 *
 * @remarks
-* Each {@link import('@orkestrel/agent').ToolDefinition} carries through its
+* Each {@link import('@orkestrel/tool').ToolDefinition} carries through its
 * `name` and (when present) `description`; its open JSON-Schema `parameters`
 * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)
 * when a tool declares none (MCP requires an `inputSchema`).
@@ -283,32 +901,154 @@ function buildToolDescriptors(manager) {
 	});
 }
 /**
-* Map an executed tool's {@link ToolResult} to an MCP {@link MCPToolResult} — the
-* value (or error) as a `text` content block.
+* 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
-* `result.error` (so the server adds NO try/catch around `execute`): when `error`
-* is present, this builds an `isError: true` result carrying the error text, so the
+* 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; otherwise it serializes `result.value` (via `JSON.stringify`) into one
-* `text` block.
+* 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
 */
-function buildToolResult(result) {
-	if (result.error !== void 0) return {
+function buildCallResult(result) {
+	if (!result.success) return {
 		content: [{
 			type: "text",
 			text: result.error
 		}],
 		isError: true
 	};
-	return { content: [{
+	if (result.value === void 0) return { content: [{
 		type: "text",
-		text: result.value === void 0 ? "" : JSON.stringify(result.value)
+		text: ""
 	}] };
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(result.value)
+		}],
+		structuredContent: result.value
+	};
+}
+function buildModernResult(result, identity, ttl, scope) {
+	const currentMetadata = isRecord(result) ? result["_meta"] : void 0;
+	const metadata = {
+		...isRecord(currentMetadata) ? currentMetadata : {},
+		[MCP_META_SERVER]: identity
+	};
+	if (ttl === void 0) return {
+		...result,
+		resultType: "complete",
+		_meta: metadata
+	};
+	return {
+		...result,
+		resultType: "complete",
+		ttlMs: ttl,
+		cacheScope: scope ?? "private",
+		_meta: metadata
+	};
+}
+/**
+* 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
+*/
+function buildSubscriptionFilter(requested, supported) {
+	const toolsListChanged = requested.toolsListChanged === true && supported.toolsListChanged === true;
+	const promptsListChanged = requested.promptsListChanged === true && supported.promptsListChanged === true;
+	const resourcesListChanged = requested.resourcesListChanged === true && supported.resourcesListChanged === true;
+	const supportedResources = new Set(supported.resourceSubscriptions ?? []);
+	const resourceSubscriptions = requested.resourceSubscriptions?.filter((uri) => supportedResources.has(uri));
+	return {
+		...toolsListChanged ? { toolsListChanged: true } : {},
+		...promptsListChanged ? { promptsListChanged: true } : {},
+		...resourcesListChanged ? { resourcesListChanged: true } : {},
+		...resourceSubscriptions !== void 0 && resourceSubscriptions.length > 0 ? { resourceSubscriptions } : {}
+	};
+}
+/**
+* Determine whether a produced notification belongs to an honoured subscription filter.
+*
+* @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
+*/
+function matchesSubscriptionNotification(notification, filter) {
+	if (notification.method === "notifications/tools/list_changed") return filter.toolsListChanged === true;
+	if (notification.method === "notifications/prompts/list_changed") return filter.promptsListChanged === true;
+	if (notification.method === "notifications/resources/list_changed") return filter.resourcesListChanged === true;
+	if (notification.method !== "notifications/resources/updated") return false;
+	const uri = notification.params?.["uri"];
+	return typeof uri === "string" && filter.resourceSubscriptions?.includes(uri) === true;
+}
+/**
+* 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
+*/
+function stampSubscriptionNotification(notification, id) {
+	const metadata = notification.params?.["_meta"];
+	return {
+		jsonrpc: notification.jsonrpc,
+		method: notification.method,
+		params: {
+			...notification.params,
+			_meta: {
+				...isRecord(metadata) ? metadata : {},
+				[MCP_META_SUBSCRIPTION]: id
+			}
+		}
+	};
+}
+/**
+* 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
+*/
+function buildSubscriptionAcknowledgement(notifications, id) {
+	return stampSubscriptionNotification({
+		jsonrpc: "2.0",
+		method: "notifications/subscriptions/acknowledged",
+		params: { notifications }
+	}, id);
+}
+/**
+* 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
+*/
+function buildSubscriptionResult(id, identity) {
+	return buildJSONRPCResult(id, buildModernResult({ _meta: { [MCP_META_SUBSCRIPTION]: id } }, identity));
+}
+/**
+* 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
+*/
+function buildDiscoverResult(options) {
+	return buildModernResult({
+		supportedVersions: SUPPORTED_PROTOCOL_VERSIONS.filter(isMCPVersion),
+		capabilities: { tools: {} },
+		...options.instructions === void 0 ? {} : { instructions: options.instructions }
+	}, options.identity, options.cache?.ttl ?? 6e4, options.cache?.scope);
 }
 /**
 * Build the MCP `initialize` result — the negotiated protocol version, the
@@ -316,7 +1056,8 @@ function buildToolResult(result) {
 *
 * @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}.
+* 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).
 *
@@ -325,9 +1066,10 @@ function buildToolResult(result) {
 * @param requested - The client's requested protocol version (negotiated when supported)
 * @returns The `initialize` result payload
 */
-function initializeResult(name, version, requested) {
+function buildInitializeResult(name, version, requested) {
+	const newestLegacy = SUPPORTED_PROTOCOL_VERSIONS.find((candidate) => inferEra(candidate) === "legacy") ?? "2025-06-18";
 	return {
-		protocolVersion: requested !== void 0 && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : MCP_PROTOCOL_VERSION,
+		protocolVersion: isMCPVersion(requested) && inferEra(requested) === "legacy" ? requested : newestLegacy,
 		capabilities: { tools: {} },
 		serverInfo: {
 			name,
@@ -336,6 +1078,64 @@ function initializeResult(name, version, requested) {
 	};
 }
 /**
+* 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
+* }
+* ```
+*/
+async function* serializeStream(stream) {
+	let next = await stream.next();
+	while (!next.done) {
+		yield JSON.stringify(next.value);
+		next = await stream.next();
+	}
+	return JSON.stringify(next.value);
+}
+/**
+* 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)
+* ```
+*/
+async function sendStream(stream, transport) {
+	let next = await stream.next();
+	while (!next.done) {
+		await transport.send(next.value);
+		next = await stream.next();
+	}
+	await transport.send(next.value);
+}
+/**
 * Pipe an {@link MCPTransportInterface} into an {@link MCPServerInterface} — every
 * inbound message runs through `server.handle`, and a defined reply is written back
 * via `transport.send`.
@@ -343,7 +1143,11 @@ function initializeResult(name, version, requested) {
 * @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
@@ -372,8 +1176,10 @@ function bindServer(server, transport) {
 	transport.listen(async (message) => {
 		if (!active) return;
 		try {
-			const response = await server.handle(message);
-			if (response !== void 0) await transport.send(response);
+			const answer = await server.handle(message);
+			if (answer === void 0) return;
+			if (typeof answer === "string") await transport.send(answer);
+			else await sendStream(answer, transport);
 		} catch (error) {
 			try {
 				server.emitter.emit("error", error);
@@ -462,6 +1268,40 @@ function bindClient(client, transport) {
 	};
 }
 //#endregion
+//#region src/core/MCPMethodManager.ts
+/**
+* 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
+* ```
+*/
+var MCPMethodManager = class {
+	#handlers = /* @__PURE__ */ new Map();
+	add(name, handler) {
+		this.#handlers.set(name, handler);
+	}
+	method(name) {
+		return this.#handlers.get(name);
+	}
+};
+//#endregion
 //#region src/core/MCPServer.ts
 /**
 * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
@@ -474,14 +1314,15 @@ function bindClient(client, transport) {
 *   `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 the result `error`, 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
@@ -492,97 +1333,259 @@ function bindClient(client, transport) {
 * ```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":{}}'
 * ```
 */
 var MCPServer = class {
 	#emitter;
-	#name;
-	#version;
-	#tools;
+	#options;
+	#methods;
+	#limits;
+	#subscriptions = 0;
 	constructor(options) {
 		this.#emitter = new Emitter({
 			...options.on !== void 0 ? { on: options.on } : {},
 			...options.error !== void 0 ? { error: options.error } : {}
 		});
-		this.#name = options.name;
-		this.#version = options.version;
-		this.#tools = options.tools;
+		this.#options = options;
+		this.#limits = {
+			message: sanitizeBudget(options.limit?.message, DEFAULT_MCP_LIMITS.message),
+			metadata: sanitizeBudget(options.limit?.metadata, DEFAULT_MCP_LIMITS.metadata),
+			keys: sanitizeBudget(options.limit?.keys, DEFAULT_MCP_LIMITS.keys),
+			state: sanitizeBudget(options.limit?.state, DEFAULT_MCP_LIMITS.state),
+			content: sanitizeBudget(options.limit?.content, DEFAULT_MCP_LIMITS.content),
+			subscriptions: sanitizeBudget(options.limit?.subscriptions, DEFAULT_MCP_LIMITS.subscriptions),
+			depth: sanitizeBudget(options.limit?.depth, DEFAULT_MCP_LIMITS.depth)
+		};
+		this.#methods = new MCPMethodManager();
+		this.#register();
 	}
 	get emitter() {
 		return this.#emitter;
 	}
-	get name() {
-		return this.#name;
+	get identity() {
+		return this.#options.identity;
 	}
-	get version() {
-		return this.#version;
+	get methods() {
+		return this.#methods;
 	}
-	async dispatch(request) {
+	async dispatch(request, options = {}) {
 		const id = request.id ?? null;
-		this.#emitter.emit("request", request.method, id);
+		const modern = isModernRequest(request);
+		const era = modern ? "modern" : "legacy";
+		this.#emitter.emit("request", request.method, id, era);
 		if (request.id === void 0) return;
+		const metadata = request.params?.["_meta"];
+		if (metadata !== void 0 && !isBoundedJSON(metadata, {
+			bytes: this.#limits.metadata,
+			keys: this.#limits.keys,
+			depth: this.#limits.depth
+		})) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: `_meta` exceeds the configured limit or contains an unsafe value");
+		return modern ? this.#modern(request, id, options) : this.#legacy(request, id);
+	}
+	async handle(message, options) {
+		if (!isBoundedString(message, this.#limits.message)) return JSON.stringify(buildJSONRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"));
+		let parsed;
+		try {
+			parsed = JSON.parse(message);
+		} catch {
+			return JSON.stringify(buildJSONRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"));
+		}
+		const decoded = parseJSONRPCMessage(parsed);
+		if (decoded === void 0 || !("method" in decoded)) return JSON.stringify(buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, "Invalid Request"));
+		const answer = await this.dispatch(decoded, options);
+		if (answer === void 0) return void 0;
+		return Symbol.asyncIterator in answer ? serializeStream(answer) : JSON.stringify(answer);
+	}
+	async #legacy(request, id) {
 		switch (request.method) {
 			case "initialize": {
 				const requested = request.params?.["protocolVersion"];
-				return jsonRPCResult(id, initializeResult(this.#name, this.#version, isString(requested) ? requested : void 0));
+				return buildJSONRPCResult(id, buildInitializeResult(this.#options.identity.name, this.#options.identity.version, isString(requested) ? requested : void 0));
 			}
-			case "ping": return jsonRPCResult(id, {});
-			case "tools/list": return jsonRPCResult(id, { tools: buildToolDescriptors(this.#tools) });
-			case "tools/call": return this.#call(request, id);
-			default: return jsonRPCError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`);
+			case "ping": return buildJSONRPCResult(id, {});
+			case "tools/list": return buildJSONRPCResult(id, { tools: buildToolDescriptors(this.#options.tools) });
+			case "tools/call": {
+				const result = await this.#runTool(request, id);
+				return "jsonrpc" in result ? result : buildJSONRPCResult(id, result);
+			}
+			default: return buildJSONRPCError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`);
 		}
 	}
-	async handle(message) {
-		let parsed;
+	#register() {
+		this.#methods.add("server/discover", (request) => this.#discover(request));
+		this.#methods.add("tools/list", (request) => this.#list(request));
+		this.#methods.add("tools/call", (request, options) => this.#call(request, options));
+		this.#methods.add("subscriptions/listen", (request, options) => this.#subscribe(request, options));
+	}
+	async #modern(request, id, options) {
+		const context = parseRequestContext(request);
+		if (context === void 0) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: malformed modern request metadata");
+		if (inferEra(context.version) === void 0) return buildJSONRPCError(id, MCP_UNSUPPORTED_VERSION, `Unsupported protocol version: ${context.version}`, {
+			supported: SUPPORTED_PROTOCOL_VERSIONS,
+			requested: context.version
+		});
+		const handler = this.#methods.method(request.method);
+		if (handler === void 0) return buildJSONRPCError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`);
+		return handler(request, options);
+	}
+	async #discover(request) {
+		return buildJSONRPCResult(request.id ?? null, buildDiscoverResult(this.#options));
+	}
+	async #list(request) {
+		return buildJSONRPCResult(request.id ?? null, buildModernResult({ tools: buildToolDescriptors(this.#options.tools) }, this.#options.identity, this.#options.cache?.ttl ?? 6e4, this.#options.cache?.scope));
+	}
+	async #call(request, options = {}) {
+		const id = request.id ?? null;
+		const input = await this.#input(request, options);
+		if (input !== void 0) return input;
+		const result = await this.#runTool(request, id);
+		return "jsonrpc" in result ? result : buildJSONRPCResult(id, buildModernResult(result, this.#options.identity));
+	}
+	async #input(request, options) {
+		const configured = this.#options.input;
+		if (configured === void 0) return void 0;
+		const id = request.id;
+		if (id === void 0) return void 0;
+		const params = request.params;
+		const name = params?.["name"];
+		if (!isString(name)) return void 0;
+		const rawArguments = params?.["arguments"];
+		const args = isRecord(rawArguments) ? rawArguments : {};
+		const requestState = params?.["requestState"];
+		const inputResponses = params?.["inputResponses"];
+		if (requestState === void 0 && inputResponses === void 0) {
+			const elicitation = await configured.elicit({
+				request,
+				name,
+				arguments: args
+			}, options);
+			if (elicitation === void 0) return void 0;
+			const principal = await configured.principal(request);
+			return this.#required(request, name, elicitation, principal);
+		}
+		if (!isBoundedString(requestState, this.#limits.state) || !isRecord(inputResponses)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: `inputResponses` and `requestState` are required together");
+		const state = parseMCPInputState(await verifyToken(requestState, configured.secret));
+		const principal = await configured.principal(request);
+		if (state === void 0 || state.principal !== principal || state.ttl !== configured.ttl || state.origin === id || state.name !== name || !Object.hasOwn(inputResponses, state.key)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: request state could not be verified for this retry");
+		const response = inputResponses[state.key];
+		if (!isElicitResult(response)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: the elicitation response is missing or malformed");
+		const elicitation = await configured.elicit({
+			request,
+			name,
+			arguments: args,
+			response,
+			...state.state !== void 0 ? { state: state.state } : {}
+		}, options);
+		return elicitation === void 0 ? void 0 : this.#required(request, name, elicitation, principal);
+	}
+	async #required(request, name, elicitation, principal) {
+		const id = request.id;
+		if (id === void 0) return buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, "Invalid Request");
+		const context = parseRequestContext(request);
+		if (context === void 0 || !isFormElicitationSupported(context.capabilities)) return buildJSONRPCError(id, MCP_MISSING_CAPABILITY, "Server requires the elicitation capability for this request", { requiredCapabilities: { elicitation: {} } });
+		if (!isElicitRequestFormParams(elicitation.request) || principal.length === 0 || !Number.isFinite(this.#options.input?.ttl) || (this.#options.input?.ttl ?? 0) <= 0) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: elicitation policy returned an invalid form or signing context");
+		const configured = this.#options.input;
+		if (configured === void 0) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: input is not configured");
+		const key = crypto.randomUUID();
+		const protectedState = {
+			principal,
+			ttl: configured.ttl,
+			origin: id,
+			key,
+			name,
+			...elicitation.state !== void 0 ? { state: elicitation.state } : {}
+		};
+		if (!isBoundedJSON(protectedState, {
+			bytes: this.#limits.state,
+			depth: this.#limits.depth
+		})) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: request state exceeds the configured limit");
+		const requestState = await signToken(JSON.stringify(protectedState), {
+			secret: configured.secret,
+			ttl: configured.ttl
+		});
+		if (!isBoundedString(requestState, this.#limits.state)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: request state exceeds the configured limit");
+		return buildJSONRPCResult(id, {
+			resultType: "input_required",
+			inputRequests: { [key]: {
+				method: "elicitation/create",
+				params: {
+					...elicitation.request,
+					mode: "form"
+				}
+			} },
+			requestState,
+			_meta: { [MCP_META_SERVER]: this.#options.identity }
+		});
+	}
+	async #subscribe(request, options) {
+		const id = request.id;
+		if (id === void 0) return buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, "Invalid Request");
+		const requested = request.params?.["notifications"];
+		if (!isSubscriptionFilter(requested)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: a valid `notifications` filter is required");
+		return this.#subscription(requested, id, options);
+	}
+	async *#subscription(requested, id, options) {
+		if (this.#subscriptions >= this.#limits.subscriptions) return buildJSONRPCError(id, JSONRPC_SERVER_ERROR, "Server limit reached: too many live subscriptions");
+		this.#subscriptions += 1;
 		try {
-			parsed = JSON.parse(message);
-		} catch {
-			return JSON.stringify(jsonRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"));
+			const configured = this.#options.subscription;
+			const notifications = buildSubscriptionFilter(requested, configured?.notifications ?? {});
+			yield buildSubscriptionAcknowledgement(notifications, id);
+			if (configured !== void 0) {
+				const source = await configured.listen(notifications, options);
+				for await (const notification of source) if (matchesSubscriptionNotification(notification, notifications)) yield stampSubscriptionNotification(notification, id);
+			}
+			return buildSubscriptionResult(id, this.#options.identity);
+		} finally {
+			this.#subscriptions -= 1;
 		}
-		const decoded = parseJSONRPCMessage(parsed);
-		if (decoded === void 0 || !("method" in decoded)) return JSON.stringify(jsonRPCError(null, JSONRPC_INVALID_REQUEST, "Invalid Request"));
-		const response = await this.dispatch(decoded);
-		return response === void 0 ? void 0 : JSON.stringify(response);
 	}
-	async #call(request, id) {
+	async #runTool(request, id) {
 		const params = request.params;
 		const name = params?.["name"];
-		if (!isString(name)) return jsonRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: a string `name` is required");
+		if (!isString(name)) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: a string `name` is required");
 		const rawArguments = params?.["arguments"];
 		const args = isRecord(rawArguments) ? rawArguments : {};
 		const callId = request.id === void 0 ? crypto.randomUUID() : String(request.id);
-		return jsonRPCResult(id, buildToolResult(await this.#tools.execute({
+		const result = await this.#options.tools.execute({
 			id: callId,
 			name,
 			arguments: args
-		})));
+		});
+		if (!result.success && !isBoundedString(result.error, this.#limits.content)) return buildJSONRPCError(id, JSONRPC_SERVER_ERROR, "Server limit exceeded: tool content is too large");
+		if (result.success && result.value !== void 0 && !isBoundedJSON(result.value, {
+			bytes: this.#limits.content,
+			depth: this.#limits.depth
+		})) return buildJSONRPCError(id, JSONRPC_SERVER_ERROR, "Server limit exceeded: tool content is too large or unsafe");
+		const built = attempt(() => buildCallResult(result));
+		return built.success ? built.value : buildJSONRPCError(id, JSONRPC_SERVER_ERROR, "Server could not serialize tool content");
 	}
 };
 //#endregion
 //#region src/core/MCPClient.ts
 /**
 * 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/agent').ToolManagerInterface}
-*   isolates it into a result `error` just like a local throw).
+*   locally, so an agent's {@link import('@orkestrel/tool').ToolManagerInterface}
+*   isolates it into a `success: false` result just like a local throw).
 * - **Request↔response correlation.** Each request is tagged with a monotonic numeric
 *   `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`).
@@ -592,7 +1595,7 @@ var MCPServer = class {
 *
 * @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
@@ -602,22 +1605,32 @@ var MCPServer = class {
 var MCPClient = class {
 	#emitter;
 	#transport;
-	#name;
-	#version;
+	#identity;
+	#capabilities;
+	#pin;
 	#timeout;
+	#probe;
 	#pending = /* @__PURE__ */ new Map();
 	#nextId = 0;
 	#connected = false;
-	#protocol = void 0;
+	#version = void 0;
+	#era = void 0;
+	#offer;
 	constructor(options) {
 		this.#emitter = new Emitter({
 			...options.on !== void 0 ? { on: options.on } : {},
 			...options.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#transport = options.transport;
-		this.#name = options.name ?? "taverna";
-		this.#version = options.version ?? "1.0.0";
+		this.#identity = options.identity ?? {
+			name: "taverna",
+			version: "1.0.0"
+		};
+		this.#capabilities = options.capabilities ?? {};
+		this.#pin = options.version;
+		this.#offer = options.version ?? "2026-07-28";
 		this.#timeout = options.timeout ?? 3e4;
+		this.#probe = options.timeout === void 0 ? void 0 : Math.min(options.timeout, 50);
 		this.#transport.emitter.on("message", (message) => this.#receive(message));
 	}
 	get emitter() {
@@ -626,8 +1639,8 @@ var MCPClient = class {
 	get connected() {
 		return this.#connected;
 	}
-	get protocol() {
-		return this.#protocol;
+	get version() {
+		return this.#version;
 	}
 	get transport() {
 		return this.#transport;
@@ -638,38 +1651,68 @@ var MCPClient = class {
 	async connect() {
 		if (this.#connected) return;
 		await this.#transport.start();
-		const result = await this.#request("initialize", {
-			protocolVersion: MCP_PROTOCOL_VERSION,
-			capabilities: {},
-			clientInfo: {
-				name: this.#name,
-				version: this.#version
+		if (this.#era === "legacy" || this.#pin !== void 0 && inferEra(this.#pin) === "legacy") {
+			await this.#initialize(this.#pin ?? "2025-11-25");
+			return;
+		}
+		let discovery;
+		try {
+			try {
+				discovery = await this.discover();
+			} catch (error) {
+				if (!isMCPError(error) || error.code !== -32022) throw error;
+				if (this.#pin !== void 0) throw error;
+				const supported = isRecord(error.context) ? error.context["supported"] : void 0;
+				const retry = isArray(supported) ? inferVersion(supported.filter((version) => isString(version))) : void 0;
+				if (retry === void 0) throw error;
+				this.#offer = retry;
+				discovery = await this.discover();
 			}
-		});
-		const protocol = isRecord(result) ? result["protocolVersion"] : void 0;
-		if (!isString(protocol) || !SUPPORTED_PROTOCOL_VERSIONS.includes(protocol)) {
-			await this.#transport.close();
-			if (isString(protocol)) throw new Error(`MCP server negotiated unsupported protocol version '${protocol}'`);
-			throw new Error("MCP server returned a non-string protocol version");
+		} catch (error) {
+			if (!(this.#pin !== "2026-07-28" && this.#era === void 0 && (!isMCPError(error) || error.code !== -32022))) throw error;
+			await this.#initialize(MCP_PROTOCOL_VERSION);
+			return;
 		}
-		this.#protocol = protocol;
+		const version = inferVersion(discovery.supportedVersions);
+		if (version === void 0) throw new MCPError("MCP server supports no compatible protocol version", MCP_UNSUPPORTED_VERSION, { supported: discovery.supportedVersions });
+		this.#version = version;
+		this.#era = "modern";
 		this.#connected = true;
-		await this.#transport.send({
-			jsonrpc: "2.0",
-			method: "notifications/initialized"
-		});
 		this.#emitter.emit("connect");
 	}
+	async discover() {
+		const result = await this.#request("server/discover", void 0, this.#probe, this.#version ?? this.#offer);
+		if (!isRecord(result)) throw new MCPError("MCP server returned a malformed discovery result", JSONRPC_INVALID_PARAMS, result);
+		const advertised = result["supportedVersions"];
+		const capabilities = result["capabilities"];
+		const ttl = result["ttlMs"];
+		const scope = result["cacheScope"];
+		const instructions = result["instructions"];
+		const metadata = result["_meta"];
+		const resultType = result["resultType"];
+		if (!isArray(advertised) || !isRecord(capabilities) || !isNumber(ttl) || scope !== "public" && scope !== "private" || resultType !== void 0 && resultType !== "complete" || instructions !== void 0 && !isString(instructions) || metadata !== void 0 && !isRecord(metadata)) throw new MCPError("MCP server returned a malformed discovery result", JSONRPC_INVALID_PARAMS, result);
+		const supportedVersions = [];
+		for (const version of advertised) if (isMCPVersion(version)) supportedVersions.push(version);
+		return {
+			supportedVersions,
+			capabilities,
+			resultType: resultType ?? "complete",
+			ttlMs: ttl,
+			cacheScope: scope,
+			...instructions === void 0 ? {} : { instructions },
+			...metadata === void 0 ? {} : { _meta: metadata }
+		};
+	}
 	async disconnect() {
 		if (!this.#connected) return;
 		this.#connected = false;
-		this.#protocol = void 0;
+		this.#version = void 0;
 		for (const id of this.#pending.keys()) this.#settle(id, /* @__PURE__ */ new Error("MCP client disconnected"), true);
 		await this.#transport.close();
 		this.#emitter.emit("disconnect");
 	}
 	async tools() {
-		const result = await this.#request("tools/list");
+		const result = await this.#request("tools/list", void 0, this.#timeout);
 		if (!isRecord(result) || !isArray(result["tools"])) return [];
 		const tools = [];
 		for (const descriptor of result["tools"]) {
@@ -683,7 +1726,7 @@ var MCPClient = class {
 		const result = await this.#request("tools/call", {
 			name,
 			arguments: args
-		});
+		}, this.#timeout);
 		const text = this.#text(result);
 		if (isRecord(result) && result["isError"] === true) throw new Error(text.length > 0 ? text : `MCP tool '${name}' failed`);
 		if (text.length === 0) return void 0;
@@ -693,24 +1736,46 @@ var MCPClient = class {
 			return text;
 		}
 	}
-	#request(method, params) {
+	#request(method, params, deadline, version) {
 		this.#nextId += 1;
 		const id = this.#nextId;
+		const timeout = deadline;
+		const modern = version ?? (this.#era === "modern" ? this.#version : void 0);
+		const stamped = modern === void 0 ? params : {
+			...params ?? {},
+			_meta: {
+				[MCP_META_VERSION]: modern,
+				[MCP_META_CAPABILITIES]: this.#capabilities,
+				[MCP_META_CLIENT]: this.#identity
+			}
+		};
 		const request = {
 			jsonrpc: "2.0",
 			id,
 			method,
-			...params === void 0 ? {} : { params }
+			...stamped === void 0 ? {} : { params: stamped }
 		};
 		return new Promise((resolve, reject) => {
-			const deadline = AbortSignal.timeout(this.#timeout);
-			const timeout = this.#timeoutRequest.bind(this, id, method);
-			deadline.addEventListener("abort", timeout, { once: true });
+			if (timeout === void 0) {
+				this.#pending.set(id, {
+					resolve,
+					reject,
+					method
+				});
+				this.#transport.send(request).catch((error) => {
+					this.#settle(id, error instanceof Error ? error : new Error(String(error)), true);
+				});
+				return;
+			}
+			const signal = AbortSignal.timeout(timeout);
+			const abort = this.#timeoutRequest.bind(this, id, method, timeout);
+			signal.addEventListener("abort", abort, { once: true });
 			this.#pending.set(id, {
 				resolve,
 				reject,
-				deadline,
-				timeout
+				method,
+				deadline: signal,
+				timeout: abort
 			});
 			this.#transport.send(request).catch((error) => {
 				this.#settle(id, error instanceof Error ? error : new Error(String(error)), true);
@@ -719,9 +1784,15 @@ var MCPClient = class {
 	}
 	#receive(message) {
 		if (isJSONRPCResponse(message) && isRequestId(message.id)) {
-			if (this.#pending.has(message.id)) {
+			const pending = this.#pending.get(message.id);
+			if (pending !== void 0) {
+				if (pending.method === "server/discover" && (message.error === void 0 || message.error.code !== -32601 && message.error.code !== -32600)) this.#era = "modern";
 				if (message.error !== void 0) this.#settle(message.id, new MCPError(message.error.message, message.error.code, message.error.data), true);
-				else this.#settle(message.id, message.result, false);
+				else {
+					const resultType = isRecord(message.result) ? message.result["resultType"] : void 0;
+					if (isRecord(message.result) && Object.hasOwn(message.result, "resultType") && resultType !== "complete") this.#settle(message.id, new MCPError(`MCP result type '${String(resultType)}' is not supported`, JSONRPC_INVALID_PARAMS, { resultType }), true);
+					else this.#settle(message.id, message.result, false);
+				}
 				return;
 			}
 		}
@@ -744,14 +1815,42 @@ var MCPClient = class {
 		for (const block of result["content"]) if (isRecord(block) && isString(block["text"])) parts.push(block["text"]);
 		return parts.join("\n");
 	}
-	#timeoutRequest(id, method) {
-		this.#settle(id, /* @__PURE__ */ new Error(`MCP request '${method}' timed out after ${this.#timeout}ms`), true);
+	async #initialize(version) {
+		const result = await this.#request("initialize", {
+			protocolVersion: version,
+			capabilities: {},
+			clientInfo: this.#identity
+		}, this.#timeout);
+		const protocol = isRecord(result) ? result["protocolVersion"] : void 0;
+		if (protocol === void 0) {
+			await this.#transport.close();
+			throw new Error("MCP server returned no protocol version");
+		}
+		if (!isString(protocol)) {
+			await this.#transport.close();
+			throw new Error("MCP server returned a malformed protocol version");
+		}
+		if (!isMCPVersion(protocol) || inferEra(protocol) !== "legacy") {
+			await this.#transport.close();
+			throw new Error(`MCP server negotiated unsupported protocol version '${protocol}'`);
+		}
+		this.#version = protocol;
+		this.#era = "legacy";
+		this.#connected = true;
+		await this.#transport.send({
+			jsonrpc: "2.0",
+			method: "notifications/initialized"
+		});
+		this.#emitter.emit("connect");
+	}
+	#timeoutRequest(id, method, timeout) {
+		this.#settle(id, /* @__PURE__ */ new Error(`MCP request '${method}' timed out after ${timeout}ms`), true);
 	}
 	#settle(id, value, failed) {
 		const pending = this.#pending.get(id);
 		if (pending === void 0) return;
 		this.#pending.delete(id);
-		pending.deadline.removeEventListener("abort", pending.timeout);
+		if (pending.deadline !== void 0 && pending.timeout !== void 0) pending.deadline.removeEventListener("abort", pending.timeout);
 		if (failed) pending.reject(value);
 		else pending.resolve(value);
 	}
@@ -760,20 +1859,20 @@ var MCPClient = class {
 //#region src/core/factories.ts
 /**
 * Create a transport-agnostic Model Context Protocol server — exposes a live
-* {@link import('@orkestrel/agent').ToolManagerInterface} over JSON-RPC 2.0
+* {@link import('@orkestrel/tool').ToolManagerInterface} over JSON-RPC 2.0
 * (`initialize` / `ping` / `tools/list` / `tools/call`).
 *
 * @remarks
 * Pump raw message strings through `handle` (parse → dispatch → serialize) from a
 * transport, or call the typed `dispatch` directly with an already-parsed request.
 * The server is provider-agnostic — JSON-RPC plus the tool registry, with no HTTP
-* and no model. The {@link import('@orkestrel/agent').ToolManagerInterface} already
-* isolates a thrown tool into a result error (surfaced as an MCP `isError: true`
-* tool result), so a misbehaving tool never crashes a dispatch. Subscribe to the
+* and no model. The {@link import('@orkestrel/tool').ToolManagerInterface} already
+* isolates a thrown tool into a `success: false` result (surfaced as an MCP
+* `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}
 *
@@ -784,7 +1883,7 @@ var MCPClient = class {
 * 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`:
@@ -799,7 +1898,7 @@ function createMCPServer(options) {
 * Create a transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE
 * MCP server over an injected {@link import('./types.js').ClientTransportInterface},
 * runs the `initialize` handshake, and exposes the server's tools as local
-* {@link import('@orkestrel/agent').ToolInterface}s an agent can run.
+* {@link import('@orkestrel/tool').ToolInterface}s an agent can run.
 *
 * @remarks
 * The egress mirror of {@link createMCPServer}: where the server exposes a local tool
@@ -807,14 +1906,14 @@ function createMCPServer(options) {
 * validates and exposes the negotiated protocol, `tools()` lists + wraps the remote
 * tools (each `execute` calls back over the wire),
 * and `call(name, args)` runs a remote `tools/call` (a remote tool failure throws
-* locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}
+* locally, so an agent's {@link import('@orkestrel/tool').ToolManagerInterface}
 * isolates it). The transport is injected — a concrete one (the HTTP transport over
 * `fetch`) lives in `@src/server`; the client itself is provider-agnostic. Subscribe
 * 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}
 *
@@ -876,6 +1975,6 @@ function createDuplexClientTransport(transport) {
 	};
 }
 //#endregion
-export { DEFAULT_MCP_CLIENT_NAME, DEFAULT_MCP_CLIENT_VERSION, DEFAULT_MCP_REQUEST_TIMEOUT, JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, JSONRPC_SERVER_ERROR, MCPClient, MCPError, MCPServer, MCP_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, bindClient, bindServer, buildToolDescriptors, buildToolResult, createDuplexClientTransport, createMCPClient, createMCPServer, initializeResult, isInitializeRequest, isJSONRPCMessage, isJSONRPCRequest, isJSONRPCResponse, isMCPError, isRequestId, jsonRPCError, jsonRPCResult, parseJSONRPCMessage };
+export { DEFAULT_MCP_CACHE_TTL, DEFAULT_MCP_CLIENT_NAME, DEFAULT_MCP_CLIENT_VERSION, DEFAULT_MCP_LIMITS, DEFAULT_MCP_PROBE_TIMEOUT, DEFAULT_MCP_REQUEST_TIMEOUT, JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, JSONRPC_SERVER_ERROR, MCPClient, MCPError, MCPMethodManager, MCPServer, MCP_HEADER_MISMATCH, MCP_LEGACY_VERSION, MCP_META_CAPABILITIES, MCP_META_CLIENT, MCP_META_SERVER, MCP_META_SUBSCRIPTION, MCP_META_VERSION, MCP_MISSING_CAPABILITY, MCP_MODERN_VERSION, MCP_PROTOCOL_VERSION, MCP_UNSUPPORTED_VERSION, SUPPORTED_PROTOCOL_VERSIONS, bindClient, bindServer, buildCallResult, buildDiscoverResult, buildInitializeResult, buildJSONRPCError, buildJSONRPCResult, buildModernResult, buildSubscriptionAcknowledgement, buildSubscriptionFilter, buildSubscriptionResult, buildToolDescriptors, createDuplexClientTransport, createMCPClient, createMCPServer, inferEra, inferVersion, isBoundedJSON, isBoundedString, isElicitPrimitiveSchema, isElicitRequest, isElicitRequestFormParams, isElicitRequestURLParams, isElicitResult, isFormElicitationSupported, isInitializeRequest, isInputRequest, isInputRequests, isInputRequiredResult, isJSONRPCMessage, isJSONRPCRequest, isJSONRPCResponse, isMCPError, isMCPVersion, isModernRequest, isRequestId, isSubscriptionFilter, matchesSubscriptionNotification, parseJSONRPCMessage, parseMCPInputState, parseRequestContext, sendStream, serializeStream, stampSubscriptionNotification };
 
 //# sourceMappingURL=index.js.map