@warlock.js/ai-tools 5.33.0 → 5.34.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.34.0 - 2026-10-19
+
+### Added
+
+- `ai.mcp.serve` supports async `listFilter(context, tools)` for per-request discovery independent of callability, and `validateCallParams(context, params)` for application envelope policy before lookup, schema validation and call policy, over HTTP and stdio. Default handling of unknown fields and unsupported task metadata is unchanged.
+- HTTP `transport.routes` adds exact method/path application routes beneath the MCP URL with shared authentication, principal/context, Host/Origin guards, body limits, disconnect signals and shutdown draining. Conflicting or invalid route configuration fails before binding.
+- Export `McpError(code, message, data?)` and the new discovery, envelope and HTTP route contracts.
+
+### Fixed
+
+- `beforeCall` and envelope policy preserve a thrown `McpError`'s integer code, message and optional data, including official SDK errors, without a runtime SDK dependency. Other throws retain the existing invalid-params mapping.
+- Extend the core `ai.tools` namespace on registration, preserving `catalogue` and `measure` while adding the ready-made factories. `AiToolsNamespace` remains re-exported for consumers.
+
 ## 5.33.0 - 2026-10-19
 
 ### Fixed
@@ -65,71 +78,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **BREAKING:** `ai.mcp.serve()` throws `McpServeError` (`type: "collision"`) when two exposed tools share a name, and for duplicate resource URIs or prompt names. Previously both tools were listed and every call reached the last one. Rename one tool, or serve a grouped source with `prefixToolNames: true`.
 - `serve(..., { transport: { type: "http" } }).start()` no longer rejects: it binds a real endpoint. Code that implemented `McpServer` itself must return a handle from `start()`.
 
-## 5.30.0 - 2026-10-16
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
-
 ## 5.29.0 - 2026-10-01
 
 ### Changed
 
-- Lockstep release; package APIs are unchanged. Skills refer to other topics by name instead of file paths, so cross-references keep working after `agent-kit` copies them into an app.
+- Skills refer to other topics by name instead of file paths, so cross-references keep working after `agent-kit` copies them into an app.
 
 ## 5.28.0 - 2026-10-01
 
 ### Changed
 
-- Lockstep release; package APIs are unchanged. `llms.txt` now lists every skill topic with its description (frontmatter in CRLF files was skipped).
-
-## 5.27.0 - 2026-10-01
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
-
-## 5.26.0 - 2026-09-30
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
-
-## 5.25.0 - 2026-09-28
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
-
-## 5.24.0 - 2026-09-27
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
-
-## 5.23.2 - 2026-09-26
-
-### Changed
-
-- Lockstep patch release; package APIs are unchanged.
-
-## 5.23.1 - 2026-09-26
-
-### Changed
-
-- Lockstep patch release; package APIs are unchanged.
-
-## 5.23.0 - 2026-09-25
-
-### Changed
-
-- Lockstep patch release; package APIs are unchanged.
-
-## 5.22.1 - 2026-09-25
-
-### Changed
-
-- Lockstep patch release; package APIs are unchanged.
+- `llms.txt` now lists every skill topic with its description (frontmatter in CRLF files was skipped).
 
 ## 5.22.0 - 2026-09-25
 
@@ -137,12 +96,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Stdio MCP children receive only a minimal execution environment plus explicitly supplied variables.
 
-## 5.21.0 - 2026-09-25
-
-### Changed
-
-- Lockstep release maintenance and dependency refresh.
-
 ## 5.20.0 - 2026-09-24
 
 ### Changed
@@ -155,53 +108,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Refined package skill-discovery descriptions and regenerated the llms projections.
 
-## 5.11.0 - 2026-09-14
-
-_Released in lockstep with the `@warlock.js/*` family; no package-specific changes in 5.11.0._
-
-## 5.10.0 - 2026-09-14
-
-_Released in lockstep with the `@warlock.js/*` family; no package-specific changes in 5.10.0._
-
-## 5.9.0 - 2026-09-13
-
-_Released in lockstep with the `@warlock.js/*` family; no package-specific changes in 5.9.0._
-
-## 5.2.3 - 2026-09-02
-
-### Fixed
-
-- Released in exact lockstep with Core's Web generator repairs so every family dependency remains installable at 5.2.3.
-
 ## 5.2.2
 
 ### Maintenance
 
 - Restored the Warlock family to one exact, installable lockstep version.
 
