zapcode AGENTS.md

AGENTS.md

Standard agent instructions for the zapcode project. Read this before writing any code.

---

What this project is

Zapcode is a minimal, secure TypeScript subset interpreter written in Rust, designed specifically to execute code written by AI agents. It is the TypeScript equivalent of pydantic/monty.

The core thesis: LLMs produce faster, cheaper, more reliable results when they write code instead of making sequential tool calls. Zapcode makes that possible for TypeScript/JavaScript stacks without containers, sandbox services, or running untrusted code directly on the host.

What Zapcode can do:

• Execute a safe subset of TypeScript — enough for an agent to express what it wants to do
• Block all host access by default: filesystem, env vars, network, require, import
• Expose host functions to the sandbox — only functions you explicitly register
• Snapshot VM state to bytes at external function call boundaries — resume later in any process
• Start in microseconds (~2 µs for simple expressions)
• Be called from Rust, TypeScript/JavaScript (napi-rs), Python (PyO3), or WebAssembly
• Enforce resource limits: memory, execution time, stack depth, allocation count

What Zapcode cannot do (by design):

• Access the standard library beyond a safe subset (console, JSON, Math, Array, Object, Promise)
• Use import / require / dynamic imports
• Access process, globalThis, eval, Function(), setTimeout/setInterval
• Use proxies, WeakMap/WeakRef, Symbol, or with statements
• Execute regular expressions (parsed but execution is a no-op)
• Use var declarations (use let/const)

---

Repository layout

zapcode/
├── crates/
│   ├── zapcode-core/       # Parser, IR, bytecode compiler, VM, snapshot
│   │   ├── src/
│   │   │   ├── parser/      # oxc_parser integration — AST → ZapcodeIR
│   │   │   │   ├── mod.rs   # AST walker (oxc → IR)
│   │   │   │   └── ir.rs    # IR type definitions
│   │   │   ├── compiler/    # ZapcodeIR → Bytecode
│   │   │   │   ├── mod.rs   # Compiler logic
│   │   │   │   └── instruction.rs  # Instruction enum (~55 opcodes)
│   │   │   ├── vm/          # Stack-based bytecode executor
│   │   │   │   ├── mod.rs   # VM main loop, dispatch, ZapcodeRun entry point
│   │   │   │   └── builtins.rs  # Built-in functions (console, Math, JSON, etc.)
│   │   │   ├── value.rs     # Value enum — runtime type system
│   │   │   ├── snapshot.rs  # Serialize/deserialize mid-execution VM state
│   │   │   ├── sandbox.rs   # Resource limits and tracking
│   │   │   ├── error.rs     # ZapcodeError — all error types
│   │   │   └── lib.rs       # Public API re-exports
│   │   ├── tests/           # 14 test files, 214+ tests
│   │   └── benches/         # divan benchmarks
│   ├── zapcode-js/         # napi-rs bindings → @unchartedfr/zapcode npm package
│   ├── zapcode-py/         # PyO3 bindings → zapcode pip package
│   └── zapcode-wasm/       # wasm-bindgen target for browser/edge use
├── AGENTS.md                # This file
├── CLAUDE.md                # Claude Code-specific guidance (references this file)
├── Cargo.toml               # Workspace root
└── README.md                # User-facing docs with benchmarks