@orkestrel/mcp 0.0.30 → 0.0.32

package/dist/src/core/index.cjs

@@ -275,9 +275,12 @@ var DEFAULT_MCP_SUBSCRIPTION_CAPACITY = 64;
 * optional structured context.
 *
 * @remarks
-* {@link MCPClient} throws this error for a remote JSON-RPC `error` response and for a
-* locally detected protocol incompatibility. Local lifecycle and transport conditions such
-* as disconnects and request timeouts remain plain `Error`s. For a remote response, `context`
+* {@link MCPClient} throws this error for a remote JSON-RPC `error` response, for a locally
+* detected protocol incompatibility, and for a session-bound request refused because the
+* client holds no connection — that one carries `-32600`, so a caller separates "reconnect"
+* from "retry" without reading a message. Local lifecycle and transport conditions that
+* settle a request already in flight, such as a disconnect and a request timeout, remain
+* plain `Error`s. For a remote response, `context`
 * carries the optional `error.data` 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
@@ -323,11 +326,7 @@ var MCPError = class extends Error {
 * ```
 */
 function isMCPError(value) {
-	try {
-		return value instanceof MCPError;
-	} catch {
-		return false;
-	}
+	return (0, _orkestrel_contract.isInstance)(value, MCPError);
 }
 //#endregion
 //#region src/core/cloners.ts
@@ -578,7 +577,7 @@ function parseMCPInputState(value) {
 		const name = parsed["name"];
 		const digest = parsed["digest"];
 		const state = parsed["state"];
-		if (!(0, _orkestrel_contract.isString)(principal) || principal.length === 0 || !(0, _orkestrel_contract.isNumber)(expiry) || !Number.isFinite(expiry)) return;
+		if (!(0, _orkestrel_contract.isString)(principal) || principal.length === 0 || !(0, _orkestrel_contract.isFiniteNumber)(expiry)) return;
 		if (!isJSONRPCId(id)) return void 0;
 		if (!(0, _orkestrel_contract.isString)(version) || !(0, _orkestrel_contract.isString)(method) || !(0, _orkestrel_contract.isString)(name)) return void 0;
 		if (!(0, _orkestrel_contract.isString)(digest) || !(0, _orkestrel_contract.isUndefined)(state) && !(0, _orkestrel_contract.isJSONValue)(state)) return void 0;
@@ -741,9 +740,9 @@ function serializeJSON(value, limits) {
 		const limit = limits.bytes;
 		const depth = limits.depth;
 		const breadth = limits.keys;
-		if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 0) return void 0;
-		if (!Number.isFinite(depth) || !Number.isInteger(depth) || depth < 0) return void 0;
-		if (breadth !== void 0 && (!Number.isFinite(breadth) || !Number.isInteger(breadth) || breadth < 0)) return void 0;
+		if (!(0, _orkestrel_contract.isInteger)(limit) || limit < 0) return void 0;
+		if (!(0, _orkestrel_contract.isInteger)(depth) || depth < 0) return void 0;
+		if (breadth !== void 0 && (!(0, _orkestrel_contract.isInteger)(breadth) || breadth < 0)) return void 0;
 		let bytes = 0;
 		let keys = 0;
 		const chunks = [];
@@ -857,7 +856,7 @@ function serializeJSON(value, limits) {
 				continue;
 			}
 			if ((0, _orkestrel_contract.isNumber)(entry)) {
-				if (!Number.isFinite(entry)) return void 0;
+				if (!(0, _orkestrel_contract.isFiniteNumber)(entry)) return void 0;
 				const text = JSON.stringify(entry);
 				if (!(0, _orkestrel_contract.isString)(text)) return void 0;
 				bytes += text.length;
@@ -873,10 +872,10 @@ function serializeJSON(value, limits) {
 				});
 				continue;
 			}
-			if (typeof entry !== "object" || ancestors.has(entry)) return void 0;
-			if (Array.isArray(entry)) {
+			if (!(0, _orkestrel_contract.isObject)(entry) || ancestors.has(entry)) return void 0;
+			if ((0, _orkestrel_contract.isArray)(entry)) {
 				const lengthDescriptor = Reflect.getOwnPropertyDescriptor(entry, "length");
-				if (lengthDescriptor === void 0 || !Object.hasOwn(lengthDescriptor, "value") || !(0, _orkestrel_contract.isNumber)(lengthDescriptor.value) || !Number.isInteger(lengthDescriptor.value) || lengthDescriptor.value < 0 || lengthDescriptor.value > 4294967295 || lengthDescriptor.enumerable === true || lengthDescriptor.configurable === true) return void 0;
+				if (lengthDescriptor === void 0 || !Object.hasOwn(lengthDescriptor, "value") || !(0, _orkestrel_contract.isNumber)(lengthDescriptor.value) || !(0, _orkestrel_contract.isInteger)(lengthDescriptor.value) || lengthDescriptor.value < 0 || lengthDescriptor.value > 4294967295 || lengthDescriptor.enumerable === true || lengthDescriptor.configurable === true) return void 0;
 				const length = lengthDescriptor.value;
 				keys += length;
 				bytes += 2 + (length === 0 ? 0 : length - 1);
@@ -893,7 +892,7 @@ function serializeJSON(value, limits) {
 						continue;
 					}
 					const index = Number(name);
-					if (!Number.isInteger(index) || index < 0 || index >= length || String(index) !== name) return void 0;
+					if (!(0, _orkestrel_contract.isInteger)(index) || index < 0 || index >= length || String(index) !== name) return void 0;
 				}
 				if (!foundLength) return void 0;
 				const values = [];
@@ -1114,10 +1113,9 @@ function buildCallOutcome(name, result) {
 	if ((0, _orkestrel_contract.isRecord)(result) && result["isError"] === true) throw new Error(text.length > 0 ? text : `MCP tool '${name}' failed`);
 	let value;
 	if ((0, _orkestrel_contract.isRecord)(result) && Object.hasOwn(result, "structuredContent")) value = result["structuredContent"];
-	else if (text.length > 0) try {
-		value = JSON.parse(text);
-	} catch {
-		value = text;
+	else if (text.length > 0) {
+		const parsed = (0, _orkestrel_contract.parseJSON)(text);
+		value = parsed === void 0 ? text : parsed;
 	}
 	return Object.freeze({
 		resultType: "complete",
@@ -1128,19 +1126,17 @@ function buildCallOutcome(name, result) {
 * Builds the canonical Tool call for one validated MCP `tools/call` request.
 *
 * @param request - The original MCP request
-* @param caller - Optional consumer-asserted caller context
 * @param args - Optional once-validated modern arguments; omission retains legacy normalization
 * @returns The canonical call, or `undefined` when the name is invalid
 */
-function buildToolCall(request, caller, args) {
+function buildToolCall(request, args) {
 	const name = request.params?.["name"];
-	if (typeof name !== "string") return void 0;
+	if (!(0, _orkestrel_contract.isString)(name)) return void 0;
 	const rawArguments = request.params?.["arguments"];
 	return {
 		id: String(request.id),
 		name,
-		arguments: args ?? ((0, _orkestrel_contract.isRecord)(rawArguments) ? rawArguments : {}),
-		...caller === void 0 ? {} : { caller }
+		arguments: args ?? ((0, _orkestrel_contract.isRecord)(rawArguments) ? rawArguments : {})
 	};
 }
 /**
@@ -1231,7 +1227,8 @@ function buildMethodOptions(options, lifetime) {
 *
 * @remarks
 * Each {@link import('@orkestrel/tool').ToolDefinition} carries through its
-* `name` and (when present) `description`; its open JSON-Schema `parameters`
+* `name`, optional `title` and `description`, and mapped annotation hints;
+* its open JSON-Schema `parameters`
 * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)
 * when a tool declares none (MCP requires an `inputSchema`).
 *
@@ -1240,14 +1237,50 @@ function buildMethodOptions(options, lifetime) {
 */
 function buildToolDescriptors(manager) {
 	return manager.definitions().map((definition) => {
-		const descriptor = {
+		const annotations = definition.annotations === void 0 ? {} : toolAnnotationsToMCP(definition.annotations);
+		return {
 			name: definition.name,
-			inputSchema: definition.parameters ?? { type: "object" }
+			inputSchema: definition.parameters ?? { type: "object" },
+			...definition.title === void 0 ? {} : { title: definition.title },
+			...definition.description === void 0 ? {} : { description: definition.description },
+			...Object.keys(annotations).length === 0 ? {} : { annotations }
 		};
-		if (definition.description !== void 0) descriptor.description = definition.description;
-		return descriptor;
 	});
 }
+/**
+* Projects domain tool annotations onto MCP wire hints without inventing defaults.
+*
+* @param annotations - The authored domain annotations
+* @returns The mapped hints; `untrusted` has no MCP counterpart
+*
+* @example
+* ```ts
+* toolAnnotationsToMCP({ pure: true, consequential: false }) // { readOnlyHint: true, destructiveHint: false }
+* ```
+*/
+function toolAnnotationsToMCP(annotations) {
+	return {
+		...annotations.pure === void 0 ? {} : { readOnlyHint: annotations.pure },
+		...annotations.consequential === void 0 ? {} : { destructiveHint: annotations.consequential }
+	};
+}
+/**
+* Projects MCP wire hints onto domain tool annotations without inventing defaults.
+*
+* @param annotations - The validated MCP wire annotations
+* @returns The mapped annotations; unmapped wire hints are omitted
+*
+* @example
+* ```ts
+* mcpAnnotationsToTool({ readOnlyHint: false, destructiveHint: true }) // { pure: false, consequential: true }
+* ```
+*/
+function mcpAnnotationsToTool(annotations) {
+	return {
+		...annotations.readOnlyHint === void 0 ? {} : { pure: annotations.readOnlyHint },
+		...annotations.destructiveHint === void 0 ? {} : { consequential: annotations.destructiveHint }
+	};
+}
 function buildModernResult(result, identity, ttl, scope) {
 	const currentMetadata = (0, _orkestrel_contract.isRecord)(result) ? result["_meta"] : void 0;
 	if (!(0, _orkestrel_contract.isJSONValue)(identity)) throw new TypeError("MCP identity must be exact JSON");
@@ -1283,7 +1316,7 @@ function modernResultToLegacy(result) {
 	const projected = {};
 	for (const [key, value] of Object.entries(result)) {
 		if (key === "resultType" || key === "ttlMs" || key === "cacheScope") continue;
-		if (key === "content" && Array.isArray(value)) {
+		if (key === "content" && (0, _orkestrel_contract.isArray)(value)) {
 			projected[key] = value.map((entry) => (0, _orkestrel_contract.isRecord)(entry) && entry["type"] === "text" && (0, _orkestrel_contract.isString)(entry["text"]) ? {
 				type: "text",
 				text: entry["text"]
@@ -1396,7 +1429,7 @@ function matchesSubscriptionNotification(notification, filter) {
 	if (notification.method === "notifications/resources/list_changed") return filter.resourcesListChanged === true;
 	if (notification.method === "notifications/resources/updated") {
 		const uri = notification.params?.["uri"];
-		return typeof uri === "string" && filter.resourceSubscriptions?.includes(uri) === true;
+		return (0, _orkestrel_contract.isString)(uri) && filter.resourceSubscriptions?.includes(uri) === true;
 	}
 	if (notification.method === "notifications/tasks") return isMCPTaskNotification(notification) && filter.taskIds?.includes(notification.params.taskId) === true;
 	return false;
@@ -1452,10 +1485,11 @@ function buildSubscriptionResult(id, identity) {
 * @remarks
 * `capabilities.resources` and `capabilities.prompts` appear only for servers with their
 * respective managers and derive notification flags from the configured subscription filter.
-* `capabilities.completions` is independent and appears only with a completion provider.
-* `capabilities.extensions` appears only for a server that configured the extension it
-* would name. An advertisement is a promise a client is entitled to act on, so a server
-* with no `task` policy omits the member entirely rather than advertising an empty
+* `tools.listChanged` is always advertised because the server produces the family from its
+* own registry. `capabilities.completions` is independent and appears only with a completion
+* provider. `capabilities.extensions` appears only for a server that configured the
+* extension it would name. An advertisement is a promise a client is entitled to act on, so
+* a server with no `task` policy omits the member entirely rather than advertising an empty
 * record — and its discovery answer stays byte-for-byte what it was before the extension
 * existed.
 *
@@ -1466,7 +1500,7 @@ function buildDiscoverResult(options) {
 	return buildModernResult({
 		supportedVersions: SUPPORTED_MODERN_PROTOCOL_VERSIONS,
 		capabilities: {
-			tools: {},
+			tools: { listChanged: true },
 			...options.resources === void 0 ? {} : { resources: {
 				...options.subscription?.notifications.resourceSubscriptions === void 0 ? {} : { subscribe: true },
 				...options.subscription?.notifications.resourcesListChanged === true ? { listChanged: true } : {}
@@ -2109,7 +2143,7 @@ function bindServer(server, transport) {
 		try {
 			const answer = await server.handle(message, { signal: request.signal });
 			if (answer === void 0) return;
-			if (typeof answer === "string") {
+			if ((0, _orkestrel_contract.isString)(answer)) {
 				if (!request.signal.aborted) await transport.send(answer);
 			} else if (request.signal.aborted) await answer[Symbol.asyncDispose]();
 			else await sendStream(answer, transport);
@@ -2510,7 +2544,7 @@ function isMCPAnnotations(value) {
 		const audience = annotations["audience"];
 		const priority = annotations["priority"];
 		const lastModified = annotations["lastModified"];
-		if (!(0, _orkestrel_contract.isUndefined)(audience) && (!Array.isArray(audience) || !audience.every((role) => role === "user" || role === "assistant"))) return false;
+		if (!(0, _orkestrel_contract.isUndefined)(audience) && (!(0, _orkestrel_contract.isArray)(audience) || !audience.every((role) => role === "user" || role === "assistant"))) return false;
 		if (!(0, _orkestrel_contract.isUndefined)(priority) && (!(0, _orkestrel_contract.isFiniteNumber)(priority) || priority < 0 || priority > 1)) return false;
 		return (0, _orkestrel_contract.isUndefined)(lastModified) || (0, _orkestrel_contract.isString)(lastModified);
 	} catch {
@@ -2532,7 +2566,7 @@ function isMCPIcon(value) {
 		const mimeType = icon["mimeType"];
 		const sizes = icon["sizes"];
 		const theme = icon["theme"];
-		return ((0, _orkestrel_contract.isUndefined)(mimeType) || (0, _orkestrel_contract.isString)(mimeType)) && ((0, _orkestrel_contract.isUndefined)(sizes) || Array.isArray(sizes) && sizes.every((size) => (0, _orkestrel_contract.isString)(size))) && ((0, _orkestrel_contract.isUndefined)(theme) || theme === "light" || theme === "dark");
+		return ((0, _orkestrel_contract.isUndefined)(mimeType) || (0, _orkestrel_contract.isString)(mimeType)) && ((0, _orkestrel_contract.isUndefined)(sizes) || (0, _orkestrel_contract.isArray)(sizes) && sizes.every((size) => (0, _orkestrel_contract.isString)(size))) && ((0, _orkestrel_contract.isUndefined)(theme) || theme === "light" || theme === "dark");
 	} catch {
 		return false;
 	}
@@ -2548,7 +2582,7 @@ function isMCPIdentity(value) {
 		const description = identity["description"];
 		const website = identity["websiteUrl"];
 		const icons = identity["icons"];
-		return ((0, _orkestrel_contract.isUndefined)(title) || (0, _orkestrel_contract.isString)(title)) && ((0, _orkestrel_contract.isUndefined)(description) || (0, _orkestrel_contract.isString)(description)) && ((0, _orkestrel_contract.isUndefined)(website) || isAbsoluteURI(website)) && ((0, _orkestrel_contract.isUndefined)(icons) || Array.isArray(icons) && icons.every((icon) => isMCPIcon(icon)));
+		return ((0, _orkestrel_contract.isUndefined)(title) || (0, _orkestrel_contract.isString)(title)) && ((0, _orkestrel_contract.isUndefined)(description) || (0, _orkestrel_contract.isString)(description)) && ((0, _orkestrel_contract.isUndefined)(website) || isAbsoluteURI(website)) && ((0, _orkestrel_contract.isUndefined)(icons) || (0, _orkestrel_contract.isArray)(icons) && icons.every((icon) => isMCPIcon(icon)));
 	} catch {
 		return false;
 	}
@@ -2659,12 +2693,34 @@ function isMCPResource(value) {
 		const resource = owned.value;
 		const icons = resource["icons"];
 		const size = resource["size"];
-		return isAbsoluteURI(resource["uri"]) && (0, _orkestrel_contract.isString)(resource["name"]) && ((0, _orkestrel_contract.isUndefined)(resource["title"]) || (0, _orkestrel_contract.isString)(resource["title"])) && ((0, _orkestrel_contract.isUndefined)(resource["description"]) || (0, _orkestrel_contract.isString)(resource["description"])) && ((0, _orkestrel_contract.isUndefined)(resource["mimeType"]) || (0, _orkestrel_contract.isString)(resource["mimeType"])) && ((0, _orkestrel_contract.isUndefined)(resource["annotations"]) || isMCPAnnotations(resource["annotations"])) && ((0, _orkestrel_contract.isUndefined)(size) || (0, _orkestrel_contract.isInteger)(size) && size >= 0) && ((0, _orkestrel_contract.isUndefined)(icons) || Array.isArray(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(resource["_meta"]) || isMCPMetaObject(resource["_meta"]));
+		return isAbsoluteURI(resource["uri"]) && (0, _orkestrel_contract.isString)(resource["name"]) && ((0, _orkestrel_contract.isUndefined)(resource["title"]) || (0, _orkestrel_contract.isString)(resource["title"])) && ((0, _orkestrel_contract.isUndefined)(resource["description"]) || (0, _orkestrel_contract.isString)(resource["description"])) && ((0, _orkestrel_contract.isUndefined)(resource["mimeType"]) || (0, _orkestrel_contract.isString)(resource["mimeType"])) && ((0, _orkestrel_contract.isUndefined)(resource["annotations"]) || isMCPAnnotations(resource["annotations"])) && ((0, _orkestrel_contract.isUndefined)(size) || (0, _orkestrel_contract.isInteger)(size) && size >= 0) && ((0, _orkestrel_contract.isUndefined)(icons) || (0, _orkestrel_contract.isArray)(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(resource["_meta"]) || isMCPMetaObject(resource["_meta"]));
 	} catch {
 		return false;
 	}
 }
 /**
+* Checks whether a value carries valid consumed MCP 2026-07-28 tool annotation hints.
+*
+* @remarks
+* Validates only `readOnlyHint` and `destructiveHint`; other wire fields are not consumed, so
+* the open `objectOf` combinator carries them through unread. Every declared member is
+* optional, a hostile read answers `false` rather than throwing, and an array is refused.
+*
+* @param value - The unknown wire annotations
+* @returns True if consumed annotation fields are optional booleans; false otherwise
+*
+* @example
+* ```ts
+* isMCPToolAnnotations({ readOnlyHint: false }) // true
+* ```
+*/
+function isMCPToolAnnotations(value) {
+	return (0, _orkestrel_contract.objectOf)({
+		readOnlyHint: _orkestrel_contract.isBoolean,
+		destructiveHint: _orkestrel_contract.isBoolean
+	}, true)(value);
+}
+/**
 * Determines whether a value is one resource-template descriptor.
 *
 * @remarks
@@ -2680,7 +2736,7 @@ function isMCPResourceTemplate(value) {
 	try {
 		const template = owned.value;
 		const icons = template["icons"];
-		return (0, _orkestrel_contract.isString)(template["uriTemplate"]) && template["uriTemplate"].length > 0 && (0, _orkestrel_contract.isString)(template["name"]) && ((0, _orkestrel_contract.isUndefined)(template["title"]) || (0, _orkestrel_contract.isString)(template["title"])) && ((0, _orkestrel_contract.isUndefined)(template["description"]) || (0, _orkestrel_contract.isString)(template["description"])) && ((0, _orkestrel_contract.isUndefined)(template["mimeType"]) || (0, _orkestrel_contract.isString)(template["mimeType"])) && ((0, _orkestrel_contract.isUndefined)(template["annotations"]) || isMCPAnnotations(template["annotations"])) && ((0, _orkestrel_contract.isUndefined)(icons) || Array.isArray(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(template["_meta"]) || isMCPMetaObject(template["_meta"]));
+		return (0, _orkestrel_contract.isString)(template["uriTemplate"]) && template["uriTemplate"].length > 0 && (0, _orkestrel_contract.isString)(template["name"]) && ((0, _orkestrel_contract.isUndefined)(template["title"]) || (0, _orkestrel_contract.isString)(template["title"])) && ((0, _orkestrel_contract.isUndefined)(template["description"]) || (0, _orkestrel_contract.isString)(template["description"])) && ((0, _orkestrel_contract.isUndefined)(template["mimeType"]) || (0, _orkestrel_contract.isString)(template["mimeType"])) && ((0, _orkestrel_contract.isUndefined)(template["annotations"]) || isMCPAnnotations(template["annotations"])) && ((0, _orkestrel_contract.isUndefined)(icons) || (0, _orkestrel_contract.isArray)(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(template["_meta"]) || isMCPMetaObject(template["_meta"]));
 	} catch {
 		return false;
 	}
@@ -2720,7 +2776,7 @@ function isMCPResourcePage(value) {
 	if (!owned.success) return false;
 	const resources = owned.value["resources"];
 	const cursor = owned.value["nextCursor"];
-	return Array.isArray(resources) && resources.every((resource) => isMCPResource(resource)) && ((0, _orkestrel_contract.isUndefined)(cursor) || (0, _orkestrel_contract.isString)(cursor));
+	return (0, _orkestrel_contract.isArray)(resources) && resources.every((resource) => isMCPResource(resource)) && ((0, _orkestrel_contract.isUndefined)(cursor) || (0, _orkestrel_contract.isString)(cursor));
 }
 /**
 * Determines whether a value is one consumer-owned resource-template page.
@@ -2733,7 +2789,7 @@ function isMCPResourceTemplatePage(value) {
 	if (!owned.success) return false;
 	const templates = owned.value["resourceTemplates"];
 	const cursor = owned.value["nextCursor"];
-	return Array.isArray(templates) && templates.every((template) => isMCPResourceTemplate(template)) && ((0, _orkestrel_contract.isUndefined)(cursor) || (0, _orkestrel_contract.isString)(cursor));
+	return (0, _orkestrel_contract.isArray)(templates) && templates.every((template) => isMCPResourceTemplate(template)) && ((0, _orkestrel_contract.isUndefined)(cursor) || (0, _orkestrel_contract.isString)(cursor));
 }
 /**
 * Determines whether a value is a string-valued MCP argument record.
@@ -2769,7 +2825,7 @@ function isMCPPrompt(value) {
 	const prompt = owned.value;
 	const argumentsValue = prompt["arguments"];
 	const icons = prompt["icons"];
-	return (0, _orkestrel_contract.isString)(prompt["name"]) && ((0, _orkestrel_contract.isUndefined)(prompt["title"]) || (0, _orkestrel_contract.isString)(prompt["title"])) && ((0, _orkestrel_contract.isUndefined)(prompt["description"]) || (0, _orkestrel_contract.isString)(prompt["description"])) && ((0, _orkestrel_contract.isUndefined)(argumentsValue) || Array.isArray(argumentsValue) && argumentsValue.every((argument) => isMCPPromptArgument(argument))) && ((0, _orkestrel_contract.isUndefined)(icons) || Array.isArray(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(prompt["_meta"]) || isMCPMetaObject(prompt["_meta"]));
+	return (0, _orkestrel_contract.isString)(prompt["name"]) && ((0, _orkestrel_contract.isUndefined)(prompt["title"]) || (0, _orkestrel_contract.isString)(prompt["title"])) && ((0, _orkestrel_contract.isUndefined)(prompt["description"]) || (0, _orkestrel_contract.isString)(prompt["description"])) && ((0, _orkestrel_contract.isUndefined)(argumentsValue) || (0, _orkestrel_contract.isArray)(argumentsValue) && argumentsValue.every((argument) => isMCPPromptArgument(argument))) && ((0, _orkestrel_contract.isUndefined)(icons) || (0, _orkestrel_contract.isArray)(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(prompt["_meta"]) || isMCPMetaObject(prompt["_meta"]));
 }
 /**
 * Determines whether a value is one prompt message with existing rich content.
@@ -2792,7 +2848,7 @@ function isMCPPromptPage(value) {
 	if (!owned.success) return false;
 	const prompts = owned.value["prompts"];
 	const cursor = owned.value["nextCursor"];
-	return Array.isArray(prompts) && prompts.every((prompt) => isMCPPrompt(prompt)) && ((0, _orkestrel_contract.isUndefined)(cursor) || (0, _orkestrel_contract.isString)(cursor));
+	return (0, _orkestrel_contract.isArray)(prompts) && prompts.every((prompt) => isMCPPrompt(prompt)) && ((0, _orkestrel_contract.isUndefined)(cursor) || (0, _orkestrel_contract.isString)(cursor));
 }
 /**
 * Determines whether a value is one complete `prompts/get` result.
@@ -2805,7 +2861,7 @@ function isMCPPromptGetResult(value) {
 	if (!owned.success) return false;
 	const result = owned.value;
 	const messages = result["messages"];
-	return result["resultType"] === "complete" && ((0, _orkestrel_contract.isUndefined)(result["description"]) || (0, _orkestrel_contract.isString)(result["description"])) && Array.isArray(messages) && messages.every((message) => isMCPPromptMessage(message)) && ((0, _orkestrel_contract.isUndefined)(result["_meta"]) || isMCPResultMetaObject(result["_meta"]));
+	return result["resultType"] === "complete" && ((0, _orkestrel_contract.isUndefined)(result["description"]) || (0, _orkestrel_contract.isString)(result["description"])) && (0, _orkestrel_contract.isArray)(messages) && messages.every((message) => isMCPPromptMessage(message)) && ((0, _orkestrel_contract.isUndefined)(result["_meta"]) || isMCPResultMetaObject(result["_meta"]));
 }
 /**
 * Determines whether a value is a prompt or resource-template completion reference.
@@ -2850,7 +2906,7 @@ function isMCPCompletion(value) {
 	const completion = owned.value;
 	const values = completion["values"];
 	const total = completion["total"];
-	return Array.isArray(values) && values.every((candidate) => (0, _orkestrel_contract.isString)(candidate)) && ((0, _orkestrel_contract.isUndefined)(total) || (0, _orkestrel_contract.isInteger)(total) && total >= 0) && ((0, _orkestrel_contract.isUndefined)(completion["hasMore"]) || (0, _orkestrel_contract.isBoolean)(completion["hasMore"]));
+	return (0, _orkestrel_contract.isArray)(values) && values.every((candidate) => (0, _orkestrel_contract.isString)(candidate)) && ((0, _orkestrel_contract.isUndefined)(total) || (0, _orkestrel_contract.isInteger)(total) && total >= 0) && ((0, _orkestrel_contract.isUndefined)(completion["hasMore"]) || (0, _orkestrel_contract.isBoolean)(completion["hasMore"]));
 }
 /**
 * Determines whether a value is one complete, capped `completion/complete` result.
@@ -2888,7 +2944,7 @@ function isMCPContent(value) {
 			case "resource_link": {
 				const icons = content["icons"];
 				const size = content["size"];
-				return (0, _orkestrel_contract.isString)(content["name"]) && isAbsoluteURI(content["uri"]) && ((0, _orkestrel_contract.isUndefined)(content["title"]) || (0, _orkestrel_contract.isString)(content["title"])) && ((0, _orkestrel_contract.isUndefined)(content["description"]) || (0, _orkestrel_contract.isString)(content["description"])) && ((0, _orkestrel_contract.isUndefined)(content["mimeType"]) || (0, _orkestrel_contract.isString)(content["mimeType"])) && ((0, _orkestrel_contract.isUndefined)(icons) || Array.isArray(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(size) || (0, _orkestrel_contract.isInteger)(size) && size >= 0);
+				return (0, _orkestrel_contract.isString)(content["name"]) && isAbsoluteURI(content["uri"]) && ((0, _orkestrel_contract.isUndefined)(content["title"]) || (0, _orkestrel_contract.isString)(content["title"])) && ((0, _orkestrel_contract.isUndefined)(content["description"]) || (0, _orkestrel_contract.isString)(content["description"])) && ((0, _orkestrel_contract.isUndefined)(content["mimeType"]) || (0, _orkestrel_contract.isString)(content["mimeType"])) && ((0, _orkestrel_contract.isUndefined)(icons) || (0, _orkestrel_contract.isArray)(icons) && icons.every((icon) => isMCPIcon(icon))) && ((0, _orkestrel_contract.isUndefined)(size) || (0, _orkestrel_contract.isInteger)(size) && size >= 0);
 			}
 			default: return false;
 		}
@@ -2962,7 +3018,7 @@ function isMCPCallResult(value) {
 		const content = result["content"];
 		const error = result["isError"];
 		const metadata = result["_meta"];
-		return Array.isArray(content) && content.every((entry) => isMCPContent(entry)) && ((0, _orkestrel_contract.isUndefined)(error) || (0, _orkestrel_contract.isBoolean)(error)) && ((0, _orkestrel_contract.isUndefined)(metadata) || isMCPResultMetaObject(metadata));
+		return (0, _orkestrel_contract.isArray)(content) && content.every((entry) => isMCPContent(entry)) && ((0, _orkestrel_contract.isUndefined)(error) || (0, _orkestrel_contract.isBoolean)(error)) && ((0, _orkestrel_contract.isUndefined)(metadata) || isMCPResultMetaObject(metadata));
 	} catch {
 		return false;
 	}
@@ -3151,7 +3207,7 @@ function isMCPTaskNotification(value) {
 * ```
 */
 function isBoundedString(value, bytes) {
-	if (!(0, _orkestrel_contract.isString)(value) || !Number.isFinite(bytes) || !Number.isInteger(bytes) || bytes < 0) return false;
+	if (!(0, _orkestrel_contract.isString)(value) || !(0, _orkestrel_contract.isInteger)(bytes) || bytes < 0) return false;
 	let measured = 0;
 	for (let index = 0; index < value.length; index += 1) {
 		const code = value.charCodeAt(index);
@@ -3273,6 +3329,22 @@ function isMCPSubscriptionFilter(value) {
 	return (0, _orkestrel_contract.isUndefined)(tasks) || (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(tasks);
 }
 /**
+* Checks whether a subscription filter leaves the built-in tools family to the server.
+*
+* @param value - The unknown value to inspect
+* @returns True if the filter is valid and does not claim tools changes; false otherwise
+*
+* @example
+* ```ts
+* isMCPConsumerFilter({ promptsListChanged: true }) // true
+* isMCPConsumerFilter({ toolsListChanged: true }) // false
+* ```
+*/
+function isMCPConsumerFilter(value) {
+	const owned = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.cloneJSONRecord)(value));
+	return owned.success && isMCPSubscriptionFilter(owned.value) && owned.value["toolsListChanged"] !== true;
+}
+/**
 * Determines whether a value is a graceful `subscriptions/listen` result.
 *
 * @param value - The unknown value to inspect
@@ -3320,21 +3392,21 @@ function isMCPElicitFieldSchema(value) {
 			const names = schema["enumNames"];
 			const titled = schema["oneOf"];
 			if (!(0, _orkestrel_contract.isUndefined)(minimum) && (!(0, _orkestrel_contract.isInteger)(minimum) || minimum < 0) || !(0, _orkestrel_contract.isUndefined)(maximum) && (!(0, _orkestrel_contract.isInteger)(maximum) || maximum < 0) || !(0, _orkestrel_contract.isUndefined)(fallback) && !(0, _orkestrel_contract.isString)(fallback) || !(0, _orkestrel_contract.isUndefined)(format) && format !== "uri" && format !== "email" && format !== "date" && format !== "date-time") return false;
-			if (!(0, _orkestrel_contract.isUndefined)(choices) && (!Array.isArray(choices) || !choices.every(_orkestrel_contract.isString))) return false;
-			if (!(0, _orkestrel_contract.isUndefined)(names) && ((0, _orkestrel_contract.isUndefined)(choices) || !Array.isArray(names) || !names.every(_orkestrel_contract.isString))) return false;
-			return !(!(0, _orkestrel_contract.isUndefined)(titled) && (!Array.isArray(titled) || !titled.every((choice) => isJSONObject(choice) && (0, _orkestrel_contract.isString)(choice["const"]) && (0, _orkestrel_contract.isString)(choice["title"]))));
+			if (!(0, _orkestrel_contract.isUndefined)(choices) && (!(0, _orkestrel_contract.isArray)(choices) || !choices.every(_orkestrel_contract.isString))) return false;
+			if (!(0, _orkestrel_contract.isUndefined)(names) && ((0, _orkestrel_contract.isUndefined)(choices) || !(0, _orkestrel_contract.isArray)(names) || !names.every(_orkestrel_contract.isString))) return false;
+			return !(!(0, _orkestrel_contract.isUndefined)(titled) && (!(0, _orkestrel_contract.isArray)(titled) || !titled.every((choice) => isJSONObject(choice) && (0, _orkestrel_contract.isString)(choice["const"]) && (0, _orkestrel_contract.isString)(choice["title"]))));
 		}
 		if (schema["type"] !== "array") return false;
 		const minimum = schema["minItems"];
 		const maximum = schema["maxItems"];
 		const items = schema["items"];
-		if (!(0, _orkestrel_contract.isUndefined)(minimum) && (!(0, _orkestrel_contract.isInteger)(minimum) || minimum < 0) || !(0, _orkestrel_contract.isUndefined)(maximum) && (!(0, _orkestrel_contract.isInteger)(maximum) || maximum < 0) || !(0, _orkestrel_contract.isUndefined)(fallback) && (!Array.isArray(fallback) || !fallback.every((item) => (0, _orkestrel_contract.isString)(item))) || !isJSONObject(items)) return false;
+		if (!(0, _orkestrel_contract.isUndefined)(minimum) && (!(0, _orkestrel_contract.isInteger)(minimum) || minimum < 0) || !(0, _orkestrel_contract.isUndefined)(maximum) && (!(0, _orkestrel_contract.isInteger)(maximum) || maximum < 0) || !(0, _orkestrel_contract.isUndefined)(fallback) && (!(0, _orkestrel_contract.isArray)(fallback) || !fallback.every((item) => (0, _orkestrel_contract.isString)(item))) || !isJSONObject(items)) return false;
 		const itemType = items["type"];
 		const choices = items["enum"];
 		const titled = items["anyOf"];
 		if (!(0, _orkestrel_contract.isUndefined)(itemType) && itemType !== "string") return false;
-		if (!(0, _orkestrel_contract.isUndefined)(choices) && (!Array.isArray(choices) || !choices.every(_orkestrel_contract.isString))) return false;
-		if (!(0, _orkestrel_contract.isUndefined)(titled) && (!Array.isArray(titled) || !titled.every((choice) => isJSONObject(choice) && (0, _orkestrel_contract.isString)(choice["const"]) && (0, _orkestrel_contract.isString)(choice["title"])))) return false;
+		if (!(0, _orkestrel_contract.isUndefined)(choices) && (!(0, _orkestrel_contract.isArray)(choices) || !choices.every(_orkestrel_contract.isString))) return false;
+		if (!(0, _orkestrel_contract.isUndefined)(titled) && (!(0, _orkestrel_contract.isArray)(titled) || !titled.every((choice) => isJSONObject(choice) && (0, _orkestrel_contract.isString)(choice["const"]) && (0, _orkestrel_contract.isString)(choice["title"])))) return false;
 		return itemType === "string" && !(0, _orkestrel_contract.isUndefined)(choices) || !(0, _orkestrel_contract.isUndefined)(titled);
 	} catch {
 		return false;
@@ -3369,7 +3441,7 @@ function isMCPElicitSchema(value) {
 		const dialect = schema["$schema"];
 		if (!(0, _orkestrel_contract.isUndefined)(dialect) && !(0, _orkestrel_contract.isString)(dialect)) return false;
 		const required = schema["required"];
-		return ((0, _orkestrel_contract.isUndefined)(required) || Array.isArray(required) && required.every((name) => (0, _orkestrel_contract.isString)(name))) && Object.values(properties).every((property) => isMCPElicitFieldSchema(property));
+		return ((0, _orkestrel_contract.isUndefined)(required) || (0, _orkestrel_contract.isArray)(required) && required.every((name) => (0, _orkestrel_contract.isString)(name))) && Object.values(properties).every((property) => isMCPElicitFieldSchema(property));
 	} catch {
 		return false;
 	}
@@ -3512,7 +3584,7 @@ function isMCPElicitResult(value) {
 		if (action !== "accept") return (0, _orkestrel_contract.isUndefined)(content);
 		if ((0, _orkestrel_contract.isUndefined)(content)) return true;
 		if (!isJSONObject(content)) return false;
-		return Object.values(content).every((item) => (0, _orkestrel_contract.isString)(item) || (0, _orkestrel_contract.isFiniteNumber)(item) || (0, _orkestrel_contract.isBoolean)(item) || Array.isArray(item) && item.every((entry) => (0, _orkestrel_contract.isString)(entry)));
+		return Object.values(content).every((item) => (0, _orkestrel_contract.isString)(item) || (0, _orkestrel_contract.isFiniteNumber)(item) || (0, _orkestrel_contract.isBoolean)(item) || (0, _orkestrel_contract.isArray)(item) && item.every((entry) => (0, _orkestrel_contract.isString)(entry)));
 	} catch {
 		return false;
 	}
@@ -3567,11 +3639,11 @@ function isElicitContent(value, schema) {
 		const properties = declared.value["properties"];
 		const required = declared.value["required"];
 		if (!isJSONObject(properties)) return false;
-		if (Array.isArray(required)) {
+		if ((0, _orkestrel_contract.isArray)(required)) {
 			for (const name of required) if (!(0, _orkestrel_contract.isString)(name) || !Object.hasOwn(content, name)) return false;
 		}
 		for (const [name, item] of Object.entries(content)) {
-			if (!(0, _orkestrel_contract.isString)(item) && !(0, _orkestrel_contract.isFiniteNumber)(item) && !(0, _orkestrel_contract.isBoolean)(item) && !(Array.isArray(item) && item.every((entry) => (0, _orkestrel_contract.isString)(entry)))) return false;
+			if (!(0, _orkestrel_contract.isString)(item) && !(0, _orkestrel_contract.isFiniteNumber)(item) && !(0, _orkestrel_contract.isBoolean)(item) && !((0, _orkestrel_contract.isArray)(item) && item.every((entry) => (0, _orkestrel_contract.isString)(entry)))) return false;
 			if (!Object.hasOwn(properties, name)) continue;
 			const field = properties[name];
 			if (!isJSONObject(field)) return false;
@@ -3584,7 +3656,7 @@ function isElicitContent(value, schema) {
 				const minimum = field["minimum"];
 				const maximum = field["maximum"];
 				if (!(0, _orkestrel_contract.isFiniteNumber)(item)) return false;
-				if (declaredType === "integer" && !Number.isInteger(item)) return false;
+				if (declaredType === "integer" && !(0, _orkestrel_contract.isInteger)(item)) return false;
 				if ((0, _orkestrel_contract.isFiniteNumber)(minimum) && item < minimum) return false;
 				if ((0, _orkestrel_contract.isFiniteNumber)(maximum) && item > maximum) return false;
 				continue;
@@ -3596,8 +3668,8 @@ function isElicitContent(value, schema) {
 				const maximum = field["maxLength"];
 				const format = field["format"];
 				if (!(0, _orkestrel_contract.isString)(item)) return false;
-				if (Array.isArray(choices) && !choices.includes(item)) return false;
-				if (Array.isArray(titled) && !titled.some((choice) => isJSONObject(choice) && choice["const"] === item)) return false;
+				if ((0, _orkestrel_contract.isArray)(choices) && !choices.includes(item)) return false;
+				if ((0, _orkestrel_contract.isArray)(titled) && !titled.some((choice) => isJSONObject(choice) && choice["const"] === item)) return false;
 				const length = Array.from(item).length;
 				if ((0, _orkestrel_contract.isInteger)(minimum) && length < minimum) return false;
 				if ((0, _orkestrel_contract.isInteger)(maximum) && length > maximum) return false;
@@ -3610,14 +3682,14 @@ function isElicitContent(value, schema) {
 			const items = field["items"];
 			const minimum = field["minItems"];
 			const maximum = field["maxItems"];
-			if (!Array.isArray(item) || !item.every((entry) => (0, _orkestrel_contract.isString)(entry))) return false;
+			if (!(0, _orkestrel_contract.isArray)(item) || !item.every((entry) => (0, _orkestrel_contract.isString)(entry))) return false;
 			if ((0, _orkestrel_contract.isInteger)(minimum) && item.length < minimum) return false;
 			if ((0, _orkestrel_contract.isInteger)(maximum) && item.length > maximum) return false;
 			if (!isJSONObject(items)) return false;
 			const choices = items["enum"];
 			const titled = items["anyOf"];
-			if (Array.isArray(choices) && !item.every((entry) => choices.includes(entry))) return false;
-			if (Array.isArray(titled) && !item.every((entry) => titled.some((choice) => isJSONObject(choice) && choice["const"] === entry))) return false;
+			if ((0, _orkestrel_contract.isArray)(choices) && !item.every((entry) => choices.includes(entry))) return false;
+			if ((0, _orkestrel_contract.isArray)(titled) && !item.every((entry) => titled.some((choice) => isJSONObject(choice) && choice["const"] === entry))) return false;
 		}
 		return true;
 	} catch {
@@ -3678,7 +3750,7 @@ function isMCPRootResult(value) {
 		const result = owned.value;
 		const roots = result["roots"];
 		const metadata = result["_meta"];
-		if (!Array.isArray(roots) || !roots.every((root) => isMCPRoot(root))) return false;
+		if (!(0, _orkestrel_contract.isArray)(roots) || !roots.every((root) => isMCPRoot(root))) return false;
 		return (0, _orkestrel_contract.isUndefined)(metadata) || isMCPMetaObject(metadata);
 	} catch {
 		return false;
@@ -3716,7 +3788,7 @@ function isMCPSampleContent(value) {
 		if (block["type"] === "tool_result") {
 			const carried = block["content"];
 			const failed = block["isError"];
-			if (!Array.isArray(carried) || !carried.every((entry) => isMCPContent(entry))) return false;
+			if (!(0, _orkestrel_contract.isArray)(carried) || !carried.every((entry) => isMCPContent(entry))) return false;
 			if (!(0, _orkestrel_contract.isUndefined)(failed) && !(0, _orkestrel_contract.isBoolean)(failed)) return false;
 			return (0, _orkestrel_contract.isString)(block["toolUseId"]);
 		}
@@ -3765,7 +3837,7 @@ function isMCPSampleResult(value) {
 		const metadata = result["_meta"];
 		if (role !== "user" && role !== "assistant") return false;
 		if (!(0, _orkestrel_contract.isString)(result["model"])) return false;
-		if (!(Array.isArray(content) ? content : [content]).every((block) => isMCPSampleContent(block))) return false;
+		if (!((0, _orkestrel_contract.isArray)(content) ? content : [content]).every((block) => isMCPSampleContent(block))) return false;
 		if (!(0, _orkestrel_contract.isUndefined)(reason) && !(0, _orkestrel_contract.isString)(reason)) return false;
 		return (0, _orkestrel_contract.isUndefined)(metadata) || isMCPMetaObject(metadata);
 	} catch {
@@ -5015,6 +5087,7 @@ var MCPServer = class {
 	#limits;
 	#subscriptions = 0;
 	constructor(options) {
+		if (options.subscription !== void 0 && !isMCPConsumerFilter(options.subscription.notifications)) throw new MCPError("The consumer filter must be a valid filter that omits tools changes, because the server produces that family from its registry", JSONRPC_INVALID_PARAMS);
 		this.#emitter = new _orkestrel_emitter.Emitter({
 			...options.on !== void 0 ? { on: options.on } : {},
 			...options.error !== void 0 ? { error: options.error } : {}
@@ -5177,7 +5250,7 @@ var MCPServer = class {
 			const input = captured[0];
 			return this.#forward(input, request);
 		}
-		if (!Array.isArray(captured[0]) || !captured[0].every((entry) => isMCPResourceContents(entry))) return buildJSONRPCError(request.id, JSONRPC_INTERNAL_ERROR, "Server resource manager returned invalid or oversized contents");
+		if (!(0, _orkestrel_contract.isArray)(captured[0]) || !captured[0].every((entry) => isMCPResourceContents(entry))) return buildJSONRPCError(request.id, JSONRPC_INTERNAL_ERROR, "Server resource manager returned invalid or oversized contents");
 		const result = buildModernResult({ contents: captured[0] }, this.#options.identity, this.#options.cache?.ttl ?? 6e4, this.#options.cache?.scope);
 		return buildJSONRPCResult(request.id, result);
 	}
@@ -5260,7 +5333,7 @@ var MCPServer = class {
 		const generated = await manager.complete(params, options);
 		if (generated === void 0) return buildJSONRPCError(request.id, JSONRPC_INVALID_PARAMS, "Completion reference not found");
 		const candidate = generated;
-		if (!(0, _orkestrel_contract.isRecord)(candidate) || !Array.isArray(candidate["values"])) return buildJSONRPCError(request.id, JSONRPC_INTERNAL_ERROR, "Server completion manager returned invalid or oversized candidates");
+		if (!(0, _orkestrel_contract.isRecord)(candidate) || !(0, _orkestrel_contract.isArray)(candidate["values"])) return buildJSONRPCError(request.id, JSONRPC_INTERNAL_ERROR, "Server completion manager returned invalid or oversized candidates");
 		const values = candidate["values"];
 		const truncated = values.length > 100;
 		const captured = snapshotJSON({
@@ -5287,14 +5360,14 @@ var MCPServer = class {
 		const args = (0, _orkestrel_contract.isRecord)(rawArguments) ? rawArguments : EMPTY_MCP_ARGUMENTS;
 		const input = await this.#input(request, args, options);
 		if (input !== void 0) return input;
-		const call = buildToolCall(request, options.caller, args);
+		const call = buildToolCall(request, args);
 		if (call === void 0) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: a string `name` is required");
 		const deferred = await this.#defer(request, call, options);
 		if (deferred !== void 0) return deferred;
 		const token = params?.["_meta"];
 		const progressToken = (0, _orkestrel_contract.isRecord)(token) ? token["progressToken"] : void 0;
-		if (this.#options.execution !== void 0 && ((0, _orkestrel_contract.isString)(progressToken) || typeof progressToken === "number" && Number.isInteger(progressToken))) return this.#progress(request, call, progressToken, options);
-		const result = await this.#execute(request, call, options.signal);
+		if (this.#options.execution !== void 0 && ((0, _orkestrel_contract.isString)(progressToken) || (0, _orkestrel_contract.isInteger)(progressToken))) return this.#progress(request, call, progressToken, options);
+		const result = await this.#execute(request, call, options);
 		return "jsonrpc" in result ? result : buildJSONRPCResult(id, result);
 	}
 	async #defer(request, call, options) {
@@ -5338,7 +5411,7 @@ var MCPServer = class {
 			keys: this.#limits.keys,
 			depth: this.#limits.depth
 		}, signal);
-		const execution = this.#execute(request, call, signal, reporter);
+		const execution = this.#execute(request, call, options, reporter);
 		try {
 			while (true) {
 				const outcome = await Promise.race([reporter.take(), execution]);
@@ -5356,14 +5429,19 @@ var MCPServer = class {
 			reporter.stop();
 		}
 	}
-	async #execute(request, call, signal, progress) {
+	async #execute(request, call, options, progress) {
+		const { signal, caller } = options;
 		let result;
 		try {
-			result = this.#options.execution === void 0 ? await this.#options.tools.execute(call) : await this.#options.execution({
+			result = this.#options.execution === void 0 ? await this.#options.tools.execute(call, {
+				signal,
+				...caller === void 0 ? {} : { caller }
+			}) : await this.#options.execution({
 				request,
 				call,
 				tools: this.#options.tools,
 				signal,
+				...caller === void 0 ? {} : { caller },
 				...progress === void 0 ? {} : { progress }
 			});
 		} catch (error) {
@@ -5501,7 +5579,7 @@ var MCPServer = class {
 			bytes: this.#limits.message,
 			depth: this.#limits.depth
 		});
-		if (configured === void 0 || context === void 0 || !(0, _orkestrel_contract.isString)(principal) || principal.length === 0 || !Number.isFinite(configured.ttl) || configured.ttl <= 0) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: input policy returned an invalid round or continuation context");
+		if (configured === void 0 || context === void 0 || !(0, _orkestrel_contract.isString)(principal) || principal.length === 0 || !(0, _orkestrel_contract.isFiniteNumber)(configured.ttl) || configured.ttl <= 0) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: input policy returned an invalid round or continuation context");
 		if (previous !== void 0 && previous <= Date.now()) return buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: request state could not be verified for this retry");
 		const expiry = Date.now() + configured.ttl;
 		const protectedState = {
@@ -5551,7 +5629,10 @@ var MCPServer = class {
 			const task = this.#options.task;
 			const configured = this.#options.subscription;
 			const tasks = task !== void 0 && configured !== void 0;
-			let notifications = buildSubscriptionFilter(requested, configured?.notifications ?? {}, tasks);
+			let notifications = buildSubscriptionFilter(requested, {
+				...configured?.notifications,
+				toolsListChanged: true
+			}, tasks);
 			const requestedTaskIds = notifications.taskIds;
 			if (requestedTaskIds !== void 0) {
 				const resolved = [];
@@ -5564,19 +5645,22 @@ var MCPServer = class {
 					taskIds: resolved
 				} : rest;
 			}
+			const state = {
+				frame: void 0,
+				failure: void 0,
+				iterator: void 0
+			};
+			const source = new ReadableStream({
+				start: this.#startSubscription.bind(this, notifications, options, configured, state),
+				pull: this.#pullSubscription.bind(this, notifications, options, state)
+			});
 			yield buildSubscriptionAcknowledgement(notifications, id);
-			if (configured !== void 0) {
-				const iterator = (await configured.producer(notifications, options))[Symbol.asyncIterator]();
-				options.signal.addEventListener("abort", () => void iterator.return?.(void 0)?.catch(() => void 0), { once: true });
-				for (let next = await iterator.next(); next.done !== true; next = await iterator.next()) {
-					const owned = parseJSONRPCMessage(next.value, {
-						bytes: this.#limits.message,
-						depth: this.#limits.depth
-					});
-					if (owned === void 0 || !isJSONRPCNotification(owned)) continue;
-					if (matchesSubscriptionNotification(owned, notifications)) yield stampSubscriptionNotification(owned, id);
-				}
+			for await (const notification of source) {
+				if (notification === void 0) continue;
+				if (notification === state.frame) state.frame = void 0;
+				yield stampSubscriptionNotification(notification, id);
 			}
+			if (state.failure !== void 0) throw state.failure.error;
 			return buildSubscriptionResult(id, this.#options.identity);
 		} catch (error) {
 			if (options.signal.aborted) throw error;
@@ -5585,6 +5669,72 @@ var MCPServer = class {
 			slot.abort();
 		}
 	}
+	async #startSubscription(notifications, options, configured, state, controller) {
+		const emitter = this.#options.tools.emitter;
+		const changed = this.#change.bind(this, controller, options.signal, state);
+		if (options.signal.aborted) {
+			controller.error(options.signal.reason);
+			return;
+		}
+		if (notifications.toolsListChanged === true && !emitter.destroyed) {
+			emitter.on("add", changed);
+			emitter.on("remove", changed);
+			emitter.on("clear", changed);
+		}
+		options.signal.addEventListener("abort", () => {
+			emitter.off("add", changed);
+			emitter.off("remove", changed);
+			emitter.off("clear", changed);
+			const iterator = state.iterator;
+			state.iterator = void 0;
+			if (iterator !== void 0) this.#releaseProducer(iterator, options.signal.reason);
+			controller.error(options.signal.reason);
+		}, { once: true });
+		try {
+			if (configured === void 0) return;
+			const iterator = (await configured.producer(notifications, options))[Symbol.asyncIterator]();
+			if (options.signal.aborted) this.#releaseProducer(iterator, options.signal.reason);
+			else state.iterator = iterator;
+		} catch (error) {
+			this.#failSubscription(state, options.signal, controller, error);
+		}
+	}
+	#change(controller, signal, state) {
+		if (signal.aborted || state.failure !== void 0 || state.frame !== void 0) return;
+		const notification = {
+			jsonrpc: "2.0",
+			method: "notifications/tools/list_changed"
+		};
+		state.frame = notification;
+		controller.enqueue(notification);
+	}
+	async #pullSubscription(notifications, options, state, controller) {
+		try {
+			if (options.signal.aborted) return;
+			const next = await state.iterator?.next();
+			if (options.signal.aborted) return;
+			if (next === void 0 || next.done === true) {
+				state.iterator = void 0;
+				if (notifications.toolsListChanged !== true) controller.close();
+				return;
+			}
+			const owned = parseJSONRPCMessage(next.value, {
+				bytes: this.#limits.message,
+				depth: this.#limits.depth
+			});
+			controller.enqueue(owned !== void 0 && isJSONRPCNotification(owned) && owned.method !== "notifications/tools/list_changed" && matchesSubscriptionNotification(owned, notifications) ? owned : void 0);
+		} catch (error) {
+			this.#failSubscription(state, options.signal, controller, error);
+		}
+	}
+	#failSubscription(state, signal, controller, error) {
+		if (signal.aborted) return;
+		state.failure = { error };
+		controller.close();
+	}
+	#releaseProducer(iterator, reason) {
+		iterator.return?.(reason)?.catch(() => void 0);
+	}
 	#readTaskId(request) {
 		const id = request.id;
 		const context = parseRequestContext(request, {
@@ -5952,9 +6102,11 @@ var MCPClient = class {
 	async *#openSubscription(notifications, signal, capacity) {
 		signal.throwIfAborted();
 		if (!(0, _orkestrel_contract.isInteger)(capacity) || capacity < 1) throw new MCPError("MCP subscription capacity must be a positive integer", JSONRPC_INVALID_PARAMS);
+		const method = "subscriptions/listen";
+		const opening = this.#refuse(method);
+		if (opening !== void 0) throw opening;
 		this.#nextId += 1;
 		const id = this.#nextId;
-		const method = "subscriptions/listen";
 		const modern = this.#version;
 		const request = {
 			jsonrpc: "2.0",
@@ -6002,7 +6154,16 @@ var MCPClient = class {
 			this.#cancelSubscription(id, /* @__PURE__ */ new Error("MCP subscription closed by its consumer"));
 		}
 	}