-## 5.1.0
-
-No changes to `@warlock.js/ai-tools`. Released in lockstep with the `@warlock.js/web`
-React-execution fix and the `@warlock.js/core` CLI additions — see those packages'
-changelogs.
-
-## 5.0.2 - 2026-08-25
-
-No changes to `@warlock.js/ai-tools`. Released in lockstep with the `@warlock.js/web` SSR
-fix (`ssr.noExternal`) — see that package's changelog.
-
-## 5.0.1 - 2026-08-25
-
-No changes to `@warlock.js/ai-tools`. Released in lockstep with the `create-warlock` vite
-resolution pin and the `@warlock.js/web` peer narrowing — see those packages'
-changelogs.
-
-## 5.0.0 - 2026-08-25
-
-### Changed
-
-- This package is unchanged in 5.0.0; its version moved only because the Warlock family releases in lockstep.
-
 ## 4.16.0 - 2026-08-18
 
 ### Security

package/cjs/index.cjs

@@ -1294,6 +1294,28 @@ function mcp$1(server, options) {
 	return new McpClientImpl(server, options);
 }
 
+//#endregion
+//#region ../../packages/ai-tools/src/mcp/error.ts
+/** An application-defined JSON-RPC error thrown by MCP serving policy hooks. */
+var McpError = class extends Error {
+	constructor(code, message, data) {
+		super(message);
+		this.name = "McpError";
+		this.code = code;
+		this.data = data;
+	}
+};
+/**
+* Recognize our error and the SDK's McpError without a runtime SDK dependency.
+* SDK source (checked 2026-10-19):
+* https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/src/types.ts
+* Only explicitly named errors with an integer code opt in; ordinary throws
+* retain the existing mapping. Preserve the error's message verbatim.
+*/
+function isMcpError(cause) {
+	return cause instanceof Error && cause.name === "McpError" && "code" in cause && typeof cause.code === "number" && Number.isInteger(cause.code);
+}
+
 //#endregion
 //#region ../../packages/ai-tools/src/mcp/protocol.ts
 /**
@@ -1465,7 +1487,7 @@ var McpServeRequests = class {
 * specification (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports,
 * checked 2026-10-17) on `node:http`, with no SDK dependency:
 *
-* - one endpoint path; each POST carries exactly one JSON-RPC message
+* - one MCP endpoint path (plus optional authenticated app routes); each MCP POST carries exactly one JSON-RPC message
 *   (batches were removed from the protocol in 2025-06-18 and get 400);
 * - a request is answered with `Content-Type: application/json` (the spec
 *   lets a server pick JSON or SSE per request); a notification or a
@@ -1523,6 +1545,35 @@ function hostnameOf(hostHeader) {
 function digest(value) {
 	return (0, node_crypto.createHash)("sha256").update(value, "utf8").digest();
 }
+/** Resolve exact descendant routes; no route may replace the MCP endpoint. */
+function resolveRoutes(path, routes) {
+	const resolved = /* @__PURE__ */ new Map();
+	const methods = /* @__PURE__ */ new Set([
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"HEAD",
+		"OPTIONS"
+	]);
+	if (routes.length > 0) {
+		let canonical = false;
+		try {
+			canonical = !path.startsWith("//") && new URL(path, "http://localhost").pathname === path;
+		} catch {}
+		if (!canonical) throw new McpServeError("MCP http routes require a canonical endpoint pathname.", { type: "config" });
+	}
+	for (const route of routes) {
+		if (!methods.has(route.method) || !/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/.test(route.path) || route.path.split("/").some((segment) => segment === "." || segment === "..") || typeof route.handler !== "function") throw new McpServeError("Invalid MCP http route method, path or handler.", { type: "config" });
+		const fullPath = `${path.replace(/\/+$/, "")}${route.path}`;
+		const byMethod = resolved.get(fullPath) ?? /* @__PURE__ */ new Map();
+		if (fullPath === path || byMethod.has(route.method)) throw new McpServeError(`MCP http route "${route.method} ${fullPath}" conflicts.`, { type: "collision" });
+		byMethod.set(route.method, { ...route });
+		resolved.set(fullPath, byMethod);
+	}
+	return resolved;
+}
 /** Normalise a configured origin to `scheme://host[:port]`, or throw a config error. */
 function normalizeOrigin(origin) {
 	try {
@@ -1572,7 +1623,8 @@ function resolveSettings(transport) {
 		authenticate: auth?.authenticate,
 		authRequired,
 		allowedOrigins: new Set((transport.allowedOrigins ?? []).map(normalizeOrigin)),
-		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name)))
+		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name))),
+		routes: resolveRoutes(path, transport.routes ?? [])
 	};
 }
 /** Flatten Node's header bag into lower-cased `name → value` strings. */
