@rulvar/core 1.168.0 → 1.170.0

package/dist/index.d.ts

@@ -10809,6 +10809,58 @@ interface McpConfig {
   approval?: boolean | Record<string, boolean>;
   /** Host-supplied risk labels for imported tools. */
   risk?: Record<string, ToolRisk>;
+  /**
+  * Cap on WIRE tools accepted from the tools/list sweep (RV1515),
+  * checked after each page, PRE-filter: the sweep itself is the
+  * resource being bounded, so allow/deny cannot admit past it. A
+  * server that streams more refuses typed. Positive integer; absent =
+  * unbounded (today's behavior).
+  */
+  maxTools?: number;
+  /**
+  * Per ADMITTED tool (allow/deny filter first): the UTF-8 byte length
+  * of the serialized inputSchema plus outputSchema when present
+  * (RV1515). An oversized tool refuses the resolution typed, naming
+  * the tool and its measured bytes; deny the tool or raise the cap.
+  * Positive integer; absent = unbounded.
+  */
+  maxSchemaBytes?: number;
+  /**
+  * Per-source latency bounds (RV1515). connectMs races the transport
+  * handshake (on expiry the client, and for stdio its child, is
+  * released and the refusal is typed). listMs and callMs ride the SDK
+  * request timeout per tools/list page and per tools/call; without
+  * them the SDK's own 60s default request timeout applies. A call
+  * timeout surfaces as the tool's error result, never past policy.
+  * Each a positive finite number of milliseconds.
+  */
+  timeouts?: {
+    connectMs?: number;
+    listMs?: number;
+    callMs?: number;
+  };
+  /**
+  * streamable-http only (RV1516): headers injected into EVERY wire
+  * request through a wrapped fetch. The hook form is awaited before
+  * each send, so it IS the refresh point: rotate a token in the hook
+  * and the next request carries it, with no reconnect and no
+  * library-invented 401 retry (transport failures surface exactly as
+  * before; the engine's RetryPolicy owns retries).
+  */
+  http?: {
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+  };
+  /**
+  * What a listChanged notification means for THIS source (RV1516).
+  * 'rekey' is the documented default: the session cache invalidates
+  * and subsequently spawned agents import the changed list under a new
+  * toolsetHash. 'refuse' fails closed instead: the notification
+  * poisons the source, every later tools() call refuses typed, and
+  * only close() (a deliberate host reset) clears it. In-flight spawn
+  * snapshots are untouched either way. Composes with the toolset
+  * attestation: refuse at the source vs refuse at the spawn.
+  */
+  drift?: "rekey" | "refuse";
 }
 /**
 * The ToolSource returned by {@link mcp}: the frozen ToolSource seam

package/dist/index.js

@@ -3879,7 +3879,27 @@ function buildToolContext(seed) {
 *
 * Docs: https://docs.rulvar.com/guide/mcp.
 */
