refactor: merge protocol into @execbox/core/protocol (#20)

Author: aallam

.changeset/modern-bears-dance.md

@@ -0,0 +1,7 @@
+---
+"@execbox/core": minor
+"@execbox/quickjs": minor
+"@execbox/remote": minor
+---
+
+Move the standalone protocol helpers into the new `@execbox/core/protocol` entrypoint and remove the separate `@execbox/protocol` package. Transport-backed integrations should now import protocol messages, host-session helpers, and resource-pool utilities from `@execbox/core/protocol`.

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`, and `@execbox/isolated-vm`.
+- The workspace currently contains `@execbox/core`, `@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
@@ -32,7 +32,7 @@
 
 - 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/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/core/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/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/core/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

@@ -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/isolated-vm`, or `@execbox/isolated-vm/runner`: run `npm run api:check`
+- Public API changes to `@execbox/core`, `@execbox/core/mcp`, `@execbox/core/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,21 +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-5-111827?style=flat-square)](#package-map)
+[![Packages](https://img.shields.io/badge/packages-4-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: 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)       | 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/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                              |
+| 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, MCP adapters, and the `@execbox/core/protocol` transport subpath |
+| [`@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/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
 

docs/architecture/README.md

@@ -12,7 +12,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 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-mcp-and-protocol.md](./execbox-mcp-and-protocol.md) for MCP wrapping and where `@execbox/core/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.
 - Read [execbox-runner-specification.md](./execbox-runner-specification.md) for the normative runner specification for non-TypeScript runners.
@@ -26,7 +26,7 @@ flowchart LR
     QJS["@execbox/quickjs<br/>QuickJS executor + reusable runner"]
     REM["@execbox/remote<br/>transport-backed remote executor"]
     IVM["@execbox/isolated-vm<br/>in-process isolated-vm executor + reusable runner"]
-    PROTO["@execbox/protocol<br/>transport messages + shared host session"]
+    PROTO["@execbox/core/protocol<br/>transport messages + shared host session"]
     MCP["MCP sources and wrapped servers"]
 
     APP --> CORE
@@ -40,13 +40,12 @@ flowchart LR
 
 ### Package Roles
 
-| 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 |
+| Package                | Role                                                                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@execbox/core`        | Core types, provider resolution, shared runner semantics, MCP adapters, and the `@execbox/core/protocol` transport subpath |
+| `@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                           |
 
 ## End-to-End Execution Model
 
@@ -101,4 +100,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. 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.
+`@execbox/core` owns the stable execution contract, provider resolution, shared runner semantics, MCP adapters, and the `@execbox/core/protocol` transport surface. `@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/core/protocol`, which owns the transport boundary: message shapes, shared host sessions, and reusable resource pools for transport-backed execution.

docs/architecture/execbox-core.md

@@ -106,7 +106,7 @@ This seam is what lets execbox share semantics across:
 
 - the in-process QuickJS executor
 - the in-process `isolated-vm` executor
-- transport-backed executors that reuse the same manifest and dispatcher model through `@execbox/protocol`
+- transport-backed executors that reuse the same manifest and dispatcher model through `@execbox/core/protocol`
 
 without forcing every runtime through the same transport implementation.
 
@@ -199,7 +199,7 @@ The core package does not own QuickJS, `isolated-vm`, worker threads, or transpo
 The consequence is deliberate separation between:
 
 - core execution and runner semantics in `@execbox/core`
-- transport/session mechanics in `@execbox/protocol`
+- transport/session mechanics in `@execbox/core/protocol`
 - runtime-specific bridge code in executor packages
 
 That split keeps the public contract stable without forcing every backend through identical plumbing.

docs/architecture/execbox-executors.md

@@ -26,7 +26,7 @@ flowchart LR
     IVMRT["isolated-vm context"]
     THREAD["Worker thread"]
     RUNNER["core runner semantics"]
-    PROTO["execbox-protocol<br/>messages + host session"]
+    PROTO["@execbox/core/protocol<br/>messages + host session"]
     WQJSRT["QuickJS runtime in worker"]
     PQJSRT["QuickJS runtime in child process"]
 
@@ -143,7 +143,7 @@ Every `execute()` call still creates a fresh QuickJS runtime/context, reinjects
 
 Pooling is implemented at the host-shell layer, not at the QuickJS runtime layer.
 
-- `@execbox/protocol` exposes a small bounded async `createResourcePool()` helper that owns reusable shells, idle eviction, and `prewarm()` / `dispose()` support.
+- `@execbox/core/protocol` exposes a small bounded async `createResourcePool()` helper that owns reusable shells, idle eviction, and `prewarm()` / `dispose()` support.
 - Hosted `QuickJsExecutor` pools either `ChildProcess` or `Worker` shells. Each shell owns one long-lived transport wrapper plus one attached QuickJS protocol endpoint.
 - The child/worker entrypoint only attaches `attachQuickJsProtocolEndpoint(...)` once. That endpoint accepts one active `execute` message at a time and starts a fresh `runQuickJsSession()` for each message.
 - Concurrency therefore comes from pool size, not from multiplexing several executions through one shell.

docs/architecture/execbox-mcp-and-protocol.md

@@ -3,7 +3,7 @@
 This page covers two related but separate parts of the execbox architecture:
 
 - MCP adapters in `@execbox/core`
-- transport-safe execution plumbing in `@execbox/protocol`
+- transport-safe execution plumbing in `@execbox/core/protocol`
 
 Use this page as the overview. For the remote execution control flow, read [execbox-remote-workflow.md](./execbox-remote-workflow.md). For the message-level protocol contract, read [execbox-protocol-reference.md](./execbox-protocol-reference.md). For the normative runner specification, read [execbox-runner-specification.md](./execbox-runner-specification.md).
 
@@ -39,7 +39,7 @@ flowchart LR
 
 ## Protocol Responsibilities
 
-`@execbox/protocol` is not a sandbox runtime. It provides the transport-safe layer that lets a trusted host and a runtime exchange execution messages without sharing host closures.
+`@execbox/core/protocol` is not a sandbox runtime. It provides the transport-safe layer that lets a trusted host and a runtime exchange execution messages without sharing host closures.
 
 It owns:
 
@@ -51,13 +51,13 @@ It owns:
 The architecture split is:
 
 - `@execbox/core` owns provider resolution, manifest extraction, and host-side tool dispatch semantics
-- `@execbox/protocol` owns wire messages, host-session lifecycle, and host-side shell pooling utilities around those semantics
+- `@execbox/core/protocol` owns wire messages, host-session lifecycle, and host-side shell pooling utilities around those semantics
 
 ## How The Packages Fit Together
 
 - `QuickJsExecutor` uses the shared runner semantics from `@execbox/core` directly.
 - `IsolatedVmExecutor` uses the same core runner semantics, but keeps a direct `isolated-vm` bridge instead of transport messages.
-- `QuickJsExecutor` in `host: "process"` and `host: "worker"` modes uses the shared host session from `@execbox/protocol` plus the shared QuickJS protocol endpoint inside the child or worker shell.
+- `QuickJsExecutor` in `host: "process"` and `host: "worker"` modes uses the shared host session from `@execbox/core/protocol` plus the shared QuickJS protocol endpoint inside the child or worker shell.
 - `RemoteExecutor` uses that same host session across an app-owned transport boundary.
 - Pooled process and worker execution reuse only the outer host shell. Each `execute()` call still starts a fresh QuickJS runtime through the shared protocol endpoint.
 
@@ -73,7 +73,7 @@ flowchart TB
     end
 
     subgraph TransportBacked["Transport-backed executors"]
-        PROTO["@execbox/protocol<br/>messages + host session + resource pool"]
+        PROTO["@execbox/core/protocol<br/>messages + host session + resource pool"]
         HOSTED["QuickJsExecutor host modes"]
         REM["RemoteExecutor"]
         ENDPOINT["QuickJS protocol endpoint"]

docs/architecture/execbox-protocol-reference.md

@@ -1,6 +1,6 @@
-# Execbox Protocol Reference
+# Execbox Core Protocol Reference
 
-This page is the message-level reference for `@execbox/protocol`.
+This page is the message-level reference for `@execbox/core/protocol`.
 
 It describes the wire shapes and session semantics used by transport-backed execbox runtimes such as hosted QuickJS and remote execution. It is grounded in the shipped implementation and should be read as a practical reference, not as a formal RFC.