@execbox/quickjs 0.4.0 → 0.6.0

package/README.md

@@ -1,41 +1,16 @@
 # @execbox/quickjs
 
-QuickJS executor backend for `@execbox/core`, supporting inline, worker-hosted, and process-hosted execution.
+Default execbox executor for most deployments. It runs guest JavaScript in QuickJS and lets you keep the same API as you move between inline and worker-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)
+[![Docs](https://img.shields.io/badge/docs-site-0ea5e9?style=flat-square)](https://execbox.aallam.com)
 
-Docs: https://execbox.aallam.com
+## Use `@execbox/quickjs` When
 
-## Choose QuickJS When
-
-- 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
-
-- Each execution gets a fresh QuickJS runtime with no ambient Node globals injected by execbox.
-- 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, use `host: "process"`, move execution behind `@execbox/remote`, or place the runtime behind a container or VM.
-
-## Architecture Docs
-
-- [Execbox architecture overview](https://github.com/aallam/execbox/blob/main/docs/architecture/README.md)
-- [Execbox executors](https://github.com/aallam/execbox/blob/main/docs/architecture/execbox-executors.md)
-- [Execbox MCP adapters and protocol](https://github.com/aallam/execbox/blob/main/docs/architecture/execbox-mcp-and-protocol.md)
-
-## 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)
-- [Full examples index](https://github.com/aallam/execbox/tree/main/examples)
+- you want the default execbox path with the easiest setup
+- you do not want a native addon in local development or CI
+- you want one package that can stay inline or move off-thread later
 
 ## Install
 
@@ -43,16 +18,14 @@ Docs: https://execbox.aallam.com
 npm install @execbox/core @execbox/quickjs
 ```
 
-Advanced consumers can also import the reusable QuickJS runner from `@execbox/quickjs/runner`.
-Hosted worker/process execution and `@execbox/remote` also reuse the shared QuickJS protocol endpoint from `@execbox/quickjs/runner/protocol-endpoint`.
-
-## Usage
+## Smallest Working Usage
 
 ```ts
 import { resolveProvider } from "@execbox/core";
 import { QuickJsExecutor } from "@execbox/quickjs";
 
 const provider = resolveProvider({
+  name: "tools",
   tools: {
     echo: {
       execute: async (input) => input,
@@ -61,14 +34,21 @@ const provider = resolveProvider({
 });
 
 const executor = new QuickJsExecutor();
-const result = await executor.execute("await codemode.echo({ ok: true })", [
+const result = await executor.execute(`await tools.echo({ ok: true })`, [
   provider,
 ]);
+
+console.log(result);
 ```
 
-Each execution runs in a fresh QuickJS runtime with timeout handling, captured logs, and JSON-only result and tool boundaries.
+## Host Modes
+
+`QuickJsExecutor` keeps the same execution API while changing where the runtime lives:
 
-`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.
+| Mode             | Use it when                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| Inline (default) | You want the lowest-friction development path.                  |
+| `host: "worker"` | You want QuickJS off the main thread with pooled worker shells. |
 
 ```ts
 const executor = new QuickJsExecutor({
@@ -81,3 +61,23 @@ const executor = new QuickJsExecutor({
 
 await executor.prewarm();
 ```
+
+## Advanced Imports
+
+- `@execbox/quickjs/runner` exports the reusable QuickJS runner
+- `@execbox/quickjs/runner/protocol-endpoint` exports the low-level QuickJS protocol loop used by worker-hosted integrations
+- `@execbox/quickjs/remote-endpoint` adapts the QuickJS protocol loop to `@execbox/remote` runner ports
+
+## Operational Notes
+
+- Each execution gets a fresh QuickJS runtime with JSON-only tool and result boundaries.
+- This package is the default deployment path, not a hard security boundary for hostile or multi-tenant code.
+- If you need a stronger deployment boundary, move execution behind `@execbox/remote` and a process, container, VM, or network boundary your application owns.
+
+## Read Next
+
+- [Getting Started](https://execbox.aallam.com/getting-started)
+- [Examples](https://execbox.aallam.com/examples)
+- [Security & Boundaries](https://execbox.aallam.com/security)
+- [Executors](https://execbox.aallam.com/architecture/execbox-executors)
+- [MCP And Protocol](https://execbox.aallam.com/architecture/execbox-mcp-and-protocol)

package/dist/index.cjs

@@ -1,82 +1,17 @@
-const require_runner = require('./runner-DRt0kpEk.cjs');
-let node_child_process = require("node:child_process");
-let node_url = require("node:url");
-let __execbox_core_protocol = require("@execbox/core/protocol");
-let node_crypto = require("node:crypto");
+const require_runner = require('./runner-DRLfwiqY.cjs');
+let __execbox_core_runtime = require("@execbox/core/runtime");
 let node_os = require("node:os");
 let node_worker_threads = require("node:worker_threads");
+let __execbox_core_protocol = require("@execbox/core/protocol");
+let node_crypto = require("node:crypto");
 
-//#region ../core/src/runner.ts
-function toTrustedExecuteError(error) {
-	if (require_runner.isExecuteFailure(error)) return {
-		code: error.code,
-		message: error.message
-	};
-	return {
-		code: "tool_error",
-		message: require_runner.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: require_runner.getExecutionTimeoutMessage()
-				},
-				ok: false
-			};
-			const result = await descriptor.execute(call.input, require_runner.createExecutionContext(signal, provider.name, descriptor.safeName, descriptor.originalName));
-			if (result !== void 0 && !require_runner.isJsonSerializable(result)) throw new require_runner.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.
+* Default grace period before a worker-hosted shell is forcefully terminated.
 */
 const DEFAULT_CANCEL_GRACE_MS = 25;
 /**
-* Default pooling limits shared by the hosted QuickJS executors.
+* Default pooling limits shared by worker-hosted QuickJS executors.
 */
 const DEFAULT_POOL_OPTIONS = {
 	idleTimeoutMs: 3e4,
@@ -85,7 +20,7 @@ const DEFAULT_POOL_OPTIONS = {
 	prewarm: false
 };
 /**
-* Minimal code used to warm a hosted shell without touching user providers.
+* Minimal code used to warm a worker shell without touching user providers.
 */
 const DEFAULT_PREWARM_CODE = "undefined";
 /**
@@ -140,7 +75,7 @@ async function runHostedTransportSession(options) {
 		executionId: (0, node_crypto.randomUUID)(),
 		onSettled: options.onSettled,
 		providers: options.providers,
-		runtimeOptions: require_runner.resolveExecutorRuntimeOptions(options.executorOptions, options.requestOptions),
+		runtimeOptions: (0, __execbox_core_runtime.resolveExecutorRuntimeOptions)(options.executorOptions, options.requestOptions),
 		signal: options.requestOptions?.signal,
 		transport: options.transport
 	});
@@ -163,227 +98,6 @@ async function warmHostedPool(options) {
 	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_core_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_core_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;
@@ -487,7 +201,7 @@ var WorkerHostedQuickJsExecutor = class {
 	poolOptions;
 	warmup;
 	/**
-	* Creates a hosted QuickJS executor that launches worker-thread shells on demand.
+	* Creates a QuickJS executor that launches worker-thread shells on demand.
 	*/
 	constructor(options) {
 		this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
@@ -557,7 +271,7 @@ var WorkerHostedQuickJsExecutor = class {
 	* Executes guest code in a worker-thread-hosted QuickJS shell.
 	*/
 	async execute(code, providers, options = {}) {
-		if (options.signal?.aborted) return require_runner.createTimeoutExecuteResult();
+		if (options.signal?.aborted) return (0, __execbox_core_runtime.createTimeoutExecuteResult)();
 		await this.warmup;
 		if (this.pool) {
 			const lease = await this.pool.acquire();
@@ -578,28 +292,28 @@ var WorkerHostedQuickJsExecutor = class {
 function isWorkerOptions(options) {
 	return options.host === "worker";
 }
-function isProcessOptions(options) {
-	return options.host === "process";
+function getUnsupportedHost(options) {
+	const host = options.host;
+	if (host === void 0 || host === "inline" || host === "worker") return;
+	return String(host);
 }
 /**
-* QuickJS-backed executor for inline, worker-backed, or process-backed JavaScript runs.
+* QuickJS-backed executor for inline or worker-backed JavaScript runs.
 */
 var QuickJsExecutor = class {
 	hostedExecutor;
 	options;
 	/**
 	* Creates a QuickJS executor with inline QuickJS by default, or a hosted
-	* worker/process shell when `host` is explicitly set.
+	* worker shell when `host` is explicitly set.
 	*/
 	constructor(options = {}) {
+		const unsupportedHost = getUnsupportedHost(options);
+		if (unsupportedHost !== void 0) throw new Error(`QuickJsExecutor host "${unsupportedHost}" is no longer supported. Use host "worker" for local hosted execution, or @execbox/remote for process, container, or VM boundaries.`);
 		if (isWorkerOptions(options)) {
 			this.hostedExecutor = new WorkerHostedQuickJsExecutor(options);
 			return;
 		}
-		if (isProcessOptions(options)) {
-			this.hostedExecutor = new ProcessHostedQuickJsExecutor(options);
-			return;
-		}
 		this.options = options;
 	}
 	/**
@@ -609,8 +323,8 @@ var QuickJsExecutor = class {
 		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.
+	* Prewarms pooled hosted shells when the executor is running in worker mode.
+	* Inline mode treats this as a no-op.
 	*/
 	async prewarm(count) {
 		await this.hostedExecutor?.prewarm?.(count);
@@ -620,9 +334,9 @@ var QuickJsExecutor = class {
 	*/
 	async execute(code, providers, options = {}) {
 		if (this.hostedExecutor) return await this.hostedExecutor.execute(code, providers, options);
-		if (options.signal?.aborted) return require_runner.createTimeoutExecuteResult();
+		if (options.signal?.aborted) return (0, __execbox_core_runtime.createTimeoutExecuteResult)();
 		const abortController = new AbortController();
-		const onToolCall = createToolCallDispatcher(providers, abortController.signal);
+		const onToolCall = (0, __execbox_core_runtime.createToolCallDispatcher)(providers, abortController.signal);
 		const onAbort = () => {
 			abortController.abort();
 		};
@@ -632,7 +346,7 @@ var QuickJsExecutor = class {
 				abortController,
 				code,
 				onToolCall,
-				providers: extractProviderManifests(providers)
+				providers: (0, __execbox_core_runtime.extractProviderManifests)(providers)
 			}, {
 				...this.options,
 				...options