@warlock.js/ai-tools 5.31.0 → 5.32.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.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
@@ -1342,7 +1351,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",
@@ -1569,7 +1578,8 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 	};
 	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 challenge = settings.tokenDigests.length > 0 ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {};
+		sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", challenge);
 		return;
 	}
 	if (method !== "POST") {
@@ -1741,6 +1751,89 @@ function readBody$1(request, limit) {
 	});
 }
 
+//#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.ts
 /** JSON-RPC version literal every outbound message carries. */
@@ -1873,18 +1966,15 @@ var McpServeHandler = class {
 			case "ping": return {};
 			case "tools/list": return { tools: this.listTools() };
 			case "tools/call": return this.callTool(request.params, context);
-			default: break;
 		}
 		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 +2014,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`.
@@ -1961,6 +2053,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",
@@ -2674,7 +2776,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 +3217,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 +3282,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 +3388,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 +3424,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