refactor(quickjs): consolidate hosted executor surface

Author: aallam

.changeset/quickjs-surface-consolidation.md

@@ -0,0 +1,8 @@
+---
+"@execbox/quickjs": minor
+"@execbox/protocol": minor
+---
+
+`@execbox/quickjs` now covers inline, worker-hosted, and process-hosted QuickJS execution through `new QuickJsExecutor({ host })`. Migrate `@execbox/process` usage to `new QuickJsExecutor({ host: "process" })` and `@execbox/worker` usage to `new QuickJsExecutor({ host: "worker" })`.
+
+`@execbox/protocol` no longer re-exports `createToolCallDispatcher` or `extractProviderManifests`. Import those helpers from `@execbox/core` instead.

AGENTS.md

@@ -4,7 +4,7 @@
 
 - `execbox` is a Node.js 22+ npm workspace that publishes the `@execbox/*` package family.
 - Core source lives under `packages/*/src`, tests live under `packages/*/__tests__`, runnable examples live under `examples/`, and the public docs site lives under `docs/`.
-- The workspace currently contains `@execbox/core`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/remote`, `@execbox/process`, `@execbox/worker`, and `@execbox/isolated-vm`.
+- The workspace currently contains `@execbox/core`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/remote`, and `@execbox/isolated-vm`.
 - Keep changes aligned with existing package boundaries. Prefer changing the owning package instead of introducing cross-package shortcuts.
 
 ## Setup Commands
@@ -24,15 +24,15 @@
 
 - Do not edit generated `dist/` output under `packages/*/dist`; build artifacts are produced from source.
 - Preserve the existing ESM + TypeScript workspace structure and root script orchestration.
-- When you change exported APIs in `packages/*/src`, keep JSDoc in sync. ESLint requires JSDoc coverage for exported package symbols.
+- When you change exported APIs in `packages/*/src`, keep JSDoc in sync. Public functions, constants, types, and classes should always ship with JSDoc, and ESLint requires JSDoc coverage for exported package symbols.
 - Prefer inline type imports where possible; the ESLint config enforces `@typescript-eslint/consistent-type-imports`.
 - Update examples or docs when you change public package behavior, developer workflow, or recommended runtime choices.
 
 ## Testing Instructions
 
 - For most code changes, run `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, and `npm run build`.
 - If you change package exports, manifest fields, or published type-resolution behavior, also run `npm run package:check`.
-- If you change the public API of `@execbox/core`, `@execbox/core/mcp`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/process`, `@execbox/worker`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`, also run `npm run api:check`.
+- If you change the public API of `@execbox/core`, `@execbox/core/mcp`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`, also run `npm run api:check`.
 - If you change docs site content, navigation, or VitePress config, also run `npm run docs:build`.
 - If you touch execution boundaries, timeout handling, abort propagation, schema validation, or log/memory controls, also run `npm run test:security`.
 - If you touch `@execbox/isolated-vm` or codepaths guarded by `VITEST_INCLUDE_ISOLATED_VM`, run `npm run test:isolated-vm` or `npm run verify:isolated-vm`.
@@ -48,7 +48,7 @@
 - Use Conventional Commits for git commit messages, for example `docs: add agent and contributor guides` or `fix(worker): handle timeout classification`.
 - Published package releases are managed with Changesets and GitHub Actions.
 - Add a `.changeset/*.md` entry when a change affects published package behavior, public APIs, or release notes for one or more `@execbox/*` packages.
