@execbox/quickjs 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,22 +1,625 @@
-import { t as runQuickJsSession } from "./runner-B4UG88h1.js";
-import { createTimeoutExecuteResult, createToolCallDispatcher, extractProviderManifests } from "@execbox/core";
+import { a as isJsonSerializable, c as getExecutionTimeoutMessage, i as isExecuteFailure, l as normalizeThrownMessage, n as resolveExecutorRuntimeOptions, o as createExecutionContext, r as ExecuteFailure, s as createTimeoutExecuteResult, t as runQuickJsSession } from "./runner-CteKTaPD.js";
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createResourcePool, getNodeTransportExecArgv, runHostTransportSession } from "@execbox/protocol";
+import { randomUUID } from "node:crypto";
+import { availableParallelism } from "node:os";
+import { Worker } from "node:worker_threads";
 
+//#region ../core/src/runner.ts
+function toTrustedExecuteError(error) {
+	if (isExecuteFailure(error)) return {
+		code: error.code,
+		message: error.message
+	};
+	return {
+		code: "tool_error",
+		message: normalizeThrownMessage(error)
+	};
+}
+/**
+* Converts resolved providers into manifest metadata that reveals only namespace details.
+*/
+function extractProviderManifests(providers) {
+	return providers.map((provider) => ({
+		name: provider.name,
+		tools: Object.fromEntries(Object.entries(provider.tools).map(([safeToolName, descriptor]) => [safeToolName, {
+			description: descriptor.description,
+			originalName: descriptor.originalName,
+			safeName: descriptor.safeName
+		}])),
+		types: provider.types
+	}));
+}
+/**
+* Creates a host-side dispatcher for runner-emitted tool calls.
+*/
+function createToolCallDispatcher(providers, signal) {
+	const providerMap = new Map(providers.map((provider) => [provider.name, provider]));
+	return async (call) => {
+		const provider = providerMap.get(call.providerName);
+		const descriptor = provider?.tools[call.safeToolName];
+		if (!provider || !descriptor) return {
+			error: {
+				code: "internal_error",
+				message: `Unknown tool ${call.providerName}.${call.safeToolName}`
+			},
+			ok: false
+		};
+		try {
+			if (signal.aborted) return {
+				error: {
+					code: "timeout",
+					message: getExecutionTimeoutMessage()
+				},
+				ok: false
+			};
+			const result = await descriptor.execute(call.input, createExecutionContext(signal, provider.name, descriptor.safeName, descriptor.originalName));
+			if (result !== void 0 && !isJsonSerializable(result)) throw new ExecuteFailure("serialization_error", "Host value is not JSON-serializable");
+			return {
+				ok: true,
+				result
+			};
+		} catch (error) {
+			return {
+				error: toTrustedExecuteError(error),
+				ok: false
+			};
+		}
+	};
+}
+
+//#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 runHostTransportSession({
+		cancelGraceMs: options.cancelGraceMs,
+		code: options.code,
+		executionId: randomUUID(),
+		onSettled: options.onSettled,
+		providers: options.providers,
+		runtimeOptions: 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 = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
+	return fileURLToPath(new URL(`../processEntry${extension}`, import.meta.url));
+}
+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 fork(resolveProcessEntryPath(), [], {
+		execArgv: getNodeTransportExecArgv(import.meta.url),
+		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 = 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 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 = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
+	return new URL(`../workerEntry${extension}`, import.meta.url);
+}
+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 Worker(resolveWorkerEntryUrl(), {
+		execArgv: getNodeTransportExecArgv(import.meta.url),
+		resourceLimits: options.workerResourceLimits
+	});
+	return {
+		transport: createWorkerTransport(worker),
+		worker
+	};
+}
+function getDefaultPoolMaxSize() {
+	try {
+		return Math.max(1, Math.min(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 = 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 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 Worker(resolveWorkerEntryUrl(), {
+			execArgv: getNodeTransportExecArgv(import.meta.url),
+			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 createTimeoutExecuteResult();
 		const abortController = new AbortController();
 		const onToolCall = createToolCallDispatcher(providers, abortController.signal);