+	#refuse(method) {
+		if (method === "server/discover") return void 0;
+		if (this.#connected) return void 0;
+		const inflight = this.#connecting;
+		if (inflight !== void 0 && inflight.generation === this.#generation) return void 0;
+		return new MCPError(`MCP client is not connected, so '${method}' was not issued`, JSONRPC_INVALID_REQUEST);
+	}
 	#request(method, params, deadline, version, options) {
+		const refusal = this.#refuse(method);
+		if (refusal !== void 0) return Promise.reject(refusal);
 		this.#nextId += 1;
 		const id = this.#nextId;
 		const timeout = deadline;
@@ -6056,7 +6217,7 @@ var MCPClient = class {
 				...report === void 0 ? {} : { progress: report }
 			});
 			this.#transport.send(request).catch((error) => {
-				this.#settle(id, error instanceof Error ? error : new Error(String(error)), true);
+				this.#settle(id, (0, _orkestrel_contract.isError)(error) ? error : new Error(String(error)), true);
 			});
 		});
 	}
@@ -6144,16 +6305,20 @@ var MCPClient = class {
 	#tool(name, descriptor) {
 		const inputSchema = descriptor["inputSchema"];
 		const description = descriptor["description"];
-		const options = {
+		const title = descriptor["title"];
+		const annotations = descriptor["annotations"];
+		const projected = isMCPToolAnnotations(annotations) ? mcpAnnotationsToTool(annotations) : {};
+		return new _orkestrel_tool.Tool({
 			name,
+			...(0, _orkestrel_contract.isString)(title) ? { title } : {},
+			...(0, _orkestrel_contract.isString)(description) ? { description } : {},
+			...(0, _orkestrel_contract.isRecord)(inputSchema) ? { parameters: inputSchema } : {},
+			...Object.keys(projected).length === 0 ? {} : { annotations: projected },
 			execute: this.#execute.bind(this, name)
-		};
-		if ((0, _orkestrel_contract.isString)(description)) options.description = description;
-		if ((0, _orkestrel_contract.isRecord)(inputSchema)) options.parameters = inputSchema;
-		return new _orkestrel_tool.Tool(options);
+		});
 	}
