@warlock.js/ai-tools 5.31.0 → 5.33.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to `@warlock.js/ai-tools` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.33.0 - 2026-10-19
+
+### Fixed
+
+- Keep HTTP and MCP fixtures valid under strict indexed access, accept string JSON-RPC request IDs in serving tests, and replace stdin through its descriptor without pretending a stream is a terminal.
+
+### Added
+
+- MCP serving now exposes per-call `requestId`, authenticated `principal` and cancellation-aware signals over HTTP and stdio. HTTP `auth.authenticate` resolves principals alongside bearer/authorize checks; stdio accepts static or provider principals. `beforeCall` validates policy after input validation and can return a native error refusal or throw a JSON-RPC error. `notifications/cancelled` aborts only the matching caller/request and suppresses its response. New hook/context/refusal and stdio transport types are exported.
+
+## 5.32.0 - 2026-10-18
+
+### Changed
+
+- Pin the package development compiler to TypeScript 7.0.2 and use explicit Node types and source roots with supported module resolution.
+
+### Fixed
+
+- Opted-in native MCP tool results preserve content blocks, `isError`, `structuredContent` and `_meta` over stdio and HTTP, including tools with an advertised output schema. Per-request headers and abort signals remain available to tools; default result serialization and thrown-tool error handling are unchanged.
+- Malformed native results produce a JSON-RPC internal error instead of sending invalid MCP payloads.
+
+### Added
+
+- `mcpResult(...)` and its `McpNativeResult` type explicitly mark native tool results. `serve(..., { results: "native" })` enables detection for existing native-returning tools; `meta.mcpResults: "native" | "text"` overrides detection per tool.
+- `meta.outputSchema` advertises structured tool output in `tools/list`; `McpToolCallResult` now includes `structuredContent` and `_meta`.
+
 ## 5.31.0 - 2026-10-18
 
 ### Added

package/cjs/index.cjs

@@ -298,7 +298,7 @@ const ALL_METHODS = [
 	"DELETE"
 ];
 /** Methods that conventionally carry no request body — `body` is dropped for these. */
-const BODYLESS_METHODS = new Set(["GET"]);
+const BODYLESS_METHODS = /* @__PURE__ */ new Set(["GET"]);
 /**
 * Standard Schema for {@link HttpRequestInput}. `url` is required;
 * `method` is constrained to the canonical HTTP verb set (further
@@ -462,10 +462,12 @@ function httpRequestTool(options = {}) {
 				...input.headers
 			};
 			let body;
-			if (!BODYLESS_METHODS.has(method) && input.body !== void 0) if (typeof input.body === "string") body = input.body;
-			else {
-				body = JSON.stringify(input.body);
-				if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-type")) headers["content-type"] = "application/json";
+			if (!BODYLESS_METHODS.has(method) && input.body !== void 0) {
+				if (typeof input.body === "string") body = input.body;
+				else {
+					body = JSON.stringify(input.body);
+					if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-type")) headers["content-type"] = "application/json";
+				}
 			}
 			let response;
 			try {
@@ -717,8 +719,10 @@ function armCall(reject, method, options, onSettle) {
 		}));
 	};
 	const signal = options?.signal;
-	if (signal) if (signal.aborted) queueMicrotask(onAbort);
-	else signal.addEventListener("abort", onAbort, { once: true });
+	if (signal) {
+		if (signal.aborted) queueMicrotask(onAbort);
+		else signal.addEventListener("abort", onAbort, { once: true });
+	}
 	function cleanup() {
 		clearTimeout(timer);
 		if (signal) signal.removeEventListener("abort", onAbort);
@@ -871,8 +875,10 @@ var HttpTransport = class {
 		const timer = setTimeout(() => controller.abort(), timeoutMs);
 		const onAbort = () => controller.abort();
 		const signal = options?.signal;
-		if (signal) if (signal.aborted) controller.abort();
-		else signal.addEventListener("abort", onAbort, { once: true });
+		if (signal) {
+			if (signal.aborted) controller.abort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
 		let response;
 		try {
 			response = await fetch(this.url, {
@@ -937,7 +943,8 @@ var HttpTransport = class {
 				body: JSON.stringify(notification)
 			});
 		} catch (cause) {
-			throw new McpTransportError(`MCP http transport notification "${method}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new McpTransportError(`MCP http transport notification "${method}" failed: ${message}`, {
 				type: "connect",
 				method,
 				cause
@@ -1040,7 +1047,8 @@ var JsonRpcClient = class {
 * @returns A JSON-RPC client handle.
 */
 function createJsonRpcClient(source) {
-	return new JsonRpcClient(isTransportConfig(source) ? createTransport(source) : withIdAllocator(source));
+	const transport = isTransportConfig(source) ? createTransport(source) : withIdAllocator(source);
+	return new JsonRpcClient(transport);
 }
 /**
 * Distinguish an {@link McpTransport} config (a plain object with a `type`
@@ -1121,7 +1129,8 @@ var McpClientImpl = class {
 			await this.rpc.notify("notifications/initialized");
 		} catch (cause) {
 			if (cause instanceof McpTransportError) throw cause;
-			throw new McpTransportError(`MCP initialize handshake failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new McpTransportError(`MCP initialize handshake failed: ${message}`, {
 				type: "connect",
 				method: "initialize",
 				cause
@@ -1306,6 +1315,147 @@ const SUPPORTED_PROTOCOL_VERSIONS = [
 /** The newest MCP protocol version the server speaks. */
 const LATEST_PROTOCOL_VERSION = "2025-11-25";
 