@@ -1695,13 +1747,15 @@ async function startHttpServer(transport, dispatch) {
 	};
 }
 /**
-* Validate and answer one HTTP request: path → Host / Origin → auth →
-* method → headers → body → JSON-RPC dispatch.
+* Validate and answer one HTTP request: Host / Origin → path → auth →
+* method → route handler or MCP headers/body/JSON-RPC dispatch.
 */
 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;
+	const url = new URL(request.url ?? "/", "http://localhost");
+	const path = url.pathname;
+	const routes = settings.routes.get(path);
 	if (!hostAllowed(headers.host, settings)) {
 		sendRefusal(response, 403, JSON_RPC_SERVER_ERROR, "Forbidden: Host header not allowed.");
 		return;
@@ -1710,7 +1764,7 @@ async function handleRequest(request, response, settings, dispatch, signal, requ
 		sendRefusal(response, 403, JSON_RPC_SERVER_ERROR, "Forbidden: Origin not allowed.");
 		return;
 	}
-	if (path !== settings.path) {
+	if (path !== settings.path && !routes) {
 		sendRefusal(response, 404, JSON_RPC_SERVER_ERROR, "Not found.");
 		return;
 	}
@@ -1726,6 +1780,15 @@ async function handleRequest(request, response, settings, dispatch, signal, requ
 		sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", challenge);
 		return;
 	}
+	if (routes) {
+		const route = routes.get(method);
+		if (!route) {
+			sendEmpty(response, 405, { allow: [...routes.keys()].sort().join(", ") });
+			return;
+		}
+		await handleRoute(request, response, route, info, url, authentication.principal, signal, settings);
+		return;
+	}
 	if (method !== "POST") {
 		sendEmpty(response, 405, { allow: "POST" });
 		return;
@@ -1799,6 +1862,32 @@ async function handleRequest(request, response, settings, dispatch, signal, requ
 	}
 	sendRefusal(response, 400, JSON_RPC_INVALID_REQUEST$1, "Invalid request: not a JSON-RPC message.");
 }
+/** Run a side route after the shared guards, tracking disconnect and shutdown. */
+async function handleRoute(request, response, route, info, url, principal, shutdown, settings) {
+	const disconnected = new AbortController();
+	const onClose = () => disconnected.abort();
+	response.once("close", onClose);
+	try {
+		const body = await readBody$1(request, settings.maxBodyBytes);
+		if (body.type === "too-large") {
+			sendRefusal(response, 413, JSON_RPC_SERVER_ERROR, `Request body exceeds ${settings.maxBodyBytes} bytes.`, { connection: "close" });
+			return;
+		}
+		const signal = AbortSignal.any([shutdown, disconnected.signal]);
+		signal.throwIfAborted();
+		const result = await route.handler({
+			request: info,
+			url,
+			principal,
+			body: body.text,
+			signal
+		});
+		if (result.body === void 0 || info.method === "HEAD") sendEmpty(response, result.status ?? 200, result.headers);
+		else sendJson(response, result.status ?? 200, result.body, result.headers);
+	} finally {
+		response.off("close", onClose);
+	}
+}
 /**
 * Host-header check. While bound to loopback only loopback names (plus
 * `allowedHosts`) are accepted, so a DNS-rebound name pointing at
@@ -2062,7 +2151,10 @@ var McpServeHandler = class {
 		switch (request.method) {
 			case "initialize": return this.initializeResult(request.params);
 			case "ping": return {};
-			case "tools/list": return { tools: this.listTools() };
+			case "tools/list": return { tools: await this.listTools({
+				...context,
+				requestId: request.id
+			}) };
 			case "tools/call": return this.callTool(request.params, {
 				...context,
 				requestId: request.id
@@ -2105,9 +2197,9 @@ var McpServeHandler = class {
 	* the configured dialect (default `draft-2020-12` — overriding
 	* `extractJsonSchema`'s own `openai-strict` default to a neutral MCP draft).
 	*/
-	listTools() {
+	async listTools(context) {
 		const target = this.options.schemaTarget ?? DEFAULT_SCHEMA_TARGET;
-		return this.tools.map(({ name, contract }) => {
+		const tools = this.tools.map(({ name, contract }) => {
 			const inputSchema = (0, _warlock_js_ai.extractJsonSchema)(contract.input, { target }) ?? {
 				type: "object",
 				properties: {}
@@ -2119,6 +2211,8 @@ var McpServeHandler = class {
 				...isRecord(contract.meta?.outputSchema) ? { outputSchema: contract.meta.outputSchema } : {}
 			};
 		});
+		context.signal?.throwIfAborted();
+		return this.options.listFilter ? this.options.listFilter(context, tools) : tools;
 	}
 	/**
 	* Route a `tools/call` to the named contract's `invoke()` and map the
@@ -2132,6 +2226,15 @@ var McpServeHandler = class {
 	*/
 	async callTool(params, context) {
 		const { name, args } = readCallParams(params);
+		if (this.options.validateCallParams) {
+			context.signal?.throwIfAborted();
+			try {
+				await this.options.validateCallParams(context, readRecord(params));
+			} catch (cause) {
+				if (isMcpError(cause)) throw new RpcFailure(cause.code, cause.message, cause.data);
+				throw cause;
+			}
+		}
 		const contract = this.byName.get(name);
 		if (!contract) throw new McpTransportError(`Unknown tool "${name}".`, {
 			type: "protocol",
@@ -2175,7 +2278,13 @@ var McpServeHandler = class {
 				input = validation.value;
 			}
 			context.signal?.throwIfAborted();
-			const refusal = await this.options.beforeCall(context, contract, input);
+			let refusal;
+			try {
+				refusal = await this.options.beforeCall(context, contract, input);
+			} catch (cause) {
+				if (isMcpError(cause)) throw new RpcFailure(cause.code, cause.message, cause.data);
+				throw cause;
+			}
 			if (refusal !== void 0) {
 				try {
 					assertMcpResult(refusal);
@@ -3560,20 +3669,20 @@ function webSearchTool(options) {
 
 //#endregion
 //#region ../../packages/ai-tools/src/register.ts
-_warlock_js_ai.ai.tools = {
+Object.assign(_warlock_js_ai.ai.tools, {
 	webSearch: webSearchTool,
 	fetchUrl: fetchUrlTool,
 	http: httpRequestTool,
 	calculator: calculatorTool,
-	dateTime: (options) => dateTimeTool(options),
-	measure: _warlock_js_ai.measureTools
-};
+	dateTime: (options) => dateTimeTool(options)
+});
 _warlock_js_ai.ai.mcp = mcp;
 
 //#endregion
 exports.CalculatorError = CalculatorError;
 exports.DateTimeError = DateTimeError;
 exports.HttpPolicyError = HttpPolicyError;
+exports.McpError = McpError;
 exports.McpServeError = McpServeError;
 exports.McpTransportError = McpTransportError;
 exports.SUPPORTED_PROTOCOL_VERSIONS = SUPPORTED_PROTOCOL_VERSIONS;