@execbox/quickjs 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @execbox/quickjs
 
-QuickJS executor backend for `@execbox/core`.
+QuickJS executor backend for `@execbox/core`, supporting inline, worker-hosted, and process-hosted execution.
 
 [![npm version](https://img.shields.io/npm/v/%40execbox%2Fquickjs?style=flat-square)](https://www.npmjs.com/package/@execbox/quickjs)
 [![License](https://img.shields.io/github/license/aallam/execbox?style=flat-square)](https://github.com/aallam/execbox/blob/main/LICENSE)
@@ -12,6 +12,7 @@ Docs: https://execbox.aallam.com
 - you want the easiest execbox backend to install
 - you do not want a native addon in CI or local development
 - you want fresh runtimes, captured `console.*` output, and JSON-only tool boundaries
+- you want to move from inline execution to worker or child-process hosts without changing packages
 
 ## Security Notes
 
@@ -19,7 +20,7 @@ Docs: https://execbox.aallam.com
 - Tool calls cross a JSON-only bridge, and executor timeouts propagate abort signals to in-flight provider work.
 - In the default deployment model, provider definitions are controlled by the host application, while hostile users control guest code and tool inputs.
 - This package is designed for host-controlled deployments and does not by itself create a hard isolation boundary for hostile code.
-- If you need a stronger boundary, move execution into a separate process, container, or remote runtime.
+- If you need a stronger boundary, use `host: "process"`, move execution behind `@execbox/remote`, or place the runtime behind a container or VM.
 
 ## Architecture Docs
 
@@ -30,6 +31,7 @@ Docs: https://execbox.aallam.com
 ## Examples
 
 - [Basic provider execution](https://github.com/aallam/execbox/blob/main/examples/execbox-basic.ts)
+- [Process-hosted QuickJS execution](https://github.com/aallam/execbox/blob/main/examples/execbox-process.ts)
 - [Worker-backed QuickJS execution](https://github.com/aallam/execbox/blob/main/examples/execbox-worker.ts)
 - [MCP provider wrapping](https://github.com/aallam/execbox/blob/main/examples/execbox-mcp-provider.ts)
 - [MCP server wrapper](https://github.com/aallam/execbox/blob/main/examples/execbox-mcp-server.ts)
@@ -42,7 +44,7 @@ npm install @execbox/core @execbox/quickjs
 ```
 
 Advanced consumers can also import the reusable QuickJS runner from `@execbox/quickjs/runner`.
-Transport-backed executors such as `@execbox/worker` and `@execbox/process` also reuse the shared QuickJS protocol endpoint from `@execbox/quickjs/runner/protocol-endpoint`.
+Hosted worker/process execution and `@execbox/remote` also reuse the shared QuickJS protocol endpoint from `@execbox/quickjs/runner/protocol-endpoint`.
 
 ## Usage
 
@@ -66,4 +68,16 @@ const result = await executor.execute("await codemode.echo({ ok: true })", [
 
 Each execution runs in a fresh QuickJS runtime with timeout handling, captured logs, and JSON-only result and tool boundaries.
 
-`QuickJsExecutor` intentionally stays ephemeral. Every `execute()` call creates a fresh QuickJS runtime/context, and the package does not expose a pooling API.
+`QuickJsExecutor` defaults to inline execution. Set `host: "worker"` when you want pooled worker-shell reuse, or `host: "process"` when you want pooled child-process reuse with a stronger lifecycle split.
+
+```ts
+const executor = new QuickJsExecutor({
+  host: "worker",
+  pool: {
+    maxSize: 4,
+    prewarm: true,
+  },
+});
+
+await executor.prewarm();
+```

package/dist/index.cjs

@@ -1,4 +1,10 @@
-const require_runner = require('./runner-BqkDnP0t.cjs');
+const require_runner = require('./runner-DRt0kpEk.cjs');
+let node_child_process = require("node:child_process");
+let node_url = require("node:url");
+let __execbox_protocol = require("@execbox/protocol");
+let node_crypto = require("node:crypto");
+let node_os = require("node:os");
+let node_worker_threads = require("node:worker_threads");
 
 //#region ../core/src/runner.ts
 function toTrustedExecuteError(error) {
@@ -63,23 +69,557 @@ function createToolCallDispatcher(providers, signal) {
 	};
 }
 
+//#endregion
+//#region src/hosted/shared.ts
+/**
+* Default grace period before a hosted shell is forcefully terminated.
+*/
+const DEFAULT_CANCEL_GRACE_MS = 25;
+/**
+* Default pooling limits shared by the hosted QuickJS executors.
+*/
+const DEFAULT_POOL_OPTIONS = {
+	idleTimeoutMs: 3e4,
+	maxSize: 1,
+	minSize: 0,
+	prewarm: false
+};
+/**
+* Minimal code used to warm a hosted shell without touching user providers.
+*/
+const DEFAULT_PREWARM_CODE = "undefined";
+/**
+* Wraps a transport so warmup and pooled execution can borrow it without
+* taking ownership of its lifecycle.
+*/
+function createBorrowedTransport(transport) {
+	return {
+		dispose() {},
+		onClose: transport.onClose,
+		onError: transport.onError,
+		onMessage: transport.onMessage,
+		send: transport.send,
+		terminate: transport.terminate
+	};
+}
+/**
+* Resolves how many pooled shells should be prewarmed from the pool settings.
+*/
+function getPrewarmCount(pool) {
+	if (!pool?.prewarm) return 0;
+	if (typeof pool.prewarm === "number") return Math.max(0, Math.min(pool.prewarm, pool.maxSize));
+	return Math.max(1, Math.min(pool.minSize ?? 1, pool.maxSize));
+}
+/**
+* Caps an explicit warmup request to the configured pool boundaries.
+*/
+function getWarmupTarget(count, poolOptions) {
+	return Math.max(0, Math.min(count ?? poolOptions.minSize ?? 0, poolOptions.maxSize));
+}
+/**
+* Returns whether a hosted execution result is safe to return to a pool.
+*/
+function isReusableResult(result) {
+	return result.ok || !["internal_error", "timeout"].includes(result.error.code);
+}
+/**
+* Normalizes a failed warmup result into an actionable host-side error.
+*/
+function toWarmupError(label, result) {
+	if (result.ok) return /* @__PURE__ */ new Error(`Failed to prewarm pooled ${label}`);
+	return /* @__PURE__ */ new Error(`Failed to prewarm pooled ${label}: ${result.error.message}`);
+}
+/**
+* Runs one transport-backed execution session with resolved runtime limits and
+* a fresh execution identifier.
+*/
+async function runHostedTransportSession(options) {
+	return await (0, __execbox_protocol.runHostTransportSession)({
+		cancelGraceMs: options.cancelGraceMs,
+		code: options.code,
+		executionId: (0, node_crypto.randomUUID)(),
+		onSettled: options.onSettled,
+		providers: options.providers,
+		runtimeOptions: require_runner.resolveExecutorRuntimeOptions(options.executorOptions, options.requestOptions),
+		signal: options.requestOptions?.signal,
+		transport: options.transport
+	});
+}
+/**
+* Exercises a set of leased shells with a warmup run and releases each lease
+* according to the warmup result.
+*/
+async function warmHostedPool(options) {
+	const rejected = (await Promise.allSettled(options.shells.map(async (shell) => {
+		let reusable = false;
+		try {
+			const result = await options.runSession(createBorrowedTransport(options.getTransport(shell)), DEFAULT_PREWARM_CODE, []);
+			reusable = result.ok;
+			if (!result.ok) throw toWarmupError(options.label, result);
+		} finally {
+			await options.onRelease(shell, reusable);
+		}
+	}))).find((result) => result.status === "rejected");
+	if (rejected?.status === "rejected") throw rejected.reason;
+}
+
+//#endregion
+//#region src/hosted/processHostedExecutor.ts
+function resolveProcessEntryPath() {
+	const extension = require("url").pathToFileURL(__filename).href.endsWith(".ts") ? ".ts" : ".js";
+	return (0, node_url.fileURLToPath)(new URL(`../processEntry${extension}`, require("url").pathToFileURL(__filename).href));
+}
+function createUnexpectedExitMessage(code, signal) {
+	if (code !== null) return `Child process exited unexpectedly with code ${code}`;
+	if (signal) return `Child process exited unexpectedly with signal ${signal}`;
+	return "Child process exited unexpectedly";
+}
+function createChildProcess() {
+	return (0, node_child_process.fork)(resolveProcessEntryPath(), [], {
+		execArgv: (0, __execbox_protocol.getNodeTransportExecArgv)(require("url").pathToFileURL(__filename).href),
+		stdio: [
+			"ignore",
+			"ignore",
+			"ignore",
+			"ipc"
+		]
+	});
+}
+function createProcessTransport(child) {
+	let terminated = false;
+	let closeReason;
+	const closeHandlers = /* @__PURE__ */ new Set();
+	const errorHandlers = /* @__PURE__ */ new Set();
+	const messageHandlers = /* @__PURE__ */ new Set();
+	const terminateChild = () => {
+		if (terminated) return;
+		terminated = true;
+		child.kill("SIGKILL");
+	};
+	const notifyClose = (reason) => {
+		if (closeReason) return;
+		closeReason = reason;
+		for (const handler of closeHandlers) handler(reason);
+	};
+	const onDisconnect = () => {
+		notifyClose({ message: "Child process disconnected unexpectedly" });
+	};
+	const onExit = (code, signal) => {
+		notifyClose({
+			code,
+			message: createUnexpectedExitMessage(code, signal),
+			signal
+		});
+	};
+	const onError = (error) => {
+		for (const handler of errorHandlers) handler(error);
+	};
+	const onMessage = (message) => {
+		for (const handler of messageHandlers) handler(message);
+	};
+	child.on("disconnect", onDisconnect);
+	child.on("exit", onExit);
+	child.on("error", onError);
+	child.on("message", onMessage);
+	return {
+		dispose: () => {
+			child.off("disconnect", onDisconnect);
+			child.off("exit", onExit);
+			child.off("error", onError);
+			child.off("message", onMessage);
+			terminateChild();
+		},
+		onClose: (handler) => {
+			closeHandlers.add(handler);
+			if (closeReason) queueMicrotask(() => {
+				if (closeHandlers.has(handler)) handler(closeReason);
+			});
+			return () => {
+				closeHandlers.delete(handler);
+			};
+		},
+		onError: (handler) => {
+			errorHandlers.add(handler);
+			return () => errorHandlers.delete(handler);
+		},
+		onMessage: (handler) => {
+			messageHandlers.add(handler);
+			return () => messageHandlers.delete(handler);
+		},
+		send: (message) => new Promise((resolve, reject) => {
+			if (!child.connected || typeof child.send !== "function") {
+				reject(/* @__PURE__ */ new Error("Child process disconnected unexpectedly"));
+				return;
+			}
+			child.send(message, (error) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+				resolve();
+			});
+		}),
+		terminate: () => {
+			terminateChild();
+		}
+	};
+}
+function createProcessShell() {
+	const child = createChildProcess();
+	return {
+		child,
+		transport: createProcessTransport(child)
+	};
+}
+function resolvePoolOptions$1(options) {
+	if (options.mode === "ephemeral") return;
+	return {
+		...DEFAULT_POOL_OPTIONS,
+		...options.pool
+	};
+}
+/**
+* Child-process executor that runs guest code inside a dedicated QuickJS runtime per call.
+*/
+var ProcessHostedQuickJsExecutor = class {
+	cancelGraceMs;
+	options;
+	pool;
+	poolOptions;
+	warmup;
+	/**
+	* Creates a hosted QuickJS executor that launches child-process shells on demand.
+	*/
+	constructor(options) {
+		this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
+		this.options = options;
+		const poolOptions = resolvePoolOptions$1(options);
+		this.poolOptions = poolOptions;
+		if (poolOptions) {
+			this.pool = (0, __execbox_protocol.createResourcePool)({
+				create: async () => createProcessShell(),
+				destroy: async (shell) => {
+					await shell.transport.dispose();
+				},
+				idleTimeoutMs: poolOptions.idleTimeoutMs,
+				maxSize: poolOptions.maxSize,
+				minSize: poolOptions.minSize
+			});
+			const prewarmCount = getPrewarmCount(poolOptions);
+			if (prewarmCount > 0) this.warmup = this.warmPool(prewarmCount);
+		}
+	}
+	/**
+	* Disposes any pooled child-process shells owned by this executor.
+	*/
+	async dispose() {
+		await this.pool?.dispose();
+	}
+	/**
+	* Prewarms pooled child-process shells up to the requested count.
+	*/
+	async prewarm(count) {
+		if (!this.pool || !this.poolOptions) return;
+		const target = getWarmupTarget(count, this.poolOptions);
+		if (target <= 0) return;
+		await this.warmPool(target);
+	}
+	async runTransportSession(transport, code, providers, options = {}, onSettled) {
+		return await runHostedTransportSession({
+			cancelGraceMs: this.cancelGraceMs,
+			code,
+			executorOptions: this.options,
+			onSettled,
+			providers,
+			requestOptions: options,
+			transport
+		});
+	}
+	async warmPool(count) {
+		if (!this.pool) return;
+		await this.pool.prewarm(count);
+		const leases = [];
+		try {
+			for (let index = 0; index < count; index += 1) leases.push(await this.pool.acquire());
+		} catch (error) {
+			await Promise.allSettled(leases.map(async (lease) => await lease.release(false)));
+			throw error;
+		}
+		await warmHostedPool({
+			count,
+			getTransport: (lease) => lease.value.transport,
+			label: "child process",
+			onRelease: async (lease, reusable) => await lease.release(reusable),
+			runSession: async (transport, code, providers) => await this.runTransportSession(transport, code, providers),
+			shells: leases
+		});
+	}
+	/**
+	* Executes guest code in a child-process-hosted QuickJS shell.
+	*/
+	async execute(code, providers, options = {}) {
+		if (options.signal?.aborted) return require_runner.createTimeoutExecuteResult();
+		await this.warmup;
+		if (this.pool) {
+			const lease = await this.pool.acquire();
+			return await this.runTransportSession(createBorrowedTransport(lease.value.transport), code, providers, options, async (result) => {
+				await lease.release(isReusableResult(result));
+			});
+		}
+		let child;
+		try {
+			child = createChildProcess();
+		} catch (error) {
+			return {
+				durationMs: 0,
+				error: {
+					code: "internal_error",
+					message: error instanceof Error ? error.message : String(error)
+				},
+				logs: [],
+				ok: false
+			};
+		}
+		return await this.runTransportSession(createProcessTransport(child), code, providers, options);
+	}
+};
+
+//#endregion
+//#region src/hosted/workerHostedExecutor.ts
+const DEFAULT_POOLED_WORKER_MAX_SIZE = 4;
+function resolveWorkerEntryUrl() {
+	const extension = require("url").pathToFileURL(__filename).href.endsWith(".ts") ? ".ts" : ".js";
+	return new URL(`../workerEntry${extension}`, require("url").pathToFileURL(__filename).href);
+}
+function createWorkerTransport(worker) {
+	let terminated = false;
+	let closeReason;
+	const closeHandlers = /* @__PURE__ */ new Set();
+	const errorHandlers = /* @__PURE__ */ new Set();
+	const messageHandlers = /* @__PURE__ */ new Set();
+	const terminateWorker = async () => {
+		if (terminated) return;
+		terminated = true;
+		await worker.terminate().catch(() => {});
+	};
+	const notifyClose = (reason) => {
+		if (closeReason) return;
+		closeReason = reason;
+		for (const handler of closeHandlers) handler(reason);
+	};
+	const onExit = (code) => {
+		notifyClose({
+			code,
+			message: `Worker exited unexpectedly with code ${code}`
+		});
+	};
+	const onError = (error) => {
+		for (const handler of errorHandlers) handler(error);
+	};
+	const onMessage = (message) => {
+		for (const handler of messageHandlers) handler(message);
+	};
+	worker.on("exit", onExit);
+	worker.on("error", onError);
+	worker.on("message", onMessage);
+	return {
+		dispose: async () => {
+			worker.off("exit", onExit);
+			worker.off("error", onError);
+			worker.off("message", onMessage);
+			await terminateWorker();
+		},
+		onClose: (handler) => {
+			closeHandlers.add(handler);
+			if (closeReason) queueMicrotask(() => {
+				if (closeHandlers.has(handler)) handler(closeReason);
+			});
+			return () => closeHandlers.delete(handler);
+		},
+		onError: (handler) => {
+			errorHandlers.add(handler);
+			return () => errorHandlers.delete(handler);
+		},
+		onMessage: (handler) => {
+			messageHandlers.add(handler);
+			return () => messageHandlers.delete(handler);
+		},
+		send: (message) => {
+			worker.postMessage(message);
+		},
+		terminate: async () => {
+			await terminateWorker();
+		}
+	};
+}
+function createWorkerShell(options) {
+	const worker = new node_worker_threads.Worker(resolveWorkerEntryUrl(), {
+		execArgv: (0, __execbox_protocol.getNodeTransportExecArgv)(require("url").pathToFileURL(__filename).href),
+		resourceLimits: options.workerResourceLimits
+	});
+	return {
+		transport: createWorkerTransport(worker),
+		worker
+	};
+}
+function getDefaultPoolMaxSize() {
+	try {
+		return Math.max(1, Math.min((0, node_os.availableParallelism)(), DEFAULT_POOLED_WORKER_MAX_SIZE));
+	} catch {
+		return 1;
+	}
+}
+function resolvePoolOptions(options) {
+	if (options.mode === "ephemeral") return;
+	return {
+		...DEFAULT_POOL_OPTIONS,
+		maxSize: getDefaultPoolMaxSize(),
+		...options.pool
+	};
+}
+/**
+* Worker-thread executor that runs guest code inside a dedicated QuickJS runtime per call.
+*/
+var WorkerHostedQuickJsExecutor = class {
+	cancelGraceMs;
+	options;
+	pool;
+	poolOptions;
+	warmup;
+	/**
+	* Creates a hosted QuickJS executor that launches worker-thread shells on demand.
+	*/
+	constructor(options) {
+		this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
+		this.options = options;
+		const poolOptions = resolvePoolOptions(options);
+		this.poolOptions = poolOptions;
+		if (poolOptions) {
+			this.pool = (0, __execbox_protocol.createResourcePool)({
+				create: async () => createWorkerShell(options),
+				destroy: async (shell) => {
+					await shell.transport.dispose();
+				},
+				idleTimeoutMs: poolOptions.idleTimeoutMs,
+				maxSize: poolOptions.maxSize,
+				minSize: poolOptions.minSize
+			});
+			const prewarmCount = getPrewarmCount(poolOptions);
+			if (prewarmCount > 0) this.warmup = this.warmPool(prewarmCount);
+		}
+	}
+	/**
+	* Disposes any pooled worker-thread shells owned by this executor.
+	*/
+	async dispose() {
+		await this.pool?.dispose();
+	}
+	/**
+	* Prewarms pooled worker-thread shells up to the requested count.
+	*/
+	async prewarm(count) {
+		if (!this.pool || !this.poolOptions) return;
+		const target = getWarmupTarget(count, this.poolOptions);
+		if (target <= 0) return;
+		await this.warmPool(target);
+	}
+	async runTransportSession(transport, code, providers, options = {}, onSettled) {
+		return await runHostedTransportSession({
+			cancelGraceMs: this.cancelGraceMs,
+			code,
+			executorOptions: this.options,
+			onSettled,
+			providers,
+			requestOptions: options,
+			transport
+		});
+	}
+	async warmPool(count) {
+		if (!this.pool) return;
+		await this.pool.prewarm(count);
+		const leases = [];
+		try {
+			for (let index = 0; index < count; index += 1) leases.push(await this.pool.acquire());
+		} catch (error) {
+			await Promise.allSettled(leases.map(async (lease) => await lease.release(false)));
+			throw error;
+		}
+		await warmHostedPool({
+			count,
+			getTransport: (lease) => lease.value.transport,
+			label: "worker shell",
+			onRelease: async (lease, reusable) => await lease.release(reusable),
+			runSession: async (transport, code, providers) => await this.runTransportSession(transport, code, providers),
+			shells: leases
+		});
+	}
+	/**
+	* Executes guest code in a worker-thread-hosted QuickJS shell.
+	*/
+	async execute(code, providers, options = {}) {
+		if (options.signal?.aborted) return require_runner.createTimeoutExecuteResult();
+		await this.warmup;
+		if (this.pool) {
+			const lease = await this.pool.acquire();
+			return await this.runTransportSession(createBorrowedTransport(lease.value.transport), code, providers, options, async (result) => {
+				await lease.release(isReusableResult(result));
+			});
+		}
+		const worker = new node_worker_threads.Worker(resolveWorkerEntryUrl(), {
+			execArgv: (0, __execbox_protocol.getNodeTransportExecArgv)(require("url").pathToFileURL(__filename).href),
+			resourceLimits: this.options.workerResourceLimits
+		});
+		return await this.runTransportSession(createWorkerTransport(worker), code, providers, options);
+	}
+};
+
 //#endregion
 //#region src/quickjsExecutor.ts
+function isWorkerOptions(options) {
+	return options.host === "worker";
+}
+function isProcessOptions(options) {
+	return options.host === "process";
+}
 /**
-* QuickJS-backed executor for ephemeral sandboxed JavaScript runs.
+* QuickJS-backed executor for inline, worker-backed, or process-backed JavaScript runs.
 */
 var QuickJsExecutor = class {
+	hostedExecutor;
 	options;
 	/**
-	* Creates a QuickJS executor with ephemeral runtime limits and host bridging configuration.
+	* Creates a QuickJS executor with inline QuickJS by default, or a hosted
+	* worker/process shell when `host` is explicitly set.
 	*/
 	constructor(options = {}) {
+		if (isWorkerOptions(options)) {
+			this.hostedExecutor = new WorkerHostedQuickJsExecutor(options);
+			return;
+		}
+		if (isProcessOptions(options)) {
+			this.hostedExecutor = new ProcessHostedQuickJsExecutor(options);
+			return;
+		}
 		this.options = options;
 	}
 	/**
+	* Disposes any pooled hosted shells owned by this executor.
+	*/
+	async dispose() {
+		await this.hostedExecutor?.dispose?.();
+	}
+	/**
+	* Prewarms pooled hosted shells when the executor is running in worker or
+	* process mode. Inline mode treats this as a no-op.
+	*/
+	async prewarm(count) {
+		await this.hostedExecutor?.prewarm?.(count);
+	}
+	/**
 	* Executes JavaScript against the provided tool namespaces in a fresh QuickJS runtime.
 	*/
 	async execute(code, providers, options = {}) {
+		if (this.hostedExecutor) return await this.hostedExecutor.execute(code, providers, options);
 		if (options.signal?.aborted) return require_runner.createTimeoutExecuteResult();
 		const abortController = new AbortController();
 		const onToolCall = createToolCallDispatcher(providers, abortController.signal);