-- If you intentionally change a checked-in API report for `@execbox/core`, `@execbox/core/mcp`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/process`, `@execbox/worker`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`, update it with `npm run api:update` in the same change as the code and changeset.
+- If you intentionally change a checked-in API report for `@execbox/core`, `@execbox/core/mcp`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`, update it with `npm run api:update` in the same change as the code and changeset.
 - Skip a changeset for docs-only, examples-only, CI-only, or internal maintenance changes that do not affect published package behavior.
 
 ## Useful References

CONTRIBUTING.md

@@ -13,7 +13,7 @@ This guide is for both humans and coding agents. Agent-specific operating instru
 ## Working In This Repo
 
 - Make changes in the package that owns the behavior you are updating.
-- Keep exported API documentation current when you change exported symbols in `packages/*/src`; the ESLint config requires JSDoc for exported package APIs.
+- Keep exported API documentation current when you change exported symbols in `packages/*/src`; public functions, constants, types, and classes should ship with JSDoc, and the ESLint config enforces that for package APIs.
 - Update tests with behavior changes.
 - Update examples and docs when public behavior, recommended setup, or runtime tradeoffs change.
 
@@ -27,7 +27,7 @@ This guide is for both humans and coding agents. Agent-specific operating instru
 
 Choose the smallest verification set that covers your change, and include the commands you ran in your PR or handoff notes when the context would help reviewers.
 
-- Public API changes to `@execbox/core`, `@execbox/core/mcp`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/process`, `@execbox/worker`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`: run `npm run api:check`
+- Public API changes to `@execbox/core`, `@execbox/core/mcp`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`: run `npm run api:check`
 
 ## Changesets
 

README.md