+//#endregion
+//#region ../../packages/ai-tools/src/mcp/result.ts
+const NATIVE_RESULT = Symbol("mcpResult");
+/**
+* Opt in to native MCP content, error status, structured output and metadata.
+* Validation happens after invoke(), so malformed payloads become JSON-RPC
+* errors rather than being caught as tool execution errors.
+*/
+function mcpResult(result) {
+	return { [NATIVE_RESULT]: result };
+}
+/** Read a branded value without accepting lookalike application objects. */
+function isMcpResult(value) {
+	return isRecord(value) && NATIVE_RESULT in value;
+}
+/** Get the original payload; no cloning, normalization or field stripping. */
+function unwrapMcpResult(value) {
+	return value[NATIVE_RESULT];
+}
+/** Objects with result fields are candidates only when native mode is enabled. */
+function looksLikeMcpResult(value) {
+	return isRecord(value) && [
+		"content",
+		"isError",
+		"structuredContent",
+		"_meta"
+	].some((key) => key in value);
+}
+/** Non-array object used by the MCP JSON object fields. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalString(value) {
+	return value === void 0 || typeof value === "string";
+}
+function validAnnotations(value) {
+	if (value === void 0) return true;
+	if (!isRecord(value)) return false;
+	return (value.audience === void 0 || Array.isArray(value.audience) && value.audience.every((role) => role === "user" || role === "assistant")) && (value.priority === void 0 || typeof value.priority === "number" && value.priority >= 0 && value.priority <= 1) && optionalString(value.lastModified);
+}
+function validMetadata(value) {
+	return (value["_meta"] === void 0 || isRecord(value["_meta"])) && validAnnotations(value.annotations);
+}
+function validIcon(value) {
+	return isRecord(value) && typeof value.src === "string" && optionalString(value.mimeType) && (value.sizes === void 0 || Array.isArray(value.sizes) && value.sizes.every((size) => typeof size === "string")) && (value.theme === void 0 || value.theme === "light" || value.theme === "dark");
+}
+function validContent(value) {
+	if (!isRecord(value) || !validMetadata(value)) return false;
+	switch (value.type) {
+		case "text": return typeof value.text === "string";
+		case "image":
+		case "audio": return typeof value.data === "string" && typeof value.mimeType === "string";
+		case "resource_link": return typeof value.uri === "string" && typeof value.name === "string" && optionalString(value.title) && optionalString(value.description) && optionalString(value.mimeType) && (value.size === void 0 || typeof value.size === "number") && (value.icons === void 0 || Array.isArray(value.icons) && value.icons.every(validIcon));
+		case "resource": {
+			const resource = value.resource;
+			return isRecord(resource) && typeof resource.uri === "string" && optionalString(resource.mimeType) && validMetadata(resource) && (typeof resource.text === "string" || typeof resource.blob === "string");
+		}
+		default: return false;
+	}
+}
+/** Reject values JSON would drop, coerce or fail to encode (including cycles). */
+function isJsonValue(value, ancestors = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object" || ancestors.has(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) return false;
+	ancestors.add(value);
+	const valid = Array.isArray(value) ? Array.from(value).every((entry) => isJsonValue(entry, ancestors)) : Object.values(value).every((entry) => entry === void 0 || isJsonValue(entry, ancestors));
+	ancestors.delete(value);
+	return valid;
+}
+/**
+* MCP 2025-11-25 CallToolResult and ContentBlock fields:
+* https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-result
+* https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.ts
+* structuredContent is preserved even when tools/list declares outputSchema.
+* Tool authors remain responsible for conformity to that application schema.
+*/
+function assertMcpResult(value) {
+	if (!isRecord(value) || !Array.isArray(value.content) || !Array.from(value.content).every(validContent) || value.isError !== void 0 && typeof value.isError !== "boolean" || value.structuredContent !== void 0 && !isRecord(value.structuredContent) || value["_meta"] !== void 0 && !isRecord(value["_meta"]) || !isJsonValue(value)) throw new TypeError("Invalid native MCP CallToolResult.");
+}
+
+//#endregion
+//#region ../../packages/ai-tools/src/mcp/serve-requests.ts
+/**
+* In-flight requests for one transport. HTTP partitions these by credentials;
+* stdio has a single connection. Cancellation never crosses those boundaries.
+* https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation
+* (checked 2026-10-19): ignore unknown/completed ids and never answer cancelled work.
+*/
+var McpServeRequests = class {
+	constructor() {
+		this.scopes = /* @__PURE__ */ new Map();
+	}
+	cancel(message, scope = "") {
+		if (!isRecord(message) || message.jsonrpc !== "2.0" || message.method !== "notifications/cancelled" || message.id !== void 0 || !isRecord(message.params)) return;
+		const { requestId, reason } = message.params;
+		if (typeof requestId !== "string" && typeof requestId !== "number" || reason !== void 0 && typeof reason !== "string") return;
+		const pending = this.scopes.get(scope)?.get(requestId);
+		if (pending?.size === 1) {
+			for (const entry of pending) if (entry.cancellable) entry.controller.abort(new DOMException(typeof reason === "string" ? reason : "Request cancelled.", "AbortError"));
+		}
+	}
+	async run(request, context, dispatch, scope = "") {
+		let pending = this.scopes.get(scope);
+		if (!pending) {
+			pending = /* @__PURE__ */ new Map();
+			this.scopes.set(scope, pending);
+		}
+		const controller = new AbortController();
+		const entry = {
+			controller,
+			cancellable: request.method !== "initialize"
+		};
+		const calls = pending.get(request.id) ?? /* @__PURE__ */ new Set();
+		calls.add(entry);
+		pending.set(request.id, calls);
+		const onAbort = () => controller.abort(context.signal?.reason);
+		context.signal?.addEventListener("abort", onAbort, { once: true });
+		if (context.signal?.aborted) onAbort();
+		try {
+			if (controller.signal.aborted) return;
+			const response = await dispatch({
+				...context,
+				requestId: request.id,
+				signal: controller.signal
+			});
+			return controller.signal.aborted ? void 0 : response;
+		} catch (cause) {
+			if (controller.signal.aborted) return;
+			throw cause;
+		} finally {
+			context.signal?.removeEventListener("abort", onAbort);
+			calls.delete(entry);
+			if (calls.size === 0) pending.delete(request.id);
+			if (pending.size === 0) this.scopes.delete(scope);
+		}
+	}
+};
+
 //#endregion
 //#region ../../packages/ai-tools/src/mcp/serve-http.ts
 /**
@@ -1342,7 +1492,7 @@ const JSON_RPC_INVALID_REQUEST$1 = -32600;
 /** Generic server-defined JSON-RPC code for HTTP-level refusals (auth, origin, size). */
 const JSON_RPC_SERVER_ERROR = -32e3;
 /** Host names that always mean "this machine". */
