Introducing a new way to review your PRs.

Read the announcement

earendil-works / pi

AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI

View on GitHub

13 documents · Updated Nov 19, 2026

docs / codemode

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

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 $ref percent escapes (#11803) and high-churn declaration changes (#10707); if $ref resolution 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.