@execbox/quickjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mouaad Aallam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @execbox/quickjs
+
+QuickJS executor backend for `@execbox/core`.
+
+[![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)
+
+## 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
+
+## 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 not presented as a hard security boundary for hostile code. It is best-effort in-process isolation.
+- If you need a stronger boundary, run execbox behind a separate process or container.
+
+## Architecture Docs
+
+- [Execbox architecture overview](https://github.com/aallam/execbox/blob/main/docs/execbox/architecture/README.md)
+- [Execbox executors](https://github.com/aallam/execbox/blob/main/docs/execbox/architecture/execbox-executors.md)
+- [Execbox MCP adapters and protocol](https://github.com/aallam/execbox/blob/main/docs/execbox/architecture/execbox-mcp-and-protocol.md)
+
+## Examples
+
+- [Basic provider execution](https://github.com/aallam/execbox/blob/main/examples/execbox-basic.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)
+
+## Install
+
+```bash
+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`.
+
+## Usage
+
+```ts
+import { resolveProvider } from "@execbox/core";
+import { QuickJsExecutor } from "@execbox/quickjs";
+
+const provider = resolveProvider({
+  tools: {
+    echo: {
+      execute: async (input) => input,
+    },
+  },
+});
+
+const executor = new QuickJsExecutor();
+const result = await executor.execute("await codemode.echo({ ok: true })", [
+  provider,
+]);
+```
+
+Each execution runs in a fresh QuickJS runtime with timeout handling, captured logs, and JSON-only result and tool boundaries.

package/dist/index.cjs

@@ -0,0 +1,46 @@
+const require_runner = require('./runner-CYXIVOmJ.cjs');
+let __execbox_core = require("@execbox/core");
+
+//#region src/quickjsExecutor.ts
+/**
+* QuickJS-backed executor for one-shot sandboxed JavaScript runs.
+*/
+var QuickJsExecutor = class {
+	options;
+	/**
+	* Creates a QuickJS executor with one-shot runtime limits and host bridging configuration.
+	*/
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/**
+	* Executes JavaScript against the provided tool namespaces in a fresh QuickJS runtime.
+	*/
+	async execute(code, providers, options = {}) {
+		if (options.signal?.aborted) return (0, __execbox_core.createTimeoutExecuteResult)();
+		const abortController = new AbortController();
+		const onToolCall = (0, __execbox_core.createToolCallDispatcher)(providers, abortController.signal);
+		const onAbort = () => {
+			abortController.abort();
+		};
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await require_runner.runQuickJsSession({
+				abortController,
+				code,
+				onToolCall,
+				providers: (0, __execbox_core.extractProviderManifests)(providers)
+			}, {
+				...this.options,
+				...options
+			});
+		} finally {
+			options.signal?.removeEventListener("abort", onAbort);
+			abortController.abort();
+		}
+	}
+};
+
+//#endregion
+exports.QuickJsExecutor = QuickJsExecutor;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["runQuickJsSession"],"sources":["../src/quickjsExecutor.ts"],"sourcesContent":["import {\n  createTimeoutExecuteResult,\n  createToolCallDispatcher,\n  extractProviderManifests,\n  type ExecutionOptions,\n  type ExecuteResult,\n  type Executor,\n  type ResolvedToolProvider,\n} from \"@execbox/core\";\n\nimport { runQuickJsSession } from \"./runner/index\";\nimport type { QuickJsExecutorOptions } from \"./types\";\n\n/**\n * QuickJS-backed executor for one-shot sandboxed JavaScript runs.\n */\nexport class QuickJsExecutor implements Executor {\n  private readonly options: QuickJsExecutorOptions;\n\n  /**\n   * Creates a QuickJS executor with one-shot runtime limits and host bridging configuration.\n   */\n  constructor(options: QuickJsExecutorOptions = {}) {\n    this.options = options;\n  }\n\n  /**\n   * Executes JavaScript against the provided tool namespaces in a fresh QuickJS runtime.\n   */\n  async execute(\n    code: string,\n    providers: ResolvedToolProvider[],\n    options: ExecutionOptions = {},\n  ): Promise<ExecuteResult> {\n    if (options.signal?.aborted) {\n      return createTimeoutExecuteResult();\n    }\n\n    const abortController = new AbortController();\n    const onToolCall = createToolCallDispatcher(\n      providers,\n      abortController.signal,\n    );\n    const onAbort = () => {\n      abortController.abort();\n    };\n\n    options.signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n    try {\n      return await runQuickJsSession(\n        {\n          abortController,\n          code,\n          onToolCall,\n          providers: extractProviderManifests(providers),\n        },\n        {\n          ...this.options,\n          ...options,\n        },\n      );\n    } finally {\n      options.signal?.removeEventListener(\"abort\", onAbort);\n      abortController.abort();\n    }\n  }\n}\n"],"mappings":";;;;;;;AAgBA,IAAa,kBAAb,MAAiD;CAC/C,AAAiB;;;;CAKjB,YAAY,UAAkC,EAAE,EAAE;AAChD,OAAK,UAAU;;;;;CAMjB,MAAM,QACJ,MACA,WACA,UAA4B,EAAE,EACN;AACxB,MAAI,QAAQ,QAAQ,QAClB,wDAAmC;EAGrC,MAAM,kBAAkB,IAAI,iBAAiB;EAC7C,MAAM,0DACJ,WACA,gBAAgB,OACjB;EACD,MAAM,gBAAgB;AACpB,mBAAgB,OAAO;;AAGzB,UAAQ,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;AAElE,MAAI;AACF,UAAO,MAAMA,iCACX;IACE;IACA;IACA;IACA,wDAAoC,UAAU;IAC/C,EACD;IACE,GAAG,KAAK;IACR,GAAG;IACJ,CACF;YACO;AACR,WAAQ,QAAQ,oBAAoB,SAAS,QAAQ;AACrD,mBAAgB,OAAO"}

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+import { t as QuickJsExecutorOptions } from "./types-BB8mb_-T.cjs";
+import { ExecuteResult, ExecutionOptions, Executor, ResolvedToolProvider } from "@execbox/core";
+
+//#region src/quickjsExecutor.d.ts
+
+/**
+ * QuickJS-backed executor for one-shot sandboxed JavaScript runs.
+ */
+declare class QuickJsExecutor implements Executor {
+  private readonly options;
+  /**
+   * Creates a QuickJS executor with one-shot runtime limits and host bridging configuration.
+   */
+  constructor(options?: QuickJsExecutorOptions);
+  /**
+   * Executes JavaScript against the provided tool namespaces in a fresh QuickJS runtime.
+   */
+  execute(code: string, providers: ResolvedToolProvider[], options?: ExecutionOptions): Promise<ExecuteResult>;
+}
+//#endregion
+export { QuickJsExecutor, type QuickJsExecutorOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/quickjsExecutor.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;AAMuB,cANV,eAAA,YAA2B,QAMjB,CAAA;EASR,iBAAA,OAAA;EACF;;;EAhB2B,WAAA,CAAA,OAAA,CAAA,EAMjB,sBANiB;EAAQ;;;mCAejC,kCACF,mBACR,QAAQ"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { t as QuickJsExecutorOptions } from "./types-D7uau0GM.js";
+import { ExecuteResult, ExecutionOptions, Executor, ResolvedToolProvider } from "@execbox/core";
+
+//#region src/quickjsExecutor.d.ts
+
+/**
+ * QuickJS-backed executor for one-shot sandboxed JavaScript runs.
+ */
+declare class QuickJsExecutor implements Executor {
+  private readonly options;
+  /**
+   * Creates a QuickJS executor with one-shot runtime limits and host bridging configuration.
+   */
+  constructor(options?: QuickJsExecutorOptions);
+  /**
+   * Executes JavaScript against the provided tool namespaces in a fresh QuickJS runtime.
+   */
+  execute(code: string, providers: ResolvedToolProvider[], options?: ExecutionOptions): Promise<ExecuteResult>;
+}
+//#endregion
+export { QuickJsExecutor, type QuickJsExecutorOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/quickjsExecutor.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;AAMuB,cANV,eAAA,YAA2B,QAMjB,CAAA;EASR,iBAAA,OAAA;EACF;;;EAhB2B,WAAA,CAAA,OAAA,CAAA,EAMjB,sBANiB;EAAQ;;;mCAejC,kCACF,mBACR,QAAQ"}

package/dist/index.js

@@ -0,0 +1,46 @@
+import { t as runQuickJsSession } from "./runner-DVOLiGt4.js";
+import { createTimeoutExecuteResult, createToolCallDispatcher, extractProviderManifests } from "@execbox/core";
+
+//#region src/quickjsExecutor.ts
+/**
+* QuickJS-backed executor for one-shot sandboxed JavaScript runs.
+*/
+var QuickJsExecutor = class {
+	options;
+	/**
+	* Creates a QuickJS executor with one-shot runtime limits and host bridging configuration.
+	*/
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/**
+	* Executes JavaScript against the provided tool namespaces in a fresh QuickJS runtime.
+	*/
+	async execute(code, providers, options = {}) {
+		if (options.signal?.aborted) return createTimeoutExecuteResult();
+		const abortController = new AbortController();
+		const onToolCall = createToolCallDispatcher(providers, abortController.signal);
+		const onAbort = () => {
+			abortController.abort();
+		};
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await runQuickJsSession({
+				abortController,
+				code,
+				onToolCall,
+				providers: extractProviderManifests(providers)
+			}, {
+				...this.options,
+				...options
+			});
+		} finally {
+			options.signal?.removeEventListener("abort", onAbort);
+			abortController.abort();
+		}
+	}
+};
+
+//#endregion
+export { QuickJsExecutor };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/quickjsExecutor.ts"],"sourcesContent":["import {\n  createTimeoutExecuteResult,\n  createToolCallDispatcher,\n  extractProviderManifests,\n  type ExecutionOptions,\n  type ExecuteResult,\n  type Executor,\n  type ResolvedToolProvider,\n} from \"@execbox/core\";\n\nimport { runQuickJsSession } from \"./runner/index\";\nimport type { QuickJsExecutorOptions } from \"./types\";\n\n/**\n * QuickJS-backed executor for one-shot sandboxed JavaScript runs.\n */\nexport class QuickJsExecutor implements Executor {\n  private readonly options: QuickJsExecutorOptions;\n\n  /**\n   * Creates a QuickJS executor with one-shot runtime limits and host bridging configuration.\n   */\n  constructor(options: QuickJsExecutorOptions = {}) {\n    this.options = options;\n  }\n\n  /**\n   * Executes JavaScript against the provided tool namespaces in a fresh QuickJS runtime.\n   */\n  async execute(\n    code: string,\n    providers: ResolvedToolProvider[],\n    options: ExecutionOptions = {},\n  ): Promise<ExecuteResult> {\n    if (options.signal?.aborted) {\n      return createTimeoutExecuteResult();\n    }\n\n    const abortController = new AbortController();\n    const onToolCall = createToolCallDispatcher(\n      providers,\n      abortController.signal,\n    );\n    const onAbort = () => {\n      abortController.abort();\n    };\n\n    options.signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n    try {\n      return await runQuickJsSession(\n        {\n          abortController,\n          code,\n          onToolCall,\n          providers: extractProviderManifests(providers),\n        },\n        {\n          ...this.options,\n          ...options,\n        },\n      );\n    } finally {\n      options.signal?.removeEventListener(\"abort\", onAbort);\n      abortController.abort();\n    }\n  }\n}\n"],"mappings":";;;;;;;AAgBA,IAAa,kBAAb,MAAiD;CAC/C,AAAiB;;;;CAKjB,YAAY,UAAkC,EAAE,EAAE;AAChD,OAAK,UAAU;;;;;CAMjB,MAAM,QACJ,MACA,WACA,UAA4B,EAAE,EACN;AACxB,MAAI,QAAQ,QAAQ,QAClB,QAAO,4BAA4B;EAGrC,MAAM,kBAAkB,IAAI,iBAAiB;EAC7C,MAAM,aAAa,yBACjB,WACA,gBAAgB,OACjB;EACD,MAAM,gBAAgB;AACpB,mBAAgB,OAAO;;AAGzB,UAAQ,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;AAElE,MAAI;AACF,UAAO,MAAM,kBACX;IACE;IACA;IACA;IACA,WAAW,yBAAyB,UAAU;IAC/C,EACD;IACE,GAAG,KAAK;IACR,GAAG;IACJ,CACF;YACO;AACR,WAAQ,QAAQ,oBAAoB,SAAS,QAAQ;AACrD,mBAAgB,OAAO"}

package/dist/runner/index.cjs

@@ -0,0 +1,3 @@
+const require_runner = require('../runner-CYXIVOmJ.cjs');
+
+exports.runQuickJsSession = require_runner.runQuickJsSession;

package/dist/runner/index.d.cts

@@ -0,0 +1,104 @@
+import { t as QuickJsExecutorOptions } from "../types-BB8mb_-T.cjs";
+
+//#region ../core/src/types.d.ts
+
+/**
+ * Stable error codes returned by executors and wrapped tool calls.
+ */
+type ExecuteErrorCode = "timeout" | "memory_limit" | "validation_error" | "tool_error" | "runtime_error" | "serialization_error" | "internal_error";
+/**
+ * Structured execution failure returned in {@link ExecuteResult}.
+ */
+interface ExecuteError {
+  /** Machine-readable error category. */
+  code: ExecuteErrorCode;
+  /** Human-readable failure message. */
+  message: string;
+}
+/**
+ * Structured result returned by every executor invocation.
+ */
+type ExecuteResult<T = unknown> = {
+  durationMs: number;
+  logs: string[];
+  ok: true;
+  result: T;
+} | {
+  durationMs: number;
+  error: ExecuteError;
+  logs: string[];
+  ok: false;
+};
+//#endregion
+//#region ../core/src/runner.d.ts
+/**
+ * Transport-safe metadata for one exposed tool.
+ */
+interface ProviderToolManifest {
+  description?: string;
+  originalName: string;
+  safeName: string;
+}
+/**
+ * Namespace manifest shared with runner implementations.
+ */
+interface ProviderManifest {
+  name: string;
+  tools: Record<string, ProviderToolManifest>;
+  types: string;
+}
+/**
+ * Execution limits forwarded to runner implementations.
+ */
+interface ExecutorRuntimeOptions {
+  maxLogChars?: number;
+  maxLogLines?: number;
+  memoryLimitBytes?: number;
+  timeoutMs?: number;
+}
+/**
+ * Tool invocation request emitted from a runner.
+ */
+interface ToolCall {
+  input: unknown;
+  providerName: string;
+  safeToolName: string;
+}
+/**
+ * Trusted host response to a tool invocation request.
+ */
+type ToolCallResult = {
+  ok: true;
+  result: unknown;
+} | {
+  error: ExecuteError;
+  ok: false;
+};
+//#endregion
+//#region src/runner/index.d.ts
+/**
+ * Transport-neutral host tool call emitted from a QuickJS session.
+ */
+type QuickJsSessionToolCall = ToolCall;
+/**
+ * Input required to run one transport-backed QuickJS execution session.
+ */
+interface QuickJsSessionRequest {
+  abortController?: AbortController;
+  code: string;
+  onToolCall: (call: ToolCall) => Promise<ToolCallResult> | ToolCallResult;
+  onStarted?: () => void;
+  providers: ProviderManifest[];
+  signal?: AbortSignal;
+}
+/**
+ * Options controlling one transport-backed QuickJS session.
+ */
+type QuickJsSessionOptions = QuickJsExecutorOptions & ExecutorRuntimeOptions;
+/**
+ * Runs one QuickJS-backed execution session using a transport-neutral tool callback.
+ */
+declare function runQuickJsSession(request: QuickJsSessionRequest, options?: QuickJsSessionOptions): Promise<ExecuteResult>;
+//#endregion
+export { QuickJsSessionOptions, QuickJsSessionRequest, QuickJsSessionToolCall, runQuickJsSession };
+//# sourceMappingURL=index.d.cts.map

package/dist/runner/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../../core/src/types.ts","../../../core/src/runner.ts","../../src/runner/index.ts"],"sourcesContent":[],"mappings":";;;;ACeA;AASA;AASA;AAiBiB,KDnCL,gBAAA,GCmCa,SAAA,GAAA,cAAA,GAAA,kBAAA,GAAA,YAAA,GAAA,eAAA,GAAA,qBAAA,GAAA,gBAAA;AASzB;;;UDhCiB,YAAA;EEuBL;EAKK,IAAA,EF1BT,gBE0BS;EACG;EAEC,OAAA,EAAA,MAAA;;;;;AAGV,KFxBC,aEwBD,CAAA,IAAA,OAAA,CAAA,GAAA;EAAW,UAAA,EAAA,MAAA;EAMV,IAAA,EAAA,MAAA,EAAA;EAkSU,EAAA,EAAA,IAAA;EACX,MAAA,EF5TG,CE4TH;CACA,GAAA;EACA,UAAA,EAAA,MAAA;EAAR,KAAA,EF1TU,YE0TV;EAAO,IAAA,EAAA,MAAA,EAAA;;;;;;;AFzVV;AAYiB,UCZA,oBAAA,CDcT;EAQI,WAAA,CAAA,EAAA,MAAa;;;;ACtBzB;AASA;AASA;AAiBiB,UA1BA,gBAAA,CA0BQ;EASb,IAAA,EAAA,MAAA;SAjCH,eAAe;;;ACwBxB;AAKA;;AAGqB,UDzBJ,sBAAA,CCyBI;EAAqB,WAAA,CAAA,EAAA,MAAA;EAAR,WAAA,CAAA,EAAA,MAAA;EAA0B,gBAAA,CAAA,EAAA,MAAA;EAE/C,SAAA,CAAA,EAAA,MAAA;;;;;UDVI,QAAA;;;;;;;;KASL,cAAA;;;;SAMC;;;;;;ADlDb;AAYA;AAUY,KEaA,sBAAA,GAAyB,QFJxB;;;;AC/BI,UCwCA,qBAAA,CDxCoB;EASpB,eAAA,CAAA,ECgCG,eD9BI;EAOP,IAAA,EAAA,MAAA;EAiBA,UAAA,EAAQ,CAAA,IAAA,ECQJ,QDRI,EAAA,GCQS,ODRT,CCQiB,cDRjB,CAAA,GCQmC,cDRnC;EASb,SAAA,CAAA,EAAA,GAAA,GAAc,IAAA;aCCb;WACF;;AAXX;AAKA;;AAGqB,KAST,qBAAA,GAAwB,sBATf,GAUnB,sBAVmB;;;;AAER,iBAySS,iBAAA,CAzST,OAAA,EA0SF,qBA1SE,EAAA,OAAA,CAAA,EA2SF,qBA3SE,CAAA,EA4SV,OA5SU,CA4SF,aA5SE,CAAA"}

package/dist/runner/index.d.ts

@@ -0,0 +1,104 @@
+import { t as QuickJsExecutorOptions } from "../types-D7uau0GM.js";
+
+//#region ../core/src/types.d.ts
+
+/**
+ * Stable error codes returned by executors and wrapped tool calls.
+ */
+type ExecuteErrorCode = "timeout" | "memory_limit" | "validation_error" | "tool_error" | "runtime_error" | "serialization_error" | "internal_error";
+/**
+ * Structured execution failure returned in {@link ExecuteResult}.
+ */
+interface ExecuteError {
+  /** Machine-readable error category. */
+  code: ExecuteErrorCode;
+  /** Human-readable failure message. */
+  message: string;
+}
+/**
+ * Structured result returned by every executor invocation.
+ */
+type ExecuteResult<T = unknown> = {
+  durationMs: number;
+  logs: string[];
+  ok: true;
+  result: T;
+} | {
+  durationMs: number;
+  error: ExecuteError;
+  logs: string[];
+  ok: false;
+};
+//#endregion
+//#region ../core/src/runner.d.ts
+/**
+ * Transport-safe metadata for one exposed tool.
+ */
+interface ProviderToolManifest {
+  description?: string;
+  originalName: string;
+  safeName: string;
+}
+/**
+ * Namespace manifest shared with runner implementations.
+ */
+interface ProviderManifest {
+  name: string;
+  tools: Record<string, ProviderToolManifest>;
+  types: string;
+}
+/**
+ * Execution limits forwarded to runner implementations.
+ */
+interface ExecutorRuntimeOptions {
+  maxLogChars?: number;
+  maxLogLines?: number;
+  memoryLimitBytes?: number;
+  timeoutMs?: number;
+}
+/**
+ * Tool invocation request emitted from a runner.
+ */
+interface ToolCall {
+  input: unknown;
+  providerName: string;
+  safeToolName: string;
+}
+/**
+ * Trusted host response to a tool invocation request.
+ */
+type ToolCallResult = {
+  ok: true;
+  result: unknown;
+} | {
+  error: ExecuteError;
+  ok: false;
+};
+//#endregion
+//#region src/runner/index.d.ts
+/**
+ * Transport-neutral host tool call emitted from a QuickJS session.
+ */
+type QuickJsSessionToolCall = ToolCall;
+/**
+ * Input required to run one transport-backed QuickJS execution session.
+ */
+interface QuickJsSessionRequest {
+  abortController?: AbortController;
+  code: string;
+  onToolCall: (call: ToolCall) => Promise<ToolCallResult> | ToolCallResult;
+  onStarted?: () => void;
+  providers: ProviderManifest[];
+  signal?: AbortSignal;
+}
+/**
+ * Options controlling one transport-backed QuickJS session.
+ */
+type QuickJsSessionOptions = QuickJsExecutorOptions & ExecutorRuntimeOptions;
+/**
+ * Runs one QuickJS-backed execution session using a transport-neutral tool callback.
+ */
+declare function runQuickJsSession(request: QuickJsSessionRequest, options?: QuickJsSessionOptions): Promise<ExecuteResult>;
+//#endregion
+export { QuickJsSessionOptions, QuickJsSessionRequest, QuickJsSessionToolCall, runQuickJsSession };
+//# sourceMappingURL=index.d.ts.map

package/dist/runner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../core/src/types.ts","../../../core/src/runner.ts","../../src/runner/index.ts"],"sourcesContent":[],"mappings":";;;;ACeA;AASA;AASA;AAiBiB,KDnCL,gBAAA,GCmCa,SAAA,GAAA,cAAA,GAAA,kBAAA,GAAA,YAAA,GAAA,eAAA,GAAA,qBAAA,GAAA,gBAAA;AASzB;;;UDhCiB,YAAA;EEuBL;EAKK,IAAA,EF1BT,gBE0BS;EACG;EAEC,OAAA,EAAA,MAAA;;;;;AAGV,KFxBC,aEwBD,CAAA,IAAA,OAAA,CAAA,GAAA;EAAW,UAAA,EAAA,MAAA;EAMV,IAAA,EAAA,MAAA,EAAA;EAkSU,EAAA,EAAA,IAAA;EACX,MAAA,EF5TG,CE4TH;CACA,GAAA;EACA,UAAA,EAAA,MAAA;EAAR,KAAA,EF1TU,YE0TV;EAAO,IAAA,EAAA,MAAA,EAAA;;;;;;;AFzVV;AAYiB,UCZA,oBAAA,CDcT;EAQI,WAAA,CAAA,EAAA,MAAa;;;;ACtBzB;AASA;AASA;AAiBiB,UA1BA,gBAAA,CA0BQ;EASb,IAAA,EAAA,MAAA;SAjCH,eAAe;;;ACwBxB;AAKA;;AAGqB,UDzBJ,sBAAA,CCyBI;EAAqB,WAAA,CAAA,EAAA,MAAA;EAAR,WAAA,CAAA,EAAA,MAAA;EAA0B,gBAAA,CAAA,EAAA,MAAA;EAE/C,SAAA,CAAA,EAAA,MAAA;;;;;UDVI,QAAA;;;;;;;;KASL,cAAA;;;;SAMC;;;;;;ADlDb;AAYA;AAUY,KEaA,sBAAA,GAAyB,QFJxB;;;;AC/BI,UCwCA,qBAAA,CDxCoB;EASpB,eAAA,CAAA,ECgCG,eD9BI;EAOP,IAAA,EAAA,MAAA;EAiBA,UAAA,EAAQ,CAAA,IAAA,ECQJ,QDRI,EAAA,GCQS,ODRT,CCQiB,cDRjB,CAAA,GCQmC,cDRnC;EASb,SAAA,CAAA,EAAA,GAAA,GAAc,IAAA;aCCb;WACF;;AAXX;AAKA;;AAGqB,KAST,qBAAA,GAAwB,sBATf,GAUnB,sBAVmB;;;;AAER,iBAySS,iBAAA,CAzST,OAAA,EA0SF,qBA1SE,EAAA,OAAA,CAAA,EA2SF,qBA3SE,CAAA,EA4SV,OA5SU,CA4SF,aA5SE,CAAA"}

package/dist/runner/index.js

@@ -0,0 +1,3 @@
+import { t as runQuickJsSession } from "../runner-DVOLiGt4.js";
+
+export { runQuickJsSession };

package/dist/runner/protocolEndpoint.cjs

@@ -0,0 +1,101 @@
+const require_runner = require('../runner-CYXIVOmJ.cjs');
+let node_crypto = require("node:crypto");
+
+//#region src/runner/protocolEndpoint.ts
+/**
+* Attaches the shared QuickJS protocol loop to a worker/process messaging port.
+*/
+function attachQuickJsProtocolEndpoint(port) {
+	const pendingToolCalls = /* @__PURE__ */ new Map();
+	let activeAbortController;
+	let activeExecutionId;
+	async function startExecution(message) {
+		if (activeExecutionId) {
+			port.send({
+				durationMs: 0,
+				error: {
+					code: "internal_error",
+					message: "QuickJS endpoint already has an active execution"
+				},
+				id: message.id,
+				logs: [],
+				ok: false,
+				type: "done"
+			});
+			return;
+		}
+		const abortController = new AbortController();
+		activeAbortController = abortController;
+		activeExecutionId = message.id;
+		try {
+			const result = await require_runner.runQuickJsSession({
+				abortController,
+				code: message.code,
+				onStarted: () => {
+					port.send({
+						id: message.id,
+						type: "started"
+					});
+				},
+				onToolCall: (call) => new Promise((resolve) => {
+					const callId = (0, node_crypto.randomUUID)();
+					pendingToolCalls.set(callId, resolve);
+					port.send({
+						...call,
+						callId,
+						type: "tool_call"
+					});
+				}),
+				providers: message.providers
+			}, message.options);
+			port.send({
+				...result,
+				id: message.id,
+				type: "done"
+			});
+		} catch (error) {
+			port.send({
+				durationMs: 0,
+				error: {
+					code: "internal_error",
+					message: error instanceof Error ? error.message : String(error)
+				},
+				id: message.id,
+				logs: [],
+				ok: false,
+				type: "done"
+			});
+		} finally {
+			pendingToolCalls.clear();
+			activeAbortController = void 0;
+			activeExecutionId = void 0;
+		}
+	}
+	const maybeDetach = port.onMessage((message) => {
+		switch (message.type) {
+			case "cancel":
+				if (message.id === activeExecutionId) activeAbortController?.abort();
+				break;
+			case "execute":
+				startExecution(message);
+				break;
+			case "tool_result": {
+				const resolve = pendingToolCalls.get(message.callId);
+				pendingToolCalls.delete(message.callId);
+				resolve?.(message);
+				break;
+			}
+		}
+	});
+	return () => {
+		if (typeof maybeDetach === "function") maybeDetach();
+		pendingToolCalls.clear();
+		activeAbortController?.abort();
+		activeAbortController = void 0;
+		activeExecutionId = void 0;
+	};
+}
+
+//#endregion
+exports.attachQuickJsProtocolEndpoint = attachQuickJsProtocolEndpoint;
+//# sourceMappingURL=protocolEndpoint.cjs.map

package/dist/runner/protocolEndpoint.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolEndpoint.cjs","names":["activeAbortController: AbortController | undefined","activeExecutionId: string | undefined","runQuickJsSession"],"sources":["../../src/runner/protocolEndpoint.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nimport type {\n  DispatcherMessage,\n  ExecuteMessage,\n  RunnerMessage,\n  ToolCallResult,\n} from \"@execbox/protocol\";\n\nimport { runQuickJsSession } from \"./index.ts\";\n\n/**\n * Minimal worker/process-side port used by the shared QuickJS protocol endpoint.\n */\nexport interface QuickJsProtocolPort {\n  onMessage(handler: (message: DispatcherMessage) => void): void | (() => void);\n  send(message: RunnerMessage): void;\n}\n\n/**\n * Attaches the shared QuickJS protocol loop to a worker/process messaging port.\n */\nexport function attachQuickJsProtocolEndpoint(\n  port: QuickJsProtocolPort,\n): () => void {\n  const pendingToolCalls = new Map<string, (result: ToolCallResult) => void>();\n  let activeAbortController: AbortController | undefined;\n  let activeExecutionId: string | undefined;\n\n  async function startExecution(message: ExecuteMessage): Promise<void> {\n    if (activeExecutionId) {\n      port.send({\n        durationMs: 0,\n        error: {\n          code: \"internal_error\",\n          message: \"QuickJS endpoint already has an active execution\",\n        },\n        id: message.id,\n        logs: [],\n        ok: false,\n        type: \"done\",\n      });\n      return;\n    }\n\n    const abortController = new AbortController();\n    activeAbortController = abortController;\n    activeExecutionId = message.id;\n\n    try {\n      const result = await runQuickJsSession(\n        {\n          abortController,\n          code: message.code,\n          onStarted: () => {\n            port.send({\n              id: message.id,\n              type: \"started\",\n            });\n          },\n          onToolCall: (call) =>\n            new Promise<ToolCallResult>((resolve) => {\n              const callId = randomUUID();\n              pendingToolCalls.set(callId, resolve);\n              port.send({\n                ...call,\n                callId,\n                type: \"tool_call\",\n              });\n            }),\n          providers: message.providers,\n        },\n        message.options,\n      );\n\n      port.send({\n        ...result,\n        id: message.id,\n        type: \"done\",\n      });\n    } catch (error) {\n      port.send({\n        durationMs: 0,\n        error: {\n          code: \"internal_error\",\n          message: error instanceof Error ? error.message : String(error),\n        },\n        id: message.id,\n        logs: [],\n        ok: false,\n        type: \"done\",\n      });\n    } finally {\n      pendingToolCalls.clear();\n      activeAbortController = undefined;\n      activeExecutionId = undefined;\n    }\n  }\n\n  const maybeDetach = port.onMessage((message: DispatcherMessage) => {\n    switch (message.type) {\n      case \"cancel\":\n        if (message.id === activeExecutionId) {\n          activeAbortController?.abort();\n        }\n        break;\n      case \"execute\":\n        void startExecution(message);\n        break;\n      case \"tool_result\": {\n        const resolve = pendingToolCalls.get(message.callId);\n        pendingToolCalls.delete(message.callId);\n        resolve?.(message);\n        break;\n      }\n    }\n  });\n\n  return () => {\n    if (typeof maybeDetach === \"function\") {\n      maybeDetach();\n    }\n    pendingToolCalls.clear();\n    activeAbortController?.abort();\n    activeAbortController = undefined;\n    activeExecutionId = undefined;\n  };\n}\n"],"mappings":";;;;;;;AAsBA,SAAgB,8BACd,MACY;CACZ,MAAM,mCAAmB,IAAI,KAA+C;CAC5E,IAAIA;CACJ,IAAIC;CAEJ,eAAe,eAAe,SAAwC;AACpE,MAAI,mBAAmB;AACrB,QAAK,KAAK;IACR,YAAY;IACZ,OAAO;KACL,MAAM;KACN,SAAS;KACV;IACD,IAAI,QAAQ;IACZ,MAAM,EAAE;IACR,IAAI;IACJ,MAAM;IACP,CAAC;AACF;;EAGF,MAAM,kBAAkB,IAAI,iBAAiB;AAC7C,0BAAwB;AACxB,sBAAoB,QAAQ;AAE5B,MAAI;GACF,MAAM,SAAS,MAAMC,iCACnB;IACE;IACA,MAAM,QAAQ;IACd,iBAAiB;AACf,UAAK,KAAK;MACR,IAAI,QAAQ;MACZ,MAAM;MACP,CAAC;;IAEJ,aAAa,SACX,IAAI,SAAyB,YAAY;KACvC,MAAM,sCAAqB;AAC3B,sBAAiB,IAAI,QAAQ,QAAQ;AACrC,UAAK,KAAK;MACR,GAAG;MACH;MACA,MAAM;MACP,CAAC;MACF;IACJ,WAAW,QAAQ;IACpB,EACD,QAAQ,QACT;AAED,QAAK,KAAK;IACR,GAAG;IACH,IAAI,QAAQ;IACZ,MAAM;IACP,CAAC;WACK,OAAO;AACd,QAAK,KAAK;IACR,YAAY;IACZ,OAAO;KACL,MAAM;KACN,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;KAChE;IACD,IAAI,QAAQ;IACZ,MAAM,EAAE;IACR,IAAI;IACJ,MAAM;IACP,CAAC;YACM;AACR,oBAAiB,OAAO;AACxB,2BAAwB;AACxB,uBAAoB;;;CAIxB,MAAM,cAAc,KAAK,WAAW,YAA+B;AACjE,UAAQ,QAAQ,MAAhB;GACE,KAAK;AACH,QAAI,QAAQ,OAAO,kBACjB,wBAAuB,OAAO;AAEhC;GACF,KAAK;AACH,IAAK,eAAe,QAAQ;AAC5B;GACF,KAAK,eAAe;IAClB,MAAM,UAAU,iBAAiB,IAAI,QAAQ,OAAO;AACpD,qBAAiB,OAAO,QAAQ,OAAO;AACvC,cAAU,QAAQ;AAClB;;;GAGJ;AAEF,cAAa;AACX,MAAI,OAAO,gBAAgB,WACzB,cAAa;AAEf,mBAAiB,OAAO;AACxB,yBAAuB,OAAO;AAC9B,0BAAwB;AACxB,sBAAoB"}