-	async #execute(name, args) {
-		const outcome = await this.call(name, args);
+	async #execute(name, args, context) {
+		const outcome = await this.call(name, args, { signal: context.signal });
 		if (outcome.resultType !== "complete") throw new Error(`MCP tool '${name}' answered '${outcome.resultType}' and has no inline value`);
 		return outcome.value;
 	}
@@ -6809,6 +6974,7 @@ exports.isMCPCompletion = isMCPCompletion;
 exports.isMCPCompletionParams = isMCPCompletionParams;
 exports.isMCPCompletionReference = isMCPCompletionReference;
 exports.isMCPCompletionResult = isMCPCompletionResult;
+exports.isMCPConsumerFilter = isMCPConsumerFilter;
 exports.isMCPContent = isMCPContent;
 exports.isMCPElicitFieldSchema = isMCPElicitFieldSchema;
 exports.isMCPElicitForm = isMCPElicitForm;
@@ -6859,6 +7025,7 @@ exports.isMCPTaskNotification = isMCPTaskNotification;
 exports.isMCPTaskResult = isMCPTaskResult;
 exports.isMCPTaskStatus = isMCPTaskStatus;
 exports.isMCPTextResource = isMCPTextResource;
+exports.isMCPToolAnnotations = isMCPToolAnnotations;
 exports.isMCPVersion = isMCPVersion;
 exports.isModernRequest = isModernRequest;
 exports.isRFC3339Date = isRFC3339Date;
@@ -6868,6 +7035,7 @@ exports.legacyInvocationToModern = legacyInvocationToModern;
 exports.legacyResultToModern = legacyResultToModern;
 exports.matchesResultType = matchesResultType;
 exports.matchesSubscriptionNotification = matchesSubscriptionNotification;
+exports.mcpAnnotationsToTool = mcpAnnotationsToTool;
 exports.modernInvocationToLegacy = modernInvocationToLegacy;
 exports.modernResultToLegacy = modernResultToLegacy;
 exports.parseJSONRPCMessage = parseJSONRPCMessage;
@@ -6883,5 +7051,6 @@ exports.snapshotToolResult = snapshotToolResult;
 exports.stampSubscriptionNotification = stampSubscriptionNotification;
 exports.supportsFormElicitation = supportsFormElicitation;
 exports.supportsTask = supportsTask;
+exports.toolAnnotationsToMCP = toolAnnotationsToMCP;
 
 //# sourceMappingURL=index.cjs.map