-const LOOPBACK_NAMES = new Set([
+const LOOPBACK_NAMES = /* @__PURE__ */ new Set([
 	"localhost",
 	"127.0.0.1",
 	"::1",
@@ -1404,9 +1554,9 @@ function resolveSettings(transport) {
 	const tokens = auth?.bearer === void 0 ? [] : typeof auth.bearer === "string" ? [auth.bearer] : [...auth.bearer];
 	if (tokens.some((token) => token.length === 0)) throw new McpServeError("MCP http auth.bearer tokens must be non-empty strings.", { type: "config" });
 	if (auth && auth.bearer !== void 0 && tokens.length === 0) throw new McpServeError("MCP http auth.bearer needs at least one token.", { type: "config" });
-	if (auth && tokens.length === 0 && !auth.authorize) throw new McpServeError("MCP http auth needs `bearer` and/or `authorize`.", { type: "config" });
-	const authRequired = tokens.length > 0 || auth?.authorize !== void 0;
-	if (!loopback && !authRequired) throw new McpServeError(`Refusing to serve MCP over http on non-loopback host "${host}" without auth. Set transport.auth ({ bearer } or { authorize }), or bind 127.0.0.1.`, {
+	if (auth && tokens.length === 0 && !auth.authorize && !auth.authenticate) throw new McpServeError("MCP http auth needs `bearer`, `authorize` and/or `authenticate`.", { type: "config" });
+	const authRequired = tokens.length > 0 || auth?.authorize !== void 0 || auth?.authenticate !== void 0;
+	if (!loopback && !authRequired) throw new McpServeError(`Refusing to serve MCP over http on non-loopback host "${host}" without auth. Set transport.auth ({ bearer }, { authorize } or { authenticate }), or bind 127.0.0.1.`, {
 		type: "config",
 		context: { host }
 	});
@@ -1419,6 +1569,7 @@ function resolveSettings(transport) {
 		drainTimeoutMs,
 		tokenDigests: tokens.map(digest),
 		authorize: auth?.authorize,
+		authenticate: auth?.authenticate,
 		authRequired,
 		allowedOrigins: new Set((transport.allowedOrigins ?? []).map(normalizeOrigin)),
 		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name)))
@@ -1477,6 +1628,7 @@ function sendEmpty(response, status, headers = {}) {
 async function startHttpServer(transport, dispatch) {
 	const settings = resolveSettings(transport);
 	const shutdown = new AbortController();
+	const requests = new McpServeRequests();
 	const inFlight = /* @__PURE__ */ new Set();
 	let closing;
 	const server = (0, node_http.createServer)((request, response) => {
@@ -1484,7 +1636,7 @@ async function startHttpServer(transport, dispatch) {
 			sendRefusal(response, 503, JSON_RPC_SERVER_ERROR, "Server is shutting down.", { connection: "close" });
 			return;
 		}
-		const work = handleRequest(request, response, settings, dispatch, shutdown.signal).catch(() => {
+		const work = handleRequest(request, response, settings, dispatch, shutdown.signal, requests).catch(() => {
 			sendRefusal(response, 500, JSON_RPC_SERVER_ERROR, "Internal server error.");
 		});
 		inFlight.add(work);
@@ -1546,7 +1698,7 @@ async function startHttpServer(transport, dispatch) {
 * Validate and answer one HTTP request: path → Host / Origin → auth →
 * method → headers → body → JSON-RPC dispatch.
 */
-async function handleRequest(request, response, settings, dispatch, signal) {
+async function handleRequest(request, response, settings, dispatch, signal, requests) {
 	const headers = flattenHeaders(request.headers);
 	const method = (request.method ?? "GET").toUpperCase();
 	const path = new URL(request.url ?? "/", "http://localhost").pathname;
@@ -1568,8 +1720,10 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 		headers
 	};
 	if (request.socket.remoteAddress !== void 0) info.remoteAddress = request.socket.remoteAddress;
-	if (!await authorized(info, settings)) {
-		sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", settings.tokenDigests.length > 0 ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {});
+	const authentication = await authorized(info, settings);
+	if (!authentication.allowed) {
+		const challenge = settings.tokenDigests.length > 0 || settings.authenticate ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {};
+		sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", challenge);
 		return;
 	}
 	if (method !== "POST") {
@@ -1613,6 +1767,7 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 	const id = record.id;
 	if (typeof record.method === "string") {
 		if (typeof id !== "string" && typeof id !== "number") {
+			requests.cancel(record, cancellationScope(info));
 			sendEmpty(response, 202);
 			return;
 		}
@@ -1622,10 +1777,20 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 			method: record.method
 		};
 		if (record.params !== void 0) rpcRequest.params = record.params;
-		sendJson(response, 200, await dispatch(rpcRequest, {
-			request: info,
-			signal
-		}));
+		const disconnected = new AbortController();
+		const onClose = () => disconnected.abort();
+		response.once("close", onClose);
+		try {
+			const rpcResponse = await requests.run(rpcRequest, {
+				request: info,
+				principal: authentication.principal,
+				signal: AbortSignal.any([signal, disconnected.signal])
+			}, (context) => dispatch(rpcRequest, context), cancellationScope(info));
+			if (rpcResponse === void 0) sendEmpty(response, 202);
+			else sendJson(response, 200, rpcResponse);
+		} finally {
+			response.off("close", onClose);
+		}
 		return;
 	}
 	if ((typeof id === "string" || typeof id === "number") && ("result" in record || "error" in record)) {
@@ -1664,27 +1829,50 @@ function originAllowed(origin, settings) {
 	if (settings.allowedOrigins.has(parsed.origin)) return true;
 	return (parsed.protocol === "http:" || parsed.protocol === "https:") && isLoopbackHost(parsed.hostname);
 }
-/**
-* Run the configured auth. Bearer tokens are compared in constant time
-* over SHA-256 digests (equal-length buffers for `timingSafeEqual`), and
-* every configured token is compared so the match position does not leak.
-* An `authorize` hook that throws denies the request.
-*/
 async function authorized(info, settings) {
-	if (!settings.authRequired) return true;
+	if (!settings.authRequired) return { allowed: true };
 	if (settings.tokenDigests.length > 0) {
 		const match = /^Bearer[ \t]+(.+)$/i.exec(info.headers.authorization ?? "");
 		const presented = digest(match?.[1]?.trim() ?? "");
 		let matched = false;
 		for (const expected of settings.tokenDigests) matched = (0, node_crypto.timingSafeEqual)(presented, expected) || matched;
-		if (!match || !matched) return false;
+		if (!match || !matched) return { allowed: false };
 	}
-	if (settings.authorize) try {
-		return await settings.authorize(info) === true;
+	try {
+		if (settings.authorize && await settings.authorize(info) !== true) return { allowed: false };
+		if (settings.authenticate) {
+			const principal = await settings.authenticate(info);
+			return principal === void 0 ? { allowed: false } : {
+				allowed: true,
+				principal
+			};
+		}
+		return { allowed: true };
 	} catch {
-		return false;
-	}
-	return true;
+		return { allowed: false };
+	}
+}
+/**
+* Stateless HTTP has no connection/session id. Repeat the caller's credential
+* and application headers on notifications; per-message transport headers do
+* not identify a caller. Hash the material rather than retaining secrets as keys.
+*/
+function cancellationScope(info) {
+	const transportHeaders = /* @__PURE__ */ new Set([
+		"host",
+		"origin",
+		"accept",
+		"accept-encoding",
+		"accept-language",
+		"connection",
+		"content-type",
+		"content-length",
+		"transfer-encoding",
+		"mcp-protocol-version",
+		"user-agent"
+	]);
+	const credentials = Object.entries(info.headers).filter(([name]) => !transportHeaders.has(name)).sort(([left], [right]) => left.localeCompare(right));
+	return digest(JSON.stringify([info.remoteAddress, credentials])).toString("hex");
 }
 /** True for `application/json` (any parameters, e.g. `; charset=utf-8`). */
 function isJsonContentType(contentType) {
@@ -1859,7 +2047,10 @@ var McpServeHandler = class {
 	*/
 	async handle(request, context = {}) {
 		try {
-			return this.ok(request.id, await this.dispatch(request, context));
+			return this.ok(request.id, await this.dispatch(request, {
+				...context,
+				requestId: request.id
+			}));
 		} catch (cause) {
 			if (cause instanceof RpcFailure) return this.error(request.id, cause.code, cause.message, cause.data);
 			const message = cause instanceof Error ? cause.message : String(cause);
@@ -1872,19 +2063,19 @@ var McpServeHandler = class {
 			case "initialize": return this.initializeResult(request.params);
 			case "ping": return {};
 			case "tools/list": return { tools: this.listTools() };
-			case "tools/call": return this.callTool(request.params, context);
-			default: break;
+			case "tools/call": return this.callTool(request.params, {
+				...context,
+				requestId: request.id
+			});
 		}
 		if (this.resources) switch (request.method) {
 			case "resources/list": return { resources: this.listResources(this.resources) };
 			case "resources/templates/list": return { resourceTemplates: [] };
 			case "resources/read": return this.readResource(this.resources, request.params, context);
-			default: break;
 		}
 		if (this.prompts) switch (request.method) {
 			case "prompts/list": return { prompts: this.listPrompts(this.prompts) };
 			case "prompts/get": return this.getPrompt(this.prompts, request.params, context);
-			default: break;
 		}
 		throw new RpcFailure(JSON_RPC_METHOD_NOT_FOUND, `Method "${request.method}" is not supported by this MCP server.`);
 	}
@@ -1924,15 +2115,17 @@ var McpServeHandler = class {
 			return {
 				name,
 				description: contract.description,
-				inputSchema
+				inputSchema,
+				...isRecord(contract.meta?.outputSchema) ? { outputSchema: contract.meta.outputSchema } : {}
 			};
 		});
 	}
 	/**
 	* Route a `tools/call` to the named contract's `invoke()` and map the
 	* never-throwing {@link import("@warlock.js/ai").ToolInvokeResult}: `data`
-	* → a text content block, `error` → an `isError: true` result. An unknown
-	* tool name throws (mapped to a JSON-RPC error by {@link handle}).
+	* → a text content block (or an opted-in native result), `error` → an
+	* `isError: true` result. An unknown tool name throws (mapped to a
+	* JSON-RPC error by {@link handle}).
 	*
 	* The contract receives a `ToolContext` carrying the abort signal and,
 	* over HTTP, the inbound request's headers on `ctx.request`.
@@ -1944,7 +2137,11 @@ var McpServeHandler = class {
 			type: "protocol",
 			method: "tools/call"
 		});
-		const toolContext = { artifacts: {} };
+		const toolContext = {
+			artifacts: {},
+			requestId: context.requestId,
+			principal: context.principal
+		};
 		if (context.signal) toolContext.signal = context.signal;
 		if (context.request) {
 			const { headers, remoteAddress } = context.request;
@@ -1953,6 +2150,43 @@ var McpServeHandler = class {
 				remoteAddress
 			};
 		}
+		if (this.options.beforeCall) {
+			let input = args;
+			if (contract.input) {
+				let validation;
+				try {
+					validation = await contract.input["~standard"].validate(args);
+				} catch (cause) {
+					return {
+						content: [{
+							type: "text",
+							text: `Schema validation threw for tool "${name}": ${cause instanceof Error ? cause.message : String(cause)}`
+						}],
+						isError: true
+					};
+				}
+				if (validation.issues) return {
+					content: [{
+						type: "text",
+						text: `Validation failed: ${validation.issues.map((issue) => issue.message).join("; ")}`
+					}],
+					isError: true
+				};
+				input = validation.value;
+			}
+			context.signal?.throwIfAborted();
+			const refusal = await this.options.beforeCall(context, contract, input);
+			if (refusal !== void 0) {
+				try {
+					assertMcpResult(refusal);
+					if (refusal.isError !== true) throw new Error("A refusal must be an error result.");
+				} catch {
+					throw new RpcFailure(JSON_RPC_INTERNAL_ERROR, "Invalid MCP beforeCall refusal.");
+				}
+				return refusal;
+			}
+		}
+		context.signal?.throwIfAborted();
 		const result = await contract.invoke(args, toolContext);
 		if (result.error) return {
 			content: [{
@@ -1961,6 +2195,16 @@ var McpServeHandler = class {
 			}],
 			isError: true
 		};
+		const mode = contract.meta?.mcpResults ?? this.options.results ?? "text";
+		if (isMcpResult(result.data) || mode === "native" && looksLikeMcpResult(result.data)) {
+			const native = isMcpResult(result.data) ? unwrapMcpResult(result.data) : result.data;
+			try {
+				assertMcpResult(native);
+			} catch {
+				throw new RpcFailure(JSON_RPC_INTERNAL_ERROR, "Invalid native MCP CallToolResult.");
+			}
+			return native;
+		}
 		return {
 			content: [{
 				type: "text",
@@ -2073,7 +2317,7 @@ const JSON_RPC_INTERNAL_ERROR = -32603;
 * answered with a JSON-RPC "Invalid Request" error whose `id` is `null`.
 * Never rejects: a dispatch failure is answered as an internal error.
 */
-async function answerStdioLine(line, dispatch) {
+async function answerStdioLine(line, dispatch, notify) {
 	const trimmed = line.trim();
 	if (!trimmed) return;
 	let message;
@@ -2092,10 +2336,21 @@ async function answerStdioLine(line, dispatch) {
 	})}\n`;
 	const request = message;
 	const id = request.id;
-	if (id === void 0 || id === null) return;
+	if (id === void 0 || id === null) {
+		notify?.(message);
+		return;
+	}
+	if (typeof id !== "string" && typeof id !== "number") return `${JSON.stringify({
+		jsonrpc: JSONRPC_VERSION,
+		id: null,
+		error: {
+			code: JSON_RPC_INVALID_REQUEST,
+			message: "Invalid request: id must be a string or number."
+		}
+	})}\n`;
 	try {
 		const response = await dispatch(request);
-		return `${JSON.stringify(response)}\n`;
+		return response === void 0 ? void 0 : `${JSON.stringify(response)}\n`;
 	} catch {
 		return `${JSON.stringify({
 			jsonrpc: JSONRPC_VERSION,
@@ -2179,7 +2434,7 @@ var McpServerImpl = class {
 	start() {
 		if (!this.running) {
 			const transport = this.options.transport ?? { type: "stdio" };
-			const starting = transport.type === "http" ? this.startHttp(transport) : Promise.resolve(this.startStdio());
+			const starting = transport.type === "http" ? this.startHttp(transport) : Promise.resolve(this.startStdio(transport));
 			this.running = starting.catch((error) => {
 				this.running = void 0;
 				throw error;
@@ -2199,19 +2454,29 @@ var McpServerImpl = class {
 		};
 	}
 	/** Wire the stdin line reader and answer each request on stdout. */
-	startStdio() {
+	startStdio(transport) {
+		const shutdown = new AbortController();
+		const requests = new McpServeRequests();
 		const reader = (0, node_readline.createInterface)({ input: process.stdin });
+		reader.once("close", () => shutdown.abort());
 		reader.on("line", (line) => {
-			this.onLine(line).catch(() => {});
+			this.onLine(line, transport, requests, shutdown.signal).catch(() => {});
 		});
 		return { close: async () => {
+			shutdown.abort();
 			reader.close();
 			this.running = void 0;
 		} };
 	}
 	/** Answer one stdin line on stdout (see {@link answerStdioLine}). */
-	async onLine(line) {
-		const reply = await answerStdioLine(line, (request) => this.handler.handle(request));
+	async onLine(line, transport, requests, signal) {
+		const reply = await answerStdioLine(line, (request) => requests.run(request, { signal }, async (context) => {
+			const principal = transport.principalProvider ? await transport.principalProvider(context) : transport.principal;
+			return this.handler.handle(request, {
+				...context,
+				principal
+			});
+		}), (message) => requests.cancel(message));
 		if (reply !== void 0) process.stdout.write(reply);
 	}
 	async stop() {
@@ -2674,7 +2939,8 @@ const UNIT_ALIASES = {
 };
 /** Resolve a (possibly aliased / singular) unit token to its ms length. */
 function unitToMs(unit) {
-	const ms = UNIT_MS[UNIT_ALIASES[unit] ?? unit];
+	const canonical = UNIT_ALIASES[unit] ?? unit;
+	const ms = UNIT_MS[canonical];
 	if (ms === void 0) throw new DateTimeError(`Unknown unit "${unit}". Supported units: ${Object.keys(UNIT_MS).join(", ")}.`, { type: "invalid-unit" });
 	return ms;
 }
@@ -3114,7 +3380,8 @@ function fetchUrlTool(options) {
 					type: "denied-host",
 					cause
 				});
-				throw new WebToolError(`fetch_url request failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+				const message = cause instanceof Error ? cause.message : String(cause);
+				throw new WebToolError(`fetch_url request failed: ${message}`, {
 					type: "request-failed",
 					cause
 				});
@@ -3178,7 +3445,8 @@ async function fetchJson(url, init, provider) {
 	try {
 		response = await fetch(url, init);
 	} catch (cause) {
-		throw new WebToolError(`web_search request to the "${provider}" provider failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		throw new WebToolError(`web_search request to the "${provider}" provider failed: ${message}`, {
 			type: "request-failed",
 			cause
 		});
@@ -3283,9 +3551,7 @@ function webSearchTool(options) {
 				case "brave":
 					results = await searchBrave(input.query, limit, apiKey);
 					break;
-				case "serpapi":
-					results = await searchSerpApi(input.query, limit, apiKey);
-					break;
+				case "serpapi": results = await searchSerpApi(input.query, limit, apiKey);
 			}
 			return { results };
 		}
@@ -3321,6 +3587,7 @@ exports.fetchUrlTool = fetchUrlTool;
 exports.httpRequestTool = httpRequestTool;
 exports.jsonSchemaToStandard = jsonSchemaToStandard;
 exports.mcp = mcp;
+exports.mcpResult = mcpResult;
 exports.serve = serve;
 exports.webSearchTool = webSearchTool;
 //# sourceMappingURL=index.cjs.map