package/dist/runner/protocolEndpoint.d.cts

@@ -0,0 +1,18 @@
+import { DispatcherMessage, RunnerMessage } from "@execbox/protocol";
+
+//#region src/runner/protocolEndpoint.d.ts
+
+/**
+ * Minimal worker/process-side port used by the shared QuickJS protocol endpoint.
+ */
+interface QuickJsProtocolPort {
+  onMessage(handler: (message: DispatcherMessage) => void): void | (() => void);
+  send(message: RunnerMessage): void;
+}
+/**
+ * Attaches the shared QuickJS protocol loop to a worker/process messaging port.
+ */
+declare function attachQuickJsProtocolEndpoint(port: QuickJsProtocolPort): () => void;
+//#endregion
+export { QuickJsProtocolPort, attachQuickJsProtocolEndpoint };
+//# sourceMappingURL=protocolEndpoint.d.cts.map

package/dist/runner/protocolEndpoint.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolEndpoint.d.cts","names":[],"sources":["../../src/runner/protocolEndpoint.ts"],"sourcesContent":[],"mappings":";;;;;;AAcA;AAQgB,UARC,mBAAA,CAQ4B;+BAPd;gBACf;;;;;iBAMA,6BAAA,OACR"}

package/dist/runner/protocolEndpoint.d.ts

@@ -0,0 +1,18 @@
+import { DispatcherMessage, RunnerMessage } from "@execbox/protocol";
+
+//#region src/runner/protocolEndpoint.d.ts
+
+/**
+ * Minimal worker/process-side port used by the shared QuickJS protocol endpoint.
+ */
+interface QuickJsProtocolPort {
+  onMessage(handler: (message: DispatcherMessage) => void): void | (() => void);
+  send(message: RunnerMessage): void;
+}
+/**
+ * Attaches the shared QuickJS protocol loop to a worker/process messaging port.
+ */
+declare function attachQuickJsProtocolEndpoint(port: QuickJsProtocolPort): () => void;
+//#endregion
+export { QuickJsProtocolPort, attachQuickJsProtocolEndpoint };
+//# sourceMappingURL=protocolEndpoint.d.ts.map

package/dist/runner/protocolEndpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolEndpoint.d.ts","names":[],"sources":["../../src/runner/protocolEndpoint.ts"],"sourcesContent":[],"mappings":";;;;;;AAcA;AAQgB,UARC,mBAAA,CAQ4B;+BAPd;gBACf;;;;;iBAMA,6BAAA,OACR"}