The Execution Engine is the heart of the Executor system, responsible for taking raw TypeScript code from a model, executing it within a secure sandbox, and managing the lifecycle of tool calls that require human intervention (elicitation). It abstracts the underlying sandboxed runtimes—QuickJS, Cloudflare Workers, or Deno—behind a unified ExecutionEngine interface.
The execution pipeline manages the transition from a string of code to a structured result. It handles TypeScript transpilation (via sucrase), tool address resolution, and the pause/resume state machine.
The ExecutionEngine class is the primary entry point for running code. It coordinates between the Executor (which holds tool connections) and a CodeExecutor (the specific sandbox implementation) packages/core/execution/src/engine.ts29-33
Key Functions:
execute: A standard execution that runs to completion or fails packages/core/execution/src/engine.ts335-341executeWithPause: A specialized execution that supports the "Elicitation" lifecycle. If a tool requires user approval or input, the execution is suspended, and a PausedExecution object is returned packages/core/execution/src/engine.ts358-372resume: Resumes a previously paused execution using a ResumeResponse containing the user's action (accept/decline) and any requested data packages/core/execution/src/engine.ts446-455Inside the sandbox, the user's code calls tools via a global tools proxy. These calls are dispatched back to the host via the SandboxToolInvoker packages/core/execution/src/tool-invoker.ts19-20
The makeExecutorToolInvoker function bridges the sandbox to the Executor instance. It handles:
github.getRepo to full tool addresses like tools.github.org.main.getRepo packages/core/execution/src/tool-invoker.ts59-65{ ok: true, data: ... } envelope or capturing errors packages/core/execution/src/tool-invoker.ts33-34Elicitation occurs when a tool requires interaction (e.g., OAuth flow, manual confirmation).
ElicitationRequest, the ExecutionEngine captures the current Effect fiber and stores it in a Deferred value packages/core/execution/src/engine.ts50-54PausedExecution is returned to the caller, containing the elicitationContext (the message for the user and any requested JSON schema) packages/core/execution/src/engine.ts39-42engine.resume(id, response). This completes the Deferred value, allowing the suspended fiber to continue execution as if the tool call had just returned packages/core/execution/src/engine.ts446-470Title: Execution Data Flow
Sources: packages/core/execution/src/engine.ts358-372 packages/core/execution/src/tool-invoker.ts181-187 packages/kernel/runtime-dynamic-worker/src/executor.ts5-9
Executor supports multiple runtimes, each implementing the CodeExecutor interface.
@executor-js/runtime-quickjs)A lightweight, WASM-based sandbox used primarily in the Desktop and CLI hosts. It provides high isolation with low overhead.
quickjs-emscripten to evaluate code packages/kernel/runtime-quickjs/src/index.ts12-19stripTypeScript to remove types before passing code to the QuickJS engine packages/kernel/runtime-quickjs/src/index.ts124-125__executor_invokeTool and __executor_log into the global scope packages/kernel/runtime-quickjs/src/index.ts128-131@executor-js/runtime-dynamic-worker)Used in the Cloud host (Cloudflare Workers). It runs code in an ephemeral, isolated Worker.
RpcTarget) to communicate between the host and the dynamic sandbox packages/kernel/runtime-dynamic-worker/src/executor.ts5-9executor.js) containing the user's code and the tool-calling logic packages/kernel/runtime-dynamic-worker/src/executor.ts90-91compilation errors (syntax), runtime errors (CPU/Memory limits), and internal defects packages/kernel/runtime-dynamic-worker/src/executor.ts222-225@executor-js/runtime-deno-subprocess)Used when local filesystem access or native Deno features are required. It spawns a Deno subprocess with restricted permissions.
The system categorizes errors to provide actionable feedback to models while hiding internal infrastructure details.
| Error Class | Origin | Visibility | Description |
|---|---|---|---|
CodeCompilationError | Host (Sucrase) | Public | Syntax errors caught before execution packages/kernel/core/src/effect-errors.ts34-38 |
SandboxRuntimeError | Runtime | Public | Resource limits (CPU/Memory) or non-serializable returns packages/kernel/core/src/effect-errors.ts54-58 |
ExecutionToolError | Plugin/Invoker | Public/Opaque | Errors during tool execution. Specifically tagged messages are passed through packages/core/execution/src/errors.ts1-5 |
CodeExecutionError | Infrastructure | Opaque | Unexpected sandbox crashes or loader failures packages/kernel/core/src/effect-errors.ts17-21 |
Title: Error Classification Mapping
Sources: packages/kernel/core/src/effect-errors.ts17-58 packages/kernel/runtime-dynamic-worker/src/executor.ts184-207
To help the model use tools effectively, the engine dynamically builds the execute tool description.
- github, - slack) packages/core/execution/src/description.ts77-82skills({ name: "execute" }) tool, which provides the full documentation on how to write code for the sandbox packages/core/execution/src/description.ts32Sources:
Refresh this wiki