@warlock.js/ai-tools 5.34.0 → 5.34.2

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.34.2 - 2026-10-19
+
+### Fixed
+
+- Qualify custom-tool guidance as a topic of @warlock.js/ai, remove the redundant loose skill catalog, and include package orientation in LLM projections.
+
+## 5.34.1 - 2026-10-19
+
+### Added
+
+- HTTP `transport.onAuthRefusal` customizes denied authentication responses for the MCP endpoint and side routes using typed safe context, 4xx/5xx statuses, allowlisted headers and JSON bodies. Host/Origin guards retain precedence, invalid or throwing hooks retain the default refusal, and handlers never run after a denial.
+
+### Fixed
+
+- Tools adapted from a remote MCP server now show the model their real input schema. `jsonSchemaToStandard` implements Standard JSON Schema (`~standard.jsonSchema`), so `extractJsonSchema` and every provider adapter read the server's `inputSchema` instead of falling back to a parameterless `{ type: "object" }`, which made models guess argument names and retry. Adapters receive copies of the schema; a tool without one advertises `{ type: "object", properties: {} }`.
+
 ## 5.34.0 - 2026-10-19
 
 ### Added

package/README.md

@@ -162,7 +162,7 @@ if (error instanceof HttpPolicyError && error.type === "host-not-allowed") {
 
 ## Skills
 
-Progressive-disclosure, per-task docs live under [`skills/`](./skills/README.md):
+Progressive-disclosure, per-task docs live under [`skills/`](./skills/index.md):
 
 - [`use-web-and-http-tools/`](./skills/use-web-and-http-tools/SKILL.md) — wire `web_search`, `fetch_url`,
   `http_request`, `calculator`, and `date_time` into an agent under their guardrails.

package/cjs/index.cjs

@@ -587,42 +587,31 @@ function makeCompiler(schema) {
 	};
 }
 /**
-* Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose
-* `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`
-* (`{ "~standard": { version: 1, vendor, validate } }`) so it drops into
-* `tool({ input })` exactly like a native seal schema.
-*
-* Validation behavior:
-* - **Valid input** → `{ value }` (the input is passed through unchanged;
-*   Ajv validates, it does not transform).
-* - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +
-*   message per failure, so `tool()` produces a `SchemaValidationError`.
-* - **Missing `ajv` peer** → a single issue carrying the curated install
-*   string, surfaced the same way (a developer-facing message in logs).
-* - **No / empty schema** → an accept-all passthrough (an MCP tool may
-*   advertise no `inputSchema`).
-*
-* @param schema - The JSON Schema (an MCP tool's `inputSchema`), or
-*   `undefined` for a no-argument tool.
-* @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.
-*
-* @example
-* const input = jsonSchemaToStandard<{ q: string }>({
-*   type: "object",
-*   properties: { q: { type: "string" } },
-*   required: ["q"],
-* });
+* Standard JSON Schema converter returning a copy of the wrapped schema, so
+* provider adapters (which may compact or rewrite it) never mutate the source.
+* The remote server owns its schema, so every target receives it unchanged.
 */
+function exposeSchema(schema) {
+	return {
+		input: () => structuredClone(schema),
+		output: () => structuredClone(schema)
+	};
+}
 function jsonSchemaToStandard(schema) {
 	if (!schema || Object.keys(schema).length === 0) return { "~standard": {
 		version: 1,
 		vendor: VENDOR$2,
-		validate: (value) => ({ value })
+		validate: (value) => ({ value }),
+		jsonSchema: exposeSchema({
+			type: "object",
+			properties: {}
+		})
 	} };
 	const compile = makeCompiler(schema);
 	return { "~standard": {
 		version: 1,
 		vendor: VENDOR$2,
+		jsonSchema: exposeSchema(schema),
 		async validate(value) {
 			await loadAjv();
 			if (!isAjvAvailable) return { issues: [{ message: AJV_INSTALL_INSTRUCTIONS }] };
@@ -1621,6 +1610,7 @@ function resolveSettings(transport) {
 		tokenDigests: tokens.map(digest),
 		authorize: auth?.authorize,
 		authenticate: auth?.authenticate,
+		onAuthRefusal: transport.onAuthRefusal,
 		authRequired,
 		allowedOrigins: new Set((transport.allowedOrigins ?? []).map(normalizeOrigin)),
 		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name))),
@@ -1661,6 +1651,52 @@ function sendRefusal(response, status, code, message, headers = {}) {
 		}
 	}, headers);
 }