+function validateBounds(cfg) {
+	const positiveInt = (key) => {
+		const value = cfg[key];
+		if (value !== void 0 && (!Number.isInteger(value) || value <= 0)) throw new ConfigError(`mcp: '${key}' must be a positive integer, got ${String(value)}`);
+	};
+	positiveInt("maxTools");
+	positiveInt("maxSchemaBytes");
+	for (const key of [
+		"connectMs",
+		"listMs",
+		"callMs"
+	]) {
+		const value = cfg.timeouts?.[key];
+		if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) throw new ConfigError(`mcp: 'timeouts.${key}' must be a positive finite number of milliseconds, got ${String(value)}`);
+	}
+	if (cfg.drift !== void 0 && cfg.drift !== "rekey" && cfg.drift !== "refuse") throw new ConfigError(`mcp: 'drift' must be 'rekey' or 'refuse', got '${String(cfg.drift)}'`);
+	const headers = cfg.http?.headers;
+	if (headers !== void 0 && typeof headers !== "function" && typeof headers !== "object") throw new ConfigError("mcp: 'http.headers' must be a record of header values or a (possibly async) function returning one");
+}
 function validateConfig(cfg) {
+	validateBounds(cfg);
 	const forbid = (key) => {
 		if (cfg[key] !== void 0) throw new ConfigError(`mcp: '${key}' is not a config key of the '${cfg.transport}' transport (exactly the keys matching the chosen transport)`);
 	};
@@ -3888,6 +3908,7 @@ function validateConfig(cfg) {
 			if (cfg.command === void 0) throw new ConfigError("mcp: the stdio transport requires 'command'");
 			forbid("url");
 			forbid("server");
+			forbid("http");
 			return;
 		case "streamable-http":
 			if (cfg.url === void 0) throw new ConfigError("mcp: the streamable-http transport requires 'url'");
@@ -3900,6 +3921,7 @@ function validateConfig(cfg) {
 			forbid("command");
 			forbid("args");
 			forbid("url");
+			forbid("http");
 			return;
 		default: throw new ConfigError(`mcp: unknown transport '${String(cfg.transport)}'`);
 	}
@@ -3920,6 +3942,23 @@ function mapContent(result) {
 		text: block.text ?? ""
 	} : block);
 }
