Codemode Package
Overview
Path routing coverage: this document owns packages/codemode/**. Route changes under that glob here, including the runtime, public entrypoints, examples, tests, package metadata, and build/test configuration for @earendil-works/pi-codemode.
packages/codemode publishes @earendil-works/pi-codemode, a standalone QuickJS/WASI sandbox for running model-written JavaScript where the only host capability is calling injected tools. packages/…/package.json exports the main Node/Bun entry (src/index.ts), lightweight subentries for declarations/source/portable/cloudflare, and the worker entry (src/…/worker.ts); it builds src/…/*.ts to dist via packages/…/tsconfig.build.json, with src/cloudflare-modules.d.ts supplying local ambient declarations for Wrangler-only imports.
The public API fans out from packages/…/index.ts. It re-exports the worker-backed CodemodeSandbox, the shared CodemodeSandboxBase, the portable InlineCodemodeSandbox and RemoteCodemodeSandbox, the parseCodemodeSource() source directive parser, JSON-Schema-to-TypeScript declaration rendering helpers, output/store limits, toCodemodeIdentifier(), and loadQuickJSWasm(). packages/…/portable.ts intentionally omits Node built-ins and exports only the base/inline/remote/runtime types needed by Cloudflare Workers or browser-like hosts. packages/…/cloudflare.ts adds Wrangler-specific pieces: a compiled quickjs-wasi/quickjs.wasm import, createInlineCodemodeSandbox(), and CodemodeSandboxDurableObject, the remote Durable Object server.
All sandbox variants share the same host-side execution engine in packages/…/execution.ts. CodemodeSandboxBase stores registered tools/globals, default timeout and memory limit, and in-flight executions. execute(code, options) snapshots the current tool table and store, starts a fresh VM through a supplied launcher, records text/image output and tool calls, runs host tools with per-call abort signals, reports script failures as { ok: false }, and aborts pending calls on timeout, caller abort, script completion, or close(). start(code, options) is the deterministic host-controlled mode: the VM declares its tools/globals from CodemodeRunOptions, sends every call to onCall, and the host resumes it with run.deliver(seq, now, id, outcome) so durable callers can replay the same script after a restart.
The VM boundary is defined by packages/…/protocol.ts and implemented in packages/…/vm.ts plus packages/…/prelude-source.ts. VmStartData carries only plain data: code, tools, globals, serialized store, memory limit, and optional deterministic seed/time. startVm() creates one QuickJS instance from a compiled wasm module, evaluates the prelude, wraps user code as an async function body, drains promise jobs, polls interrupts between job batches, and posts only protocol messages (call, output, done, crash, plus deterministic started/idle). The prelude freezes built-ins before user code runs, exposes tools, ALL_TOOLS, text, image, exit, console, store, load, and configured globals, validates image blocks/data URLs, enforces output and store size limits, serializes tool arguments/results through JSON, and detects a stalled script that is awaiting a promise no tool or timer can settle.
There are three VM launchers. packages/…/host.ts implements CodemodeSandbox for Node and Bun by loading QuickJS with loadQuickJSWasm() (packages/…/wasm.ts) and starting packages/…/worker.ts in a fresh worker thread per execution. The worker receives the compiled wasm module and a SharedArrayBuffer interrupt flag, runs startVm(), and relays host result messages back into the VM. host.ts also owns worker admission/lifetime hooks (acquireWorker, onWorkerStarted) and treats Node --watch dependency reports on the worker channel as noise. packages/…/inline.ts implements InlineCodemodeSandbox, running QuickJS on the calling thread with an interrupt poll budget because host timers cannot fire while synchronous QuickJS code is computing. packages/…/remote.ts implements RemoteCodemodeSandbox and serveCodemodeRemote(): tools and call records stay in the caller, while the VM runs in another isolate via an exchange callback, batching output and stopping the remote when the caller aborts or times out.
The script-visible API and types are declared in packages/…/types.ts. Tools receive JSON-round-tripped arguments and an abort signal, and results must be JSON-serializable. Tool names are callable both by original bracket name and normalized identifier from packages/…/identifier.ts; globals must be valid identifiers or one-level namespaces and are not recorded in result.calls. CodemodeResult keeps output on failures, but only successful runs include storeWrites.
packages/…/source.ts parses the optional first-line // @options: directive used by codemode tool inputs. It returns code with the directive line replaced by a blank line to preserve stack line numbers, supports only max_output_tokens and timeout_ms, and rejects empty input, malformed/unknown options, an options-only script, or an options directive anywhere except line 1. The sandbox does not apply these parsed options itself; callers decide how to map them to output budgets or timeoutMs.
packages/…/declarations.ts renders TypeScript declarations and samples for script authors from tool/global metadata. schemaToType() handles primitive/object/array/tuple/union/allOf/local $ref JSON Schemas, sorts object properties, emits comment tags for constraints that TypeScript cannot express, caps runaway reference expansion and long rendered types, and returns unknown for remote, recursive, missing, or malformed refs. These declarations are used to present tool signatures to models without giving them host capabilities.
Cloudflare support is split so agent sessions do not block on QuickJS. packages/…/index.ts deploys only CodemodeSandboxDurableObject from the /cloudflare entry, with packages/…/wrangler.jsonc disabling public routes and setting CPU limits. packages/…/index.ts keeps session state and tools in a Session Durable Object, imports RemoteCodemodeSandbox from /portable, and binds the sandbox Durable Object with script_name in packages/…/wrangler.jsonc; this keeps the QuickJS wasm and blocking execution in the separately deployed sandbox Worker.
Tests under packages/codemode/test are the behavioral spec. sandbox.test.ts runs most execution behavior against worker, inline, and in-process remote backends; it covers output, images, tools, globals, store/load, timeouts/aborts, output limits, sandbox escape attempts, frozen built-ins, and worker host errors. deterministic.test.ts covers start() replay behavior, fingerprints, virtual clock/randomness, ordered result delivery, and remote transport reordering. portable.test.ts focuses on inline interrupt budgets and remote exchange semantics. worker-lifetime.test.ts covers admission control, worker exit accounting, and prompt cancellation/close behavior. source.test.ts and declarations.test.ts pin the source directive and schema/declaration rendering contracts.
Coupling
- If the worker/VM protocol changes, update packages/…/protocol.ts, packages/…/execution.ts, packages/…/vm.ts, packages/…/worker.ts, and packages/…/remote.ts together. The host validates incoming messages and treats malformed bridge payloads as sandbox failures; remote and worker transports pass the same message shapes with different delivery mechanics.
- If script-visible globals or helper behavior change, update both packages/…/prelude-source.ts and the declaration/source docs exposed through packages/…/types.ts, packages/…/declarations.ts, and packages/…/README.md. The prelude is the runtime source of truth, but callers and models rely on rendered declarations and README examples to call the same API.
- If deterministic execution changes anything a script can observe, update the fingerprint inputs in packages/…/vm.ts (including
DETERMINISTIC_VERSIONwhen the existing version/hash/limits do not capture the change) and the pinned expectations in packages/…/deterministic.test.ts. Replayed durable runs depend on refusing a VM whose behavior differs silently. - If Cloudflare packaging changes, verify the split among packages/…/portable.ts, packages/…/cloudflare.ts, and
packages/codemode/examples/cloudflare/**. Importing/cloudflarein an agent Worker bundles QuickJS there, while importing/portablekeeps wasm in the sandbox Worker; thescript_namebinding in examples/…/wrangler.jsonc is what prevents session-thread blocking. - If output, image, or store limits change, update constants and enforcement in packages/…/prelude-source.ts, exported constants in packages/…/index.ts and packages/…/portable.ts, README limit prose, and tests in packages/…/sandbox.test.ts. The host buffers all output until completion, so mismatched limits can become memory exhaustion or provider-rejected image payloads.
- If bundled-host worker loading changes, check packages/…/package.json exports, packages/…/host.ts, packages/…/worker.ts, and the README bundled Node/Bun section. The default worker URL only works when the package's worker file exists next to the module; bundled hosts must pass a separate worker entry and often a custom wasm path.
Risks
- packages/…/host.ts has fragile worker termination semantics on Bun: aborts, timeouts, and
close()request termination and unref the worker but do not wait for actual exit. The changelog records fix #10748 and packages/…/worker-lifetime.test.ts pins admission and exit accounting; if capacity is released when a result settles instead of when the worker exits, hosts can oversubscribe workers while a non-interruptible built-in keeps running. - packages/…/prelude-source.ts, packages/…/execution.ts, and packages/…/vm.ts are sensitive to script mutation of built-ins and bridge payloads. The changelog records #10444 after scripts that patched prototypes crashed the host or left executions unsettled; if lockdown or bridge validation is weakened, model-written code can corrupt JSON serialization and turn one script into a sandbox-level failure or a hung host result.
- packages/…/remote.ts, packages/…/inline.ts, and packages/…/cloudflare.ts rely on interrupt budgets rather than wall-clock timers while QuickJS computes on the calling thread. If the budget is raised above Cloudflare CPU limits or not capped by
CodemodeSandboxDurableObject, a tight loop can reset the Durable Object instead of returning a codemode timeout. - packages/…/declarations.ts processes schemas from external tools/MCP servers. Recent fixes in packages/…/CHANGELOG.md mention malformed local
$refpercent escapes (#11803) and high-churn declaration changes (#10707); if$refresolution or max-size fallbacks regress, one bad tool schema can make all declaration rendering fail for a caller. - packages/…/prelude-source.ts image validation protects downstream model providers from rejected requests. The changelog records #10215 after malformed base64 or unsupported image types were accepted; if detection starts trusting declared MIME types or remote URLs, persisted image outputs can poison later turns or fail provider submission.