@@ -6,22 +6,20 @@ Portable code execution for [Model Context Protocol](https://modelcontextprotoco
 
 [![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)
-[![Packages](https://img.shields.io/badge/packages-7-111827?style=flat-square)](#package-map)
+[![Packages](https://img.shields.io/badge/packages-5-111827?style=flat-square)](#package-map)
 
 </div>
 
-Execbox turns host tool catalogs into callable guest namespaces, supports MCP wrapping on both sides of the boundary, and lets you place guest JavaScript where it fits your deployment: in-process, in a worker, in a child process, or behind your own remote transport.
+Execbox turns host tool catalogs into callable guest namespaces, supports MCP wrapping on both sides of the boundary, and lets you place guest JavaScript where it fits your deployment: inline, behind a worker or child-process host, or across your own remote transport.
 
 ## Package Map
 
 | Package                                           | npm                                                                                                                                   | What it is for                                                 |
 | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | [`@execbox/core`](./packages/core/)               | [![npm](https://img.shields.io/npm/v/%40execbox%2Fcore?style=flat-square)](https://www.npmjs.com/package/@execbox/core)               | Core execution contract, provider resolution, and MCP adapters |
-| [`@execbox/protocol`](./packages/protocol/)       | [![npm](https://img.shields.io/npm/v/%40execbox%2Fprotocol?style=flat-square)](https://www.npmjs.com/package/@execbox/protocol)       | Transport-safe messages and shared host-session helpers        |
-| [`@execbox/quickjs`](./packages/quickjs/)         | [![npm](https://img.shields.io/npm/v/%40execbox%2Fquickjs?style=flat-square)](https://www.npmjs.com/package/@execbox/quickjs)         | QuickJS backend for execbox                                    |
+| [`@execbox/protocol`](./packages/protocol/)       | [![npm](https://img.shields.io/npm/v/%40execbox%2Fprotocol?style=flat-square)](https://www.npmjs.com/package/@execbox/protocol)       | Low-level transport messages, sessions, and resource pools     |
+| [`@execbox/quickjs`](./packages/quickjs/)         | [![npm](https://img.shields.io/npm/v/%40execbox%2Fquickjs?style=flat-square)](https://www.npmjs.com/package/@execbox/quickjs)         | QuickJS executor for inline, worker, and process hosts         |
 | [`@execbox/remote`](./packages/remote/)           | [![npm](https://img.shields.io/npm/v/%40execbox%2Fremote?style=flat-square)](https://www.npmjs.com/package/@execbox/remote)           | Transport-backed remote executor                               |
-| [`@execbox/process`](./packages/process/)         | [![npm](https://img.shields.io/npm/v/%40execbox%2Fprocess?style=flat-square)](https://www.npmjs.com/package/@execbox/process)         | Child-process QuickJS executor                                 |
-| [`@execbox/worker`](./packages/worker/)           | [![npm](https://img.shields.io/npm/v/%40execbox%2Fworker?style=flat-square)](https://www.npmjs.com/package/@execbox/worker)           | Worker-thread QuickJS executor                                 |
 | [`@execbox/isolated-vm`](./packages/isolated-vm/) | [![npm](https://img.shields.io/npm/v/%40execbox%2Fisolated-vm?style=flat-square)](https://www.npmjs.com/package/@execbox/isolated-vm) | `isolated-vm` backend for execbox                              |
 
 ## Examples

benchmarks/config.ts

@@ -1,7 +1,5 @@
 import type { Executor } from "@execbox/core";
 import { QuickJsExecutor } from "@execbox/quickjs";
-import { ProcessExecutor } from "@execbox/process";
-import { WorkerExecutor } from "@execbox/worker";
 
 export type DisposableExecutor = Executor & {
   dispose?(): Promise<void>;
@@ -57,29 +55,37 @@ export function createBenchmarkFactories(): ExecutorFactory[] {
     {
       name: "worker (ephemeral)",
       create: () =>
-        new WorkerExecutor({ mode: "ephemeral" }) as DisposableExecutor,
+        new QuickJsExecutor({
+          host: "worker",
+          mode: "ephemeral",
+        }) as DisposableExecutor,
       supportsExplicitPrewarm: false,
     },
     {
       name: "worker (pooled)",
       create: () =>
-        new WorkerExecutor(
-          createPooledBenchmarkOptions(),
-        ) as DisposableExecutor,
+        new QuickJsExecutor({
+          host: "worker",
+          ...createPooledBenchmarkOptions(),
+        }) as DisposableExecutor,
       supportsExplicitPrewarm: true,
     },
     {
       name: "process (ephemeral)",
       create: () =>
-        new ProcessExecutor({ mode: "ephemeral" }) as DisposableExecutor,
+        new QuickJsExecutor({
+          host: "process",
+          mode: "ephemeral",
+        }) as DisposableExecutor,
       supportsExplicitPrewarm: false,
     },
     {
       name: "process (pooled)",
       create: () =>
-        new ProcessExecutor(
-          createPooledBenchmarkOptions(),
-        ) as DisposableExecutor,
+        new QuickJsExecutor({
+          host: "process",
+          ...createPooledBenchmarkOptions(),
+        }) as DisposableExecutor,
       supportsExplicitPrewarm: true,
     },
   ];
@@ -98,6 +104,6 @@ export function createContentionExecutor(
 ): DisposableExecutor {
   const pool = createContentionPoolOptions(poolSize);
   return executorType === "worker"
-    ? (new WorkerExecutor({ pool }) as DisposableExecutor)
-    : (new ProcessExecutor({ pool }) as DisposableExecutor);
+    ? (new QuickJsExecutor({ host: "worker", pool }) as DisposableExecutor)
+    : (new QuickJsExecutor({ host: "process", pool }) as DisposableExecutor);
 }

benchmarks/results.md

@@ -123,7 +123,7 @@ The pooled benchmark factories in this suite use a fixed `pool.maxSize: 2`.
 
 ## 7. Host-Process Memory Delta
 
-This suite only measures the parent Node process. It does not attempt to attribute child-process RSS back to `ProcessExecutor`.
+This suite only measures the parent Node process. It does not attempt to attribute child-process RSS back to `QuickJsExecutor({ host: "process" })`.
 
 | Executor             | Heap Delta | RSS Delta | External Delta |
 | -------------------- | ---------- | --------- | -------------- |
@@ -151,4 +151,4 @@ This suite only measures the parent Node process. It does not attempt to attribu
 ### What this snapshot does not prove
 
 - It does not prove exact throughput rankings for every workload or host. The concurrency and tool-call suites are still sensitive to local scheduler noise.
-- It does not prove memory behavior for `ProcessExecutor`, because the memory suite intentionally avoids reporting child-process RSS as if it were host-process memory.
+- It does not prove memory behavior for `QuickJsExecutor({ host: "process" })`, because the memory suite intentionally avoids reporting child-process RSS as if it were host-process memory.

docs/architecture/README.md

@@ -11,7 +11,7 @@ This doc set is for two audiences:
 
 - Start here for the package map, trust model, and overall flow.
 - Read [execbox-core.md](./execbox-core.md) for provider resolution, execution contracts, and error handling.
-- Read [execbox-executors.md](./execbox-executors.md) for QuickJS, process, worker-thread, and `isolated-vm` trade-offs.
+- Read [execbox-executors.md](./execbox-executors.md) for QuickJS host modes, remote execution, and `isolated-vm` trade-offs.
 - Read [execbox-mcp-and-protocol.md](./execbox-mcp-and-protocol.md) for MCP wrapping and where `execbox-protocol` fits.
 - Read [execbox-remote-workflow.md](./execbox-remote-workflow.md) for the end-to-end remote execution control flow.
 - Read [execbox-protocol-reference.md](./execbox-protocol-reference.md) for the protocol message catalog and session rules.
@@ -23,39 +23,30 @@ This doc set is for two audiences:
 flowchart LR
     APP["Host application"]
     CORE["@execbox/core<br/>provider resolution + runner semantics + MCP adapters"]
-    QJS["@execbox/quickjs<br/>in-process QuickJS executor + reusable runner"]
+    QJS["@execbox/quickjs<br/>QuickJS executor + reusable runner"]
     REM["@execbox/remote<br/>transport-backed remote executor"]
-    PROC["@execbox/process<br/>child-process QuickJS executor"]
     IVM["@execbox/isolated-vm<br/>in-process isolated-vm executor + reusable runner"]
     PROTO["@execbox/protocol<br/>transport messages + shared host session"]
-    WORKER["@execbox/worker<br/>worker-thread QuickJS executor"]
     MCP["MCP sources and wrapped servers"]
 
     APP --> CORE
     APP --> QJS
     APP --> REM
-    APP --> PROC
     APP --> IVM
-    APP --> WORKER
     CORE --> MCP
+    QJS --> PROTO
     REM --> PROTO
-    PROC --> PROTO
-    WORKER --> PROTO
-    PROC --> QJS
-    WORKER --> QJS
 ```
 
 ### Package Roles
 
-| Package                | Role                                                                                                         |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `@execbox/core`        | Core types, provider resolution, shared runner semantics, and MCP adapters                                   |
-| `@execbox/quickjs`     | Default executor backend using a fresh QuickJS runtime per execution and a reusable QuickJS runner           |
-| `@execbox/remote`      | Transport-backed executor that reuses the QuickJS protocol endpoint across an app-defined boundary           |
-| `@execbox/process`     | Child-process executor that runs the QuickJS session behind Node IPC with pooled shells by default           |
-| `@execbox/isolated-vm` | Alternate executor backend using a fresh `isolated-vm` context and a reusable isolated-vm runner             |
-| `@execbox/protocol`    | Transport-safe execution messages, shared host sessions, and reusable resource pools                         |
-| `@execbox/worker`      | Worker-thread executor that runs the QuickJS session behind a message boundary with pooled shells by default |
+| Package                | Role                                                                                                                         |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `@execbox/core`        | Core types, provider resolution, shared runner semantics, and MCP adapters                                                   |
+| `@execbox/quickjs`     | Default QuickJS executor package with inline, worker-hosted, and process-hosted modes plus a reusable runner                 |
+| `@execbox/remote`      | Transport-backed executor that reuses the QuickJS protocol endpoint across an app-defined boundary                           |
+| `@execbox/isolated-vm` | Alternate executor backend using a fresh `isolated-vm` context and a reusable isolated-vm runner                             |
+| `@execbox/protocol`    | Transport-safe execution messages, shared host sessions, and reusable resource pools for hosted QuickJS and remote execution |
 
 ## End-to-End Execution Model
 
@@ -110,4 +101,4 @@ Key implications:
 
 ## Architecture In One Paragraph
 
-`@execbox/core` owns the stable execution contract, provider resolution, shared runner semantics, and MCP adapters. `@execbox/quickjs` and `@execbox/isolated-vm` each expose a runtime-specific reusable runner. `@execbox/process`, `@execbox/worker`, and `@execbox/remote` are transport adapters around the shared QuickJS protocol endpoint, while `@execbox/protocol` owns the transport boundary: message shapes, shared host sessions, and reusable resource pools for transport-backed execution.
+`@execbox/core` owns the stable execution contract, provider resolution, shared runner semantics, and MCP adapters. `@execbox/quickjs` and `@execbox/isolated-vm` each expose a runtime-specific reusable runner. Hosted `@execbox/quickjs` modes and `@execbox/remote` sit on top of `@execbox/protocol`, which owns the transport boundary: message shapes, shared host sessions, and reusable resource pools for transport-backed execution.