+const AUTH_REFUSAL_HEADERS = /* @__PURE__ */ new Set([
+	"www-authenticate",
+	"cache-control",
+	"retry-after",
+	"content-language",
+	"x-request-id"
+]);
+/** Snapshot plain JSON, rejecting cycles and values JSON would silently coerce/drop. */
+function copyRefusalBody(value, ancestors = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value !== "object" || value === null || ancestors.has(value)) throw new TypeError("Invalid auth refusal body.");
+	const prototype = Object.getPrototypeOf(value);
+	if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) throw new TypeError("Invalid auth refusal body.");
+	ancestors.add(value);
+	const result = Array.isArray(value) ? Array.from(value, (entry) => copyRefusalBody(entry, ancestors)) : Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, copyRefusalBody(entry, ancestors)]));
+	ancestors.delete(value);
+	return result;
+}
+/** A custom response can only end a denied exchange; it cannot authorize dispatch. */
+async function sendAuthRefusal(response, settings, context) {
+	const challenge = settings.tokenDigests.length > 0 || settings.authenticate ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {};
+	if (settings.onAuthRefusal) try {
+		const result = await settings.onAuthRefusal(Object.freeze(context));
+		if (!isRecord(result)) throw new TypeError("Invalid auth refusal response.");
+		const customStatus = result.status;
+		const status = customStatus === void 0 ? 401 : customStatus;
+		if (typeof status !== "number" || !Number.isInteger(status) || status < 400 || status > 599) throw new TypeError("Invalid auth refusal status.");
+		const headers = { ...challenge };
+		const customHeaders = result.headers;
+		if (customHeaders !== void 0) {
+			if (!isRecord(customHeaders)) throw new TypeError("Invalid auth refusal headers.");
+			const prototype = Object.getPrototypeOf(customHeaders);
+			if (prototype !== Object.prototype && prototype !== null) throw new TypeError("Invalid auth refusal headers.");
+			for (const [name, value] of Object.entries(customHeaders)) {
+				const normalized = name.toLowerCase();
+				if (!AUTH_REFUSAL_HEADERS.has(normalized) || typeof value !== "string") throw new TypeError("Invalid auth refusal header.");
+				(0, node_http.validateHeaderValue)(normalized, value);
+				headers[normalized] = value;
+			}
+		}
+		sendJson(response, status, copyRefusalBody(result.body), headers);
+		return;
+	} catch {}
+	sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", challenge);
+}
 /** Write an empty-bodied status (202 / 405). */
 function sendEmpty(response, status, headers = {}) {
 	if (response.headersSent || response.destroyed) return;
@@ -1776,8 +1812,12 @@ async function handleRequest(request, response, settings, dispatch, signal, requ
 	if (request.socket.remoteAddress !== void 0) info.remoteAddress = request.socket.remoteAddress;
 	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);
+		await sendAuthRefusal(response, settings, {
+			check: authentication.check,
+			method,
+			path,
+			target: routes ? "route" : "mcp"
+		});
 		return;
 	}
 	if (routes) {
@@ -1925,21 +1965,38 @@ async function authorized(info, settings) {
 		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 { allowed: false };
+		if (!match || !matched) return {
+			allowed: false,
+			check: "bearer"
+		};
 	}
-	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 };
+	if (settings.authorize) try {
+		if (await settings.authorize(info) !== true) return {
+			allowed: false,
+			check: "authorize"
+		};
 	} catch {
-		return { allowed: false };
+		return {
+			allowed: false,
+			check: "authorize"
+		};
+	}
+	if (settings.authenticate) try {
+		const principal = await settings.authenticate(info);
+		return principal === void 0 ? {
+			allowed: false,
+			check: "authenticate"
+		} : {
+			allowed: true,
+			principal
+		};
+	} catch {
+		return {
+			allowed: false,
+			check: "authenticate"
+		};
 	}
+	return { allowed: true };
 }
 /**
 * Stateless HTTP has no connection/session id. Repeat the caller's credential