+/**
+* Wraps fetch so EVERY wire request of the streamable-http transport
+* consults the declared headers before send (RV1516): the hook form is
+* the per-request refresh point for rotating tokens, so no reconnect
+* and no library-invented 401 retry exists or is needed.
+*/
+function perRequestHeaders(headersOption) {
+	return async (url, init) => {
+		const extra = typeof headersOption === "function" ? await headersOption() : headersOption;
+		const headers = new Headers(init?.headers);
+		for (const [name, value] of Object.entries(extra ?? {})) headers.set(name, value);
+		return fetch(url, {
+			...init,
+			headers
+		});
+	};
+}
 function errorText(result) {
 	const text = (result.content ?? []).filter((block) => block.type === "text").map((block) => block.text ?? "").join("");
 	return text === "" ? "MCP tool reported an error" : text;
@@ -3942,12 +3981,13 @@ function mcp(cfg) {
 	let cache;
 	let generation = 0;
 	let inFlight;
+	let poisoned = false;
 	const connect = async () => {
 		const client = new Client({
 			name: "rulvar",
 			version: "1.0.0"
 		});
-		try {
+		const attach = async () => {
 			if (cfg.transport === "stdio") {
 				const transport = new StdioClientTransport({
 					command: cfg.command ?? "",
@@ -3955,13 +3995,31 @@ function mcp(cfg) {
 				});
 				await client.connect(transport);
 			} else if (cfg.transport === "streamable-http") {
-				const transport = new StreamableHTTPClientTransport(new URL(cfg.url ?? ""));
+				const declaredHeaders = cfg.http?.headers;
+				const transport = new StreamableHTTPClientTransport(new URL(cfg.url ?? ""), declaredHeaders === void 0 ? void 0 : { fetch: perRequestHeaders(declaredHeaders) });
 				await client.connect(transport);
 			} else {
 				const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
 				await cfg.server.connect(serverTransport);
 				await client.connect(clientTransport);
 			}
+		};
+		try {
+			const budgetMs = cfg.timeouts?.connectMs;
+			if (budgetMs === void 0) await attach();
+			else {
+				let timer;
+				const expired = new Promise((_resolve, reject) => {
+					timer = setTimeout(() => {
+						reject(new ConfigError(`mcp: connect to '${sourceIdOf(cfg)}' timed out after ${budgetMs}ms`));
+					}, budgetMs);
+				});
+				try {
+					await Promise.race([attach(), expired]);
+				} finally {
+					clearTimeout(timer);
+				}
+			}
 		} catch (error) {
 			await client.close().catch(() => void 0);
 			throw error;
@@ -3969,19 +4027,27 @@ function mcp(cfg) {
 		client.setNotificationHandler(ToolListChangedNotificationSchema, () => {
 			generation += 1;
 			cache = void 0;
+			if (cfg.drift === "refuse") poisoned = true;
 		});
 		return client;
 	};
 	const listAll = async (client) => {
 		const tools = [];
 		let cursor;
+		const listOptions = cfg.timeouts?.listMs === void 0 ? void 0 : { timeout: cfg.timeouts.listMs };
 		do {
-			const page = await client.listTools(cursor === void 0 ? {} : { cursor });
+			const page = await client.listTools(cursor === void 0 ? {} : { cursor }, listOptions);
 			tools.push(...page.tools);
+			if (cfg.maxTools !== void 0 && tools.length > cfg.maxTools) throw new ConfigError(`mcp: tools/list of '${sourceIdOf(cfg)}' returned at least ${tools.length} wire tools, over the declared maxTools ${cfg.maxTools}; raise the cap or trim the server`);
 			cursor = page.nextCursor;
 		} while (cursor !== void 0 && cursor !== "");
 		return tools;
 	};
+	const enforceSchemaBytes = (wire) => {
+		if (cfg.maxSchemaBytes === void 0) return;
+		const bytes = Buffer.byteLength(JSON.stringify(wire.inputSchema) + (wire.outputSchema === void 0 ? "" : JSON.stringify(wire.outputSchema)), "utf8");
+		if (bytes > cfg.maxSchemaBytes) throw new ConfigError(`mcp: tool '${wire.name}' declares ${bytes} bytes of schema, over the declared maxSchemaBytes ${cfg.maxSchemaBytes}; deny the tool or raise the cap`);
+	};
 	const needsApprovalFor = (originalName) => {
 		if (cfg.approval === void 0) return false;
 		if (typeof cfg.approval === "boolean") return cfg.approval;
@@ -4001,7 +4067,7 @@ function mcp(cfg) {
 				const result = await client.callTool({
 					name: wire.name,
 					arguments: input ?? {}
-				});
+				}, void 0, cfg.timeouts?.callMs === void 0 ? void 0 : { timeout: cfg.timeouts.callMs });
 				if (result.isError === true) throw new Error(errorText(result));
 				if (result.structuredContent !== void 0) {
 					if (wire.outputSchema !== void 0) {
@@ -4017,6 +4083,7 @@ function mcp(cfg) {
 	return {
 		id: sourceIdOf(cfg),
 		tools: async () => {
+			if (poisoned) throw new ConfigError(`mcp: the tool list of '${sourceIdOf(cfg)}' changed after import (listChanged) and drift policy 'refuse' holds the source closed; close() and re-create the source (and re-record any toolset attestation) to import the changed list deliberately`);
 			if (cache !== void 0) return cache;
 			if (inFlight !== void 0) return inFlight;
 			const fetch = (async () => {
@@ -4026,7 +4093,9 @@ function mcp(cfg) {
 				const wireTools = await listAll(client);
 				const denySet = new Set(cfg.deny ?? []);
 				const allowSet = cfg.allow === void 0 ? void 0 : new Set(cfg.allow);
-				const defs = wireTools.filter((wire) => !denySet.has(wire.name) && (allowSet === void 0 || allowSet.has(wire.name))).map((wire) => toDef(client, wire));
+				const admitted = wireTools.filter((wire) => !denySet.has(wire.name) && (allowSet === void 0 || allowSet.has(wire.name)));
+				for (const wire of admitted) enforceSchemaBytes(wire);
+				const defs = admitted.map((wire) => toDef(client, wire));
 				if (generation === fetchedAt) cache = defs;
 				return defs;
 			})();
@@ -4041,6 +4110,7 @@ function mcp(cfg) {
 			const pending = clientPromise;
 			clientPromise = void 0;
 			cache = void 0;
+			poisoned = false;
 			if (pending === void 0) return;
 			let client;
 			try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.168.0",
+  "version": "1.170.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",