@rulvar/executor 1.246.0 → 1.247.0

package/dist/index.js

@@ -231,126 +231,143 @@ function subprocessExecutor(options = {}) {
 	const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
 	const workdirBase = options.workdirBase ?? tmpdir();
 	const now = options.now ?? wallClock$2;
-	return { async run(request) {
-		const { command, args } = resolveCommand(request, options);
-		const workdir = await mkdtemp(join(workdirBase, `rulvar-exec-${request.tool}-`));
-		const startedAt = now();
-		const argsHash = hashArgs(request.args);
-		const attemptId = randomUUID();
-		if (options.ledger?.intent !== void 0) try {
-			await options.ledger.intent({
-				idempotencyKey: request.ctx.idempotencyKey,
-				runId: request.ctx.runId,
-				spanId: request.ctx.spanId,
-				tool: request.tool,
-				argsHash,
-				executor: request.executor,
-				workdir,
-				startedAt,
-				attemptId
-			});
-		} catch (err) {
-			await rm(workdir, {
-				recursive: true,
-				force: true
-			});
-			throw new ExecutorError("ledger", `tool '${request.tool}' was not dispatched: the two-phase ledger intent write failed (${err instanceof Error ? err.message : String(err)})`);
-		}
-		let outcome = "error";
-		let exitCode = null;
-		let signal = null;
-		let settled;
-		let bodyThrew = false;
-		let thrownBody;
-		try {
-			const env = {};
-			for (const name of options.allowEnv ?? []) {
-				const value = process.env[name];
-				if (value !== void 0) env[name] = value;
+	return {
+		describeRegulatedPosture: () => ({
+			regulatedPosture: 1,
+			kind: "tool-executor",
+			name: "subprocess",
+			ledger: options.ledger !== void 0,
+			allowEnv: [...options.allowEnv ?? []],
+			bounds: {
+				timeoutMs,
+				maxOutputBytes
+			},
+			isolation: {
+				flavor: "subprocess",
+				sandboxed: options.sandbox !== void 0
 			}
-			const creds = options.credentials === void 0 ? {} : await options.credentials(request);
-			Object.assign(env, creds);
-			env.RULVAR_TOOL = request.tool;
-			env.RULVAR_RUN_ID = request.ctx.runId;
-			env.RULVAR_IDEMPOTENCY_KEY = request.ctx.idempotencyKey;
-			const wrapper = options.sandbox === void 0 ? [] : [...options.sandbox({
-				workdir,
-				request
-			})];
-			const [spawnCommand, ...spawnPrefix] = wrapper.length > 0 ? wrapper : [command];
-			const spawnArgs = wrapper.length > 0 ? [
-				...spawnPrefix,
-				command,
-				...args
-			] : args;
-			let child;
-			try {
-				child = await runChildProcess({
-					command: spawnCommand,
-					args: spawnArgs,
-					env,
-					cwd: workdir,
-					stdinData: JSON.stringify({
-						tool: request.tool,
-						args: request.args,
-						idempotencyKey: request.ctx.idempotencyKey
-					}),
-					timeoutMs,
-					killGraceMs,
-					maxOutputBytes,
-					signal: request.ctx.signal
+		}),
+		async run(request) {
+			const { command, args } = resolveCommand(request, options);
+			const workdir = await mkdtemp(join(workdirBase, `rulvar-exec-${request.tool}-`));
+			const startedAt = now();
+			const argsHash = hashArgs(request.args);
+			const attemptId = randomUUID();
+			if (options.ledger?.intent !== void 0) try {
+				await options.ledger.intent({
+					idempotencyKey: request.ctx.idempotencyKey,
+					runId: request.ctx.runId,
+					spanId: request.ctx.spanId,
+					tool: request.tool,
+					argsHash,
+					executor: request.executor,
+					workdir,
+					startedAt,
+					attemptId
 				});
 			} catch (err) {
-				throw new ExecutorError("spawn", `tool '${request.tool}' could not be spawned: ${err instanceof Error ? err.message : String(err)}`);
+				await rm(workdir, {
+					recursive: true,
+					force: true
+				});
+				throw new ExecutorError("ledger", `tool '${request.tool}' was not dispatched: the two-phase ledger intent write failed (${err instanceof Error ? err.message : String(err)})`);
 			}
-			exitCode = child.code;
-			signal = child.signal;
-			if (child.stopped && child.reason === "timeout") {
-				outcome = "timeout";
-				throw new ExecutorError("timeout", `tool '${request.tool}' exceeded ${timeoutMs}ms and was killed`);
+			let outcome = "error";
+			let exitCode = null;
+			let signal = null;
+			let settled;
+			let bodyThrew = false;
+			let thrownBody;
+			try {
+				const env = {};
+				for (const name of options.allowEnv ?? []) {
+					const value = process.env[name];
+					if (value !== void 0) env[name] = value;
+				}
+				const creds = options.credentials === void 0 ? {} : await options.credentials(request);
+				Object.assign(env, creds);
+				env.RULVAR_TOOL = request.tool;
+				env.RULVAR_RUN_ID = request.ctx.runId;
+				env.RULVAR_IDEMPOTENCY_KEY = request.ctx.idempotencyKey;
+				const wrapper = options.sandbox === void 0 ? [] : [...options.sandbox({
+					workdir,
+					request
+				})];
+				const [spawnCommand, ...spawnPrefix] = wrapper.length > 0 ? wrapper : [command];
+				const spawnArgs = wrapper.length > 0 ? [
+					...spawnPrefix,
+					command,
+					...args
+				] : args;
+				let child;
+				try {
+					child = await runChildProcess({
+						command: spawnCommand,
+						args: spawnArgs,
+						env,
+						cwd: workdir,
+						stdinData: JSON.stringify({
+							tool: request.tool,
+							args: request.args,
+							idempotencyKey: request.ctx.idempotencyKey
+						}),
+						timeoutMs,
+						killGraceMs,
+						maxOutputBytes,
+						signal: request.ctx.signal
+					});
+				} catch (err) {
+					throw new ExecutorError("spawn", `tool '${request.tool}' could not be spawned: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				exitCode = child.code;
+				signal = child.signal;
+				if (child.stopped && child.reason === "timeout") {
+					outcome = "timeout";
+					throw new ExecutorError("timeout", `tool '${request.tool}' exceeded ${timeoutMs}ms and was killed`);
+				}
+				if (child.stopped && child.reason === "aborted") throw new ExecutorError("aborted", `tool '${request.tool}' was cancelled`);
+				if (child.stopped && child.reason === "output-cap") throw new ExecutorError("output-cap", `tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
+				if (child.code !== 0) {
+					const tail = child.stderr.trim().slice(-500);
+					throw new ExecutorError("exit", `tool '${request.tool}' exited ${child.code ?? "null"}${child.signal === null ? "" : ` (signal ${child.signal})`}${tail === "" ? "" : `: ${tail}`}`);
+				}
+				const result = parseToolResult(child.stdout, request.tool);
+				outcome = "ok";
+				settled = result;
+			} catch (thrown) {
+				bodyThrew = true;
+				thrownBody = thrown;
 			}
-			if (child.stopped && child.reason === "aborted") throw new ExecutorError("aborted", `tool '${request.tool}' was cancelled`);
-			if (child.stopped && child.reason === "output-cap") throw new ExecutorError("output-cap", `tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
-			if (child.code !== 0) {
-				const tail = child.stderr.trim().slice(-500);
-				throw new ExecutorError("exit", `tool '${request.tool}' exited ${child.code ?? "null"}${child.signal === null ? "" : ` (signal ${child.signal})`}${tail === "" ? "" : `: ${tail}`}`);
+			const durationMs = now() - startedAt;
+			let ledgerFailure;
+			try {
+				if (options.ledger !== void 0) await options.ledger.record({
+					idempotencyKey: request.ctx.idempotencyKey,
+					runId: request.ctx.runId,
+					spanId: request.ctx.spanId,
+					tool: request.tool,
+					argsHash,
+					executor: request.executor,
+					workdir,
+					startedAt,
+					attemptId,
+					durationMs,
+					outcome,
+					exitCode,
+					signal
+				});
+			} catch (recordErr) {
+				ledgerFailure = new ExecutorError("ledger", `tool '${request.tool}' outcome was not recorded: the ledger record write failed (${recordErr instanceof Error ? recordErr.message : String(recordErr)})` + (bodyThrew ? `; the dispatch itself had already failed (${thrownBody instanceof Error ? thrownBody.message : String(thrownBody)})` : ""));
 			}
-			const result = parseToolResult(child.stdout, request.tool);
-			outcome = "ok";
-			settled = result;
-		} catch (thrown) {
-			bodyThrew = true;
-			thrownBody = thrown;
-		}
-		const durationMs = now() - startedAt;
-		let ledgerFailure;
-		try {
-			if (options.ledger !== void 0) await options.ledger.record({
-				idempotencyKey: request.ctx.idempotencyKey,
-				runId: request.ctx.runId,
-				spanId: request.ctx.spanId,
-				tool: request.tool,
-				argsHash,
-				executor: request.executor,
-				workdir,
-				startedAt,
-				attemptId,
-				durationMs,
-				outcome,
-				exitCode,
-				signal
+			await rm(workdir, {
+				recursive: true,
+				force: true
 			});
-		} catch (recordErr) {
-			ledgerFailure = new ExecutorError("ledger", `tool '${request.tool}' outcome was not recorded: the ledger record write failed (${recordErr instanceof Error ? recordErr.message : String(recordErr)})` + (bodyThrew ? `; the dispatch itself had already failed (${thrownBody instanceof Error ? thrownBody.message : String(thrownBody)})` : ""));
+			if (ledgerFailure !== void 0) throw ledgerFailure;
+			if (bodyThrew) throw thrownBody;
+			return settled;
 		}
-		await rm(workdir, {
-			recursive: true,
-			force: true
-		});
-		if (ledgerFailure !== void 0) throw ledgerFailure;
-		if (bodyThrew) throw thrownBody;
-		return settled;
-	} };
+	};
 }
 /**
 * Defines a tool that runs under a subprocess (or container) executor.
@@ -431,150 +448,168 @@ function containerExecutor(options) {
 	const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
 	const workdirBase = options.workdirBase ?? tmpdir();
 	const now = options.now ?? wallClock$1;
-	return { async run(request) {
-		const spec = request.spec ?? {};
-		const command = typeof spec.command === "string" ? spec.command : options.command;
-		if (command === void 0 || command === "") throw new ExecutorError("config", `tool '${request.tool}' has no command: set executorSpec.command or the executor command`);
-		const specArgs = Array.isArray(spec.args) ? spec.args.filter((a) => typeof a === "string") : [];
-		const toolArgs = [...options.args ?? [], ...specArgs];
-		const workdir = await mkdtemp(join(workdirBase, `rulvar-cexec-${request.tool}-`));
-		const startedAt = now();
-		const argsHash = hashArgs(request.args);
-		const attemptId = randomUUID();
-		if (options.ledger?.intent !== void 0) try {
-			await options.ledger.intent({
-				idempotencyKey: request.ctx.idempotencyKey,
-				runId: request.ctx.runId,
-				spanId: request.ctx.spanId,
-				tool: request.tool,
-				argsHash,
-				executor: request.executor,
-				workdir,
-				startedAt,
-				attemptId
-			});
-		} catch (err) {
-			await rm(workdir, {
-				recursive: true,
-				force: true
-			});
-			throw new ExecutorError("ledger", `container tool '${request.tool}' was not dispatched: the two-phase ledger intent write failed (${err instanceof Error ? err.message : String(err)})`);
-		}
-		let outcome = "error";
-		let exitCode = null;
-		let signal = null;
-		let settled;
-		let bodyThrew = false;
-		let thrownBody;
-		try {
-			const daemonEnv = options.daemonEnv ?? DEFAULT_DAEMON_ENV;
-			const env = {};
-			for (const name of daemonEnv) {
-				const value = process.env[name];
-				if (value !== void 0) env[name] = value;
+	return {
+		describeRegulatedPosture: () => ({
+			regulatedPosture: 1,
+			kind: "tool-executor",
+			name: "container",
+			ledger: options.ledger !== void 0,
+			allowEnv: [...options.forwardEnv ?? []],
+			bounds: {
+				timeoutMs,
+				maxOutputBytes
+			},
+			isolation: {
+				flavor: "container",
+				network,
+				readOnlyRoot: readOnly
 			}
-			const forwardNames = /* @__PURE__ */ new Set([
-				"RULVAR_TOOL",
-				"RULVAR_RUN_ID",
-				"RULVAR_IDEMPOTENCY_KEY"
-			]);
-			for (const name of options.forwardEnv ?? []) {
-				const value = process.env[name];
-				if (value !== void 0) {
+		}),
+		async run(request) {
+			const spec = request.spec ?? {};
+			const command = typeof spec.command === "string" ? spec.command : options.command;
+			if (command === void 0 || command === "") throw new ExecutorError("config", `tool '${request.tool}' has no command: set executorSpec.command or the executor command`);
+			const specArgs = Array.isArray(spec.args) ? spec.args.filter((a) => typeof a === "string") : [];
+			const toolArgs = [...options.args ?? [], ...specArgs];
+			const workdir = await mkdtemp(join(workdirBase, `rulvar-cexec-${request.tool}-`));
+			const startedAt = now();
+			const argsHash = hashArgs(request.args);
+			const attemptId = randomUUID();
+			if (options.ledger?.intent !== void 0) try {
+				await options.ledger.intent({
+					idempotencyKey: request.ctx.idempotencyKey,
+					runId: request.ctx.runId,
+					spanId: request.ctx.spanId,
+					tool: request.tool,
+					argsHash,
+					executor: request.executor,
+					workdir,
+					startedAt,
+					attemptId
+				});
+			} catch (err) {
+				await rm(workdir, {
+					recursive: true,
+					force: true
+				});
+				throw new ExecutorError("ledger", `container tool '${request.tool}' was not dispatched: the two-phase ledger intent write failed (${err instanceof Error ? err.message : String(err)})`);
+			}
+			let outcome = "error";
+			let exitCode = null;
+			let signal = null;
+			let settled;
+			let bodyThrew = false;
+			let thrownBody;
+			try {
+				const daemonEnv = options.daemonEnv ?? DEFAULT_DAEMON_ENV;
+				const env = {};
+				for (const name of daemonEnv) {
+					const value = process.env[name];
+					if (value !== void 0) env[name] = value;
+				}
+				const forwardNames = /* @__PURE__ */ new Set([
+					"RULVAR_TOOL",
+					"RULVAR_RUN_ID",
+					"RULVAR_IDEMPOTENCY_KEY"
+				]);
+				for (const name of options.forwardEnv ?? []) {
+					const value = process.env[name];
+					if (value !== void 0) {
+						env[name] = value;
+						forwardNames.add(name);
+					}
+				}
+				const creds = options.credentials === void 0 ? {} : await options.credentials(request);
+				for (const [name, value] of Object.entries(creds)) {
 					env[name] = value;
 					forwardNames.add(name);
 				}
+				env.RULVAR_TOOL = request.tool;
+				env.RULVAR_RUN_ID = request.ctx.runId;
+				env.RULVAR_IDEMPOTENCY_KEY = request.ctx.idempotencyKey;
+				const dockerArgs = [
+					"run",
+					"--rm",
+					"-i",
+					"--network",
+					network
+				];
+				dockerArgs.push("--memory", memory, "--cpus", cpus, "--pids-limit", String(pidsLimit));
+				if (readOnly) dockerArgs.push("--read-only");
+				for (const cap of capDrop) dockerArgs.push("--cap-drop", cap);
+				for (const name of forwardNames) dockerArgs.push("-e", name);
+				dockerArgs.push("-v", `${workdir}:${workMount}`, "-w", workMount);
+				dockerArgs.push(...options.extraDockerArgs ?? []);
+				dockerArgs.push(options.image, command, ...toolArgs);
+				let child;
+				try {
+					child = await runChildProcess({
+						command: docker,
+						args: dockerArgs,
+						env,
+						cwd: workdir,
+						stdinData: JSON.stringify({
+							tool: request.tool,
+							args: request.args,
+							idempotencyKey: request.ctx.idempotencyKey
+						}),
+						timeoutMs,
+						killGraceMs,
+						maxOutputBytes,
+						signal: request.ctx.signal
+					});
+				} catch (err) {
+					throw new ExecutorError("spawn", `container tool '${request.tool}' could not launch '${docker}': ${err instanceof Error ? err.message : String(err)}`);
+				}
+				exitCode = child.code;
+				signal = child.signal;
+				if (child.stopped && child.reason === "timeout") {
+					outcome = "timeout";
+					throw new ExecutorError("timeout", `container tool '${request.tool}' exceeded ${timeoutMs}ms and was killed`);
+				}
+				if (child.stopped && child.reason === "aborted") throw new ExecutorError("aborted", `container tool '${request.tool}' was cancelled`);
+				if (child.stopped && child.reason === "output-cap") throw new ExecutorError("output-cap", `container tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
+				if (child.code !== 0) {
+					const tail = child.stderr.trim().slice(-500);
+					throw new ExecutorError("exit", `container tool '${request.tool}' exited ${child.code ?? "null"}${tail === "" ? "" : `: ${tail}`}`);
+				}
+				const result = parseToolResult(child.stdout, request.tool);
+				outcome = "ok";
+				settled = result;
+			} catch (thrown) {
+				bodyThrew = true;
+				thrownBody = thrown;
 			}
-			const creds = options.credentials === void 0 ? {} : await options.credentials(request);
-			for (const [name, value] of Object.entries(creds)) {
-				env[name] = value;
-				forwardNames.add(name);
-			}
-			env.RULVAR_TOOL = request.tool;
-			env.RULVAR_RUN_ID = request.ctx.runId;
-			env.RULVAR_IDEMPOTENCY_KEY = request.ctx.idempotencyKey;
-			const dockerArgs = [
-				"run",
-				"--rm",
-				"-i",
-				"--network",
-				network
-			];
-			dockerArgs.push("--memory", memory, "--cpus", cpus, "--pids-limit", String(pidsLimit));
-			if (readOnly) dockerArgs.push("--read-only");
-			for (const cap of capDrop) dockerArgs.push("--cap-drop", cap);
-			for (const name of forwardNames) dockerArgs.push("-e", name);
-			dockerArgs.push("-v", `${workdir}:${workMount}`, "-w", workMount);
-			dockerArgs.push(...options.extraDockerArgs ?? []);
-			dockerArgs.push(options.image, command, ...toolArgs);
-			let child;
+			const durationMs = now() - startedAt;
+			let ledgerFailure;
 			try {
-				child = await runChildProcess({
-					command: docker,
-					args: dockerArgs,
-					env,
-					cwd: workdir,
-					stdinData: JSON.stringify({
-						tool: request.tool,
-						args: request.args,
-						idempotencyKey: request.ctx.idempotencyKey
-					}),
-					timeoutMs,
-					killGraceMs,
-					maxOutputBytes,
-					signal: request.ctx.signal
+				if (options.ledger !== void 0) await options.ledger.record({
+					idempotencyKey: request.ctx.idempotencyKey,
+					runId: request.ctx.runId,
+					spanId: request.ctx.spanId,
+					tool: request.tool,
+					argsHash,
+					executor: request.executor,
+					workdir,
+					startedAt,
+					attemptId,
+					durationMs,
+					outcome,
+					exitCode,
+					signal
 				});
-			} catch (err) {
-				throw new ExecutorError("spawn", `container tool '${request.tool}' could not launch '${docker}': ${err instanceof Error ? err.message : String(err)}`);
-			}
-			exitCode = child.code;
-			signal = child.signal;
-			if (child.stopped && child.reason === "timeout") {
-				outcome = "timeout";
-				throw new ExecutorError("timeout", `container tool '${request.tool}' exceeded ${timeoutMs}ms and was killed`);
-			}
-			if (child.stopped && child.reason === "aborted") throw new ExecutorError("aborted", `container tool '${request.tool}' was cancelled`);
-			if (child.stopped && child.reason === "output-cap") throw new ExecutorError("output-cap", `container tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
-			if (child.code !== 0) {
-				const tail = child.stderr.trim().slice(-500);
-				throw new ExecutorError("exit", `container tool '${request.tool}' exited ${child.code ?? "null"}${tail === "" ? "" : `: ${tail}`}`);
+			} catch (recordErr) {
+				ledgerFailure = new ExecutorError("ledger", `container tool '${request.tool}' outcome was not recorded: the ledger record write failed (${recordErr instanceof Error ? recordErr.message : String(recordErr)})` + (bodyThrew ? `; the dispatch itself had already failed (${thrownBody instanceof Error ? thrownBody.message : String(thrownBody)})` : ""));
 			}
-			const result = parseToolResult(child.stdout, request.tool);
-			outcome = "ok";
-			settled = result;
-		} catch (thrown) {
-			bodyThrew = true;
-			thrownBody = thrown;
-		}
-		const durationMs = now() - startedAt;
-		let ledgerFailure;
-		try {
-			if (options.ledger !== void 0) await options.ledger.record({
-				idempotencyKey: request.ctx.idempotencyKey,
-				runId: request.ctx.runId,
-				spanId: request.ctx.spanId,
-				tool: request.tool,
-				argsHash,
-				executor: request.executor,
-				workdir,
-				startedAt,
-				attemptId,
-				durationMs,
-				outcome,
-				exitCode,
-				signal
+			await rm(workdir, {
+				recursive: true,
+				force: true
 			});
-		} catch (recordErr) {
-			ledgerFailure = new ExecutorError("ledger", `container tool '${request.tool}' outcome was not recorded: the ledger record write failed (${recordErr instanceof Error ? recordErr.message : String(recordErr)})` + (bodyThrew ? `; the dispatch itself had already failed (${thrownBody instanceof Error ? thrownBody.message : String(thrownBody)})` : ""));
+			if (ledgerFailure !== void 0) throw ledgerFailure;
+			if (bodyThrew) throw thrownBody;
+			return settled;
 		}
-		await rm(workdir, {
-			recursive: true,
-			force: true
-		});
-		if (ledgerFailure !== void 0) throw ledgerFailure;
-		if (bodyThrew) throw thrownBody;
-		return settled;
-	} };
+	};
 }
 //#endregion
 //#region src/ledger.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/executor",
-  "version": "1.246.0",
+  "version": "1.247.0",
   "description": "Rulvar isolated tool executors: reference ToolExecutorProvider adapters that run tool work out of process (subprocess and container) so hostile or model-generated scripts cannot reach host capabilities.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.246.0"
+    "@rulvar/core": "1.247.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.246.0"
+    "@rulvar/testing": "1.247.0"
   },
   "repository": {
     "type": "git",