executor 1.1.8 → 1.1.10-beta.5

package/README.md

@@ -4,6 +4,10 @@
 
 It gives an agent a TypeScript runtime, a discoverable tool catalog, and a single local place to connect external systems such as MCP servers, OpenAPI APIs, and GraphQL APIs. Instead of pasting large MCP manifests into every chat or giving an agent broad shell access, you run code inside `executor` and let it call typed `tools.*` functions.
 
+## Community
+
+Join the Discord community: https://discord.gg/eF29HBHwM6
+
 At runtime, `executor` behaves like one local product:
 
 - a CLI for starting the runtime and executing code
@@ -11,7 +15,12 @@ At runtime, `executor` behaves like one local product:
 - a local web UI for connecting sources, inspecting tools, and managing secrets
 - an MCP endpoint for hosts that want to drive `executor` through MCP
 
-The current codebase is the v3 rewrite. Older experiments live in `legacy/` and `legacy2/`, but the active architecture is the one in `apps/` and `packages/`.
+The current codebase lives in `apps/` and `packages/`. Older experiments stay in `legacy/` and `legacy2/`.
+
+## Attribution
+
+- [Crystian](https://www.linkedin.com/in/crystian/) provided the npm package name `executor`.
+- The `codemode` concept in this project is inspired by Cloudflare's [Code Mode announcement](https://blog.cloudflare.com/code-mode/).
 
 ## Why this exists
 
@@ -105,12 +114,22 @@ For each source you can:
 
 ## Quick start
 
-If you are working from this repository, the easiest path is:
+If you want to use this a package distribution, install it via npm:
+
+```bash
+npm install -g executor
+executor up
+```
+
+Then either tell your agent to use the CLI or to open the web UI and copy the MCP CLI install command.
+
+Then you can run the CLI as `executor`.
+
+If you are working from this repository locally, the easiest path is:
 
 ```bash
 bun install
-bun run executor doctor --json
-bun run executor up
+bun dev
 ```
 
 That starts the local runtime. The default base URL is:
@@ -194,7 +213,8 @@ return await tools.executor.sources.add({
 return await tools.executor.sources.add({
   kind: "openapi",
   endpoint: "https://api.github.com",
-  specUrl: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
+  specUrl:
+    "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
   name: "GitHub",
   namespace: "github",
 });
@@ -208,7 +228,7 @@ At a high level, every execution follows the same loop:
 
 1. `executor` resolves the current local installation and workspace.
 2. It builds a tool catalog from built-in tools plus all connected workspace sources.
-3. It runs your TypeScript inside the in-process execution runtime.
+3. It runs your TypeScript inside the QuickJS sandbox runtime by default.
 4. Tool calls are dispatched through `executor` rather than directly from your code.
 5. If a tool needs interaction, the run pauses and records a pending interaction.
 6. Once the interaction is resolved, the execution continues and eventually completes or fails.
@@ -260,18 +280,16 @@ The server also maintains local PID and log files in its runtime directory.
 
 ## Persistence and data
 
-`executor` persists the local control plane to SQL.
-
-By default it uses embedded PGlite for a local install, which keeps the product self-contained. If you provide a Postgres URL, the persistence layer can target real Postgres instead.
+`executor` persists the local control plane to local files.
 
 Persisted concepts include:
 
-- the local installation record
-- organizations and workspaces provisioned for that install
+- local installation identity
 - connected sources
 - indexed tool artifacts and related metadata
 - credentials and secret material bindings
 - source auth sessions
+- execution and interaction state
 - executions and execution interactions
 - policies
 
@@ -299,10 +317,22 @@ If you are exploring the repo, these are the directories that matter most:
 - `apps/web`: local React web UI
 - `packages/server`: local HTTP server that serves API, MCP, and UI
 - `packages/control-plane`: source management, secrets, persistence, execution, and inspection
-- `packages/runtime-local-inproc`: in-process TypeScript execution runtime
+- `packages/runtime-quickjs`: default QuickJS sandbox runtime for TypeScript execution
+- `packages/runtime-ses`: optional SES sandbox runtime for TypeScript execution
 - `packages/executor-mcp`: MCP bridge for `execute` and `resume`
 - `packages/codemode-*`: core tool abstractions plus MCP and OpenAPI adapters
 
+## Releasing
+
+- `bun run release:beta` is the simplest beta flow. It bumps `apps/executor/package.json`, runs the local publish dry-run, commits, pushes the branch, pushes the matching tag, and lets GitHub Actions publish it.
+- `bun run release:beta:dry-run` prints the next beta version and the exact git actions without changing anything.
+- `bun run --cwd apps/executor release:publish` is the only supported publish command.
+- One-time npm setup: either configure npm trusted publishing for `RhysSullivan/executor` with the workflow file `.github/workflows/publish-executor-package.yml`, or add a GitHub Actions secret named `NPM_TOKEN` that can publish the `executor` package.
+- Stable releases use a normal semver like `1.2.3` and publish to npm under `latest`.
+- Beta releases use a prerelease semver like `1.3.0-beta.1` and publish to npm under `beta`.
+- Push a matching git tag such as `v1.2.3` or `v1.3.0-beta.1` to trigger `.github/workflows/publish-executor-package.yml`.
+- To build and pack the publish artifact locally without publishing, run `bun run --cwd apps/executor release:publish:dry-run`.
+
 ## Project status
 
 This repository is explicitly on its third major architecture iteration.