zapcode-ai 1.0.0__tar.gz

zapcode_ai-1.0.0/.gitignore

@@ -0,0 +1,27 @@
+# Rust
+**/target
+**/*.rs.bk
+
+# Node.js
+node_modules/
+dist/
+package-lock.json
+
+# NAPI-RS build artifacts
+*.node
+crates/zapcode-js/npm/
+
+# Python
+__pycache__/
+*.pyc
+.python-version
+
+# Editor
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Secrets
+.env

zapcode_ai-1.0.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: zapcode-ai
+Version: 1.0.0
+Summary: AI SDK integration for Zapcode — let LLMs write and execute TypeScript safely
+Project-URL: Homepage, https://github.com/TheUncharted/zapcode
+Project-URL: Repository, https://github.com/TheUncharted/zapcode
+Project-URL: Issues, https://github.com/TheUncharted/zapcode/issues
+Project-URL: Documentation, https://github.com/TheUncharted/zapcode#readme
+Author: Uncharted
+License-Expression: MIT
+Keywords: agent,ai,interpreter,llm,mcp,sandbox,tool-use,typescript
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: zapcode
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.39.0; extra == 'anthropic'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'

zapcode_ai-1.0.0/README.md

@@ -0,0 +1,596 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Zapcode" width="160" />
+</p>
+<h1 align="center">Zapcode</h1>
+<p align="center"><strong>Run AI code. Safely. Instantly.</strong></p>
+<p align="center">A minimal, secure TypeScript interpreter written in Rust for use by AI agents</p>
+
+<p align="center">
+  <a href="https://github.com/TheUncharted/zapcode/actions"><img src="https://img.shields.io/github/actions/workflow/status/TheUncharted/zapcode/ci.yml?branch=master&label=CI" alt="CI"></a>
+  <a href="https://crates.io/crates/zapcode-core"><img src="https://img.shields.io/crates/v/zapcode-core" alt="crates.io"></a>
+  <a href="https://www.npmjs.com/package/@unchartedfr/zapcode"><img src="https://img.shields.io/npm/v/@unchartedfr/zapcode" alt="npm"></a>
+  <a href="https://pypi.org/project/zapcode/"><img src="https://img.shields.io/pypi/v/zapcode" alt="PyPI"></a>
+  <a href="https://github.com/TheUncharted/zapcode/blob/master/LICENSE"><img src="https://img.shields.io/github/license/TheUncharted/zapcode" alt="License"></a>
+</p>
+
+---
+
+> **Experimental** — Zapcode is under active development. APIs may change.
+
+## Why agents should write code
+
+AI agents are more capable when they **write code** instead of chaining tool calls. Code gives agents loops, conditionals, variables, and composition — things that tool chains simulate poorly.
+
+- [CodeMode](https://blog.cloudflare.com/codemode-ai-agent-coding) — Cloudflare on why agents should write code
+- [Programmatic Tool Calling](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/tool-use-examples#programmatic-tool-calling) — Anthropic's approach
+- [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-mcp) — Anthropic engineering
+- [Smol Agents](https://huggingface.co/docs/smolagents/en/index) — Hugging Face's code-first agents
+
+**But running AI-generated code is dangerous and slow.**
+
+Docker adds 200-500ms of cold-start latency and requires a container runtime. V8 isolates bring ~20MB of binary and millisecond startup. Neither supports snapshotting execution mid-function.
+
+Zapcode takes a different approach: a purpose-built TypeScript interpreter that starts in **2 microseconds**, enforces a security sandbox at the language level, and can snapshot execution state to bytes for later resumption — all in a single, embeddable library with zero dependencies on Node.js or V8.
+
+Inspired by [Monty](https://github.com/pydantic/monty), Pydantic's Python subset interpreter that takes the same approach for Python.
+
+## Alternatives
+
+| | Language completeness | Security | Startup | Snapshots | Setup |
+|---|---|---|---|---|---|
+| **Zapcode** | TypeScript subset | Language-level sandbox | **~2 µs** | Built-in, < 2 KB | `npm install` / `pip install` |
+| Docker + Node.js | Full Node.js | Container isolation | ~200-500 ms | No | Container runtime |
+| V8 Isolates | Full JS/TS | Isolate boundary | ~5-50 ms | No | V8 (~20 MB) |
+| Deno Deploy | Full TS | Isolate + permissions | ~10-50 ms | No | Cloud service |
+| QuickJS | Full ES2023 | Process isolation | ~1-5 ms | No | C library |
+| WASI/Wasmer | Depends on guest | Wasm sandbox | ~1-10 ms | Possible | Wasm runtime |
+
+### Why not Docker?
+
+Docker provides strong isolation but adds hundreds of milliseconds of cold-start latency, requires a container runtime, and doesn't support snapshotting execution state mid-function. For AI agent loops that execute thousands of small code snippets, the overhead dominates.
+
+### Why not V8?
+
+V8 is the gold standard for JavaScript execution. But it brings ~20 MB of binary size, millisecond startup times, and a vast API surface that must be carefully restricted for sandboxing. If you need full ECMAScript compliance, use V8. If you need microsecond startup, byte-sized snapshots, and a security model where "blocked by default" is the foundation rather than an afterthought, use Zapcode.
+
+## Benchmarks
+
+All benchmarks run the full pipeline: parse → compile → execute. No caching, no warm-up.
+
+| Benchmark | Zapcode | Docker + Node.js | V8 Isolate |
+|---|---|---|---|
+| Simple expression (`1 + 2 * 3`) | **2.1 µs** | ~200-500 ms | ~5-50 ms |
+| Variable arithmetic | **2.8 µs** | — | — |
+| String concatenation | **2.6 µs** | — | — |
+| Template literal | **2.9 µs** | — | — |
+| Array creation | **2.4 µs** | — | — |
+| Object creation | **5.2 µs** | — | — |
+| Function call | **4.6 µs** | — | — |
+| Loop (100 iterations) | **77.8 µs** | — | — |
+| Fibonacci (n=10, 177 calls) | **138.4 µs** | — | — |
+| Snapshot size (typical agent) | **< 2 KB** | N/A | N/A |
+| Memory per execution | **~10 KB** | ~50+ MB | ~20+ MB |
+| Cold start | **~2 µs** | ~200-500 ms | ~5-50 ms |
+
+No background thread, no GC, no runtime — CPU usage is exactly proportional to the instructions executed.
+
+```bash
+cargo bench   # run benchmarks yourself
+```
+
+## Installation
+
+**TypeScript / JavaScript**
+```bash
+npm install @unchartedfr/zapcode        # npm / yarn / pnpm / bun
+```
+
+**Python**
+```bash
+pip install zapcode                     # pip / uv
+```
+
+**Rust**
+```toml
+# Cargo.toml
+[dependencies]
+zapcode-core = "1.0.0"
+```
+
+**WebAssembly**
+```bash
+wasm-pack build crates/zapcode-wasm --target web
+```
+
+## Basic Usage
+
+### TypeScript / JavaScript
+
+```typescript
+import { Zapcode, ZapcodeSnapshotHandle } from '@unchartedfr/zapcode';
+
+// Simple expression
+const b = new Zapcode('1 + 2 * 3');
+console.log(b.run().output);  // 7
+
+// With inputs
+const greeter = new Zapcode(
+    '`Hello, ${name}! You are ${age} years old.`',
+    { inputs: ['name', 'age'] },
+);
+console.log(greeter.run({ name: 'Zapcode', age: 30 }).output);
+
+// Data processing
+const processor = new Zapcode(`
+    const items = [
+        { name: "Widget", price: 25.99, qty: 3 },
+        { name: "Gadget", price: 49.99, qty: 1 },
+    ];
+    const total = items.reduce((sum, i) => sum + i.price * i.qty, 0);
+    ({ total, names: items.map(i => i.name) })
+`);
+console.log(processor.run().output);
+// { total: 127.96, names: ["Widget", "Gadget"] }
+
+// External function (snapshot/resume)
+const app = new Zapcode(`const data = await fetch(url); data`, {
+    inputs: ['url'],
+    externalFunctions: ['fetch'],
+});
+const state = app.start({ url: 'https://api.example.com' });
+if (!state.completed) {
+    console.log(state.functionName);  // "fetch"
+    const snapshot = ZapcodeSnapshotHandle.load(state.snapshot);
+    const final_ = snapshot.resume({ status: 'ok' });
+    console.log(final_.output);  // { status: "ok" }
+}
+```
+
+See [`examples/typescript/basic.ts`](examples/typescript/basic.ts) for more.
+
+### Python
+
+```python
+from zapcode import Zapcode, ZapcodeSnapshot
+
+# Simple expression
+b = Zapcode("1 + 2 * 3")
+print(b.run()["output"])  # 7
+
+# With inputs
+b = Zapcode(
+    '`Hello, ${name}!`',
+    inputs=["name"],
+)
+print(b.run({"name": "Zapcode"})["output"])  # "Hello, Zapcode!"
+
+# External function (snapshot/resume)
+b = Zapcode(
+    "const w = await getWeather(city); `${city}: ${w.temp}°C`",
+    inputs=["city"],
+    external_functions=["getWeather"],
+)
+state = b.start({"city": "London"})
+if state.get("suspended"):
+    result = state["snapshot"].resume({"condition": "Cloudy", "temp": 12})
+    print(result["output"])  # "London: 12°C"
+
+# Snapshot persistence
+state = b.start({"city": "Tokyo"})
+if state.get("suspended"):
+    bytes_ = state["snapshot"].dump()          # serialize to bytes
+    restored = ZapcodeSnapshot.load(bytes_)    # load from bytes
+    result = restored.resume({"condition": "Clear", "temp": 26})
+```
+
+See [`examples/python/basic.py`](examples/python/basic.py) for more.
+
+<details>
+<summary><strong>Rust</strong></summary>
+
+```rust
+use zapcode_core::{ZapcodeRun, Value, ResourceLimits, VmState};
+
+// Simple expression
+let runner = ZapcodeRun::new(
+    "1 + 2 * 3".to_string(), vec![], vec![],
+    ResourceLimits::default(),
+)?;
+assert_eq!(runner.run_simple()?, Value::Int(7));
+
+// With inputs and external functions (snapshot/resume)
+let runner = ZapcodeRun::new(
+    r#"const weather = await getWeather(city);
+       `${city}: ${weather.condition}, ${weather.temp}°C`"#.to_string(),
+    vec!["city".to_string()],
+    vec!["getWeather".to_string()],
+    ResourceLimits::default(),
+)?;
+
+let state = runner.start(vec![
+    ("city".to_string(), Value::String("London".into())),
+])?;
+
+if let VmState::Suspended { snapshot, .. } = state {
+    let weather = Value::Object(indexmap::indexmap! {
+        "condition".into() => Value::String("Cloudy".into()),
+        "temp".into() => Value::Int(12),
+    });
+    let final_state = snapshot.resume(weather)?;
+    // VmState::Complete("London: Cloudy, 12°C")
+}
+```
+
+See [`examples/rust/basic.rs`](examples/rust/basic.rs) for more.
+</details>
+
+<details>
+<summary><strong>WebAssembly (browser)</strong></summary>
+
+```html
+<script type="module">
+import init, { Zapcode } from './zapcode-wasm/zapcode_wasm.js';
+
+await init();
+
+const b = new Zapcode(`
+    const items = [10, 20, 30];
+    items.map(x => x * 2).reduce((a, b) => a + b, 0)
+`);
+const result = b.run();
+console.log(result.output);  // 120
+</script>
+```
+
+See [`examples/wasm/index.html`](examples/wasm/index.html) for a full playground.
+</details>
+
+## AI Agent Usage
+
+### Vercel AI SDK (@unchartedfr/zapcode-ai)
+
+The recommended way — one call gives you `{ system, tools }` that plug directly into `generateText` / `streamText`:
+
+```typescript
+import { zapcode } from "@unchartedfr/zapcode-ai";
+import { generateText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+const { system, tools } = zapcode({
+  system: "You are a helpful travel assistant.",
+  tools: {
+    getWeather: {
+      description: "Get current weather for a city",
+      parameters: { city: { type: "string", description: "City name" } },
+      execute: async ({ city }) => {
+        const res = await fetch(`https://api.weather.com/${city}`);
+        return res.json();
+      },
+    },
+    searchFlights: {
+      description: "Search flights between two cities",
+      parameters: {
+        from: { type: "string" },
+        to: { type: "string" },
+        date: { type: "string" },
+      },
+      execute: async ({ from, to, date }) => {
+        return flightAPI.search(from, to, date);
+      },
+    },
+  },
+});
+
+// Works with any AI SDK model — Anthropic, OpenAI, Google, etc.
+const { text } = await generateText({
+  model: anthropic("claude-sonnet-4-20250514"),
+  system,
+  tools,
+  messages: [{ role: "user", content: "Weather in Tokyo and cheapest flight from London?" }],
+});
+```
+
+Under the hood: the LLM writes TypeScript code that calls your tools → Zapcode executes it in a sandbox → tool calls suspend the VM → your `execute` functions run on the host → results flow back in. All in ~2µs startup + tool execution time.
+
+See [`examples/typescript/ai-agent-zapcode-ai.ts`](examples/typescript/ai-agent-zapcode-ai.ts) for the full working example.
+
+<details>
+<summary><strong>Anthropic SDK</strong></summary>
+
+**TypeScript:**
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { Zapcode, ZapcodeSnapshotHandle } from "@unchartedfr/zapcode";
+
+const tools = {
+  getWeather: async (city: string) => {
+    const res = await fetch(`https://api.weather.com/${city}`);
+    return res.json();
+  },
+};
+
+const client = new Anthropic();
+const response = await client.messages.create({
+  model: "claude-sonnet-4-20250514",
+  max_tokens: 1024,
+  system: `Write TypeScript to answer the user's question.
+Available functions (use await): getWeather(city: string) → { condition, temp }
+Last expression = output. No markdown fences.`,
+  messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
+});
+
+const code = response.content[0].type === "text" ? response.content[0].text : "";
+
+// Execute + resolve tool calls via snapshot/resume
+const sandbox = new Zapcode(code, { externalFunctions: ["getWeather"] });
+let state = sandbox.start();
+while (!state.completed) {
+  const result = await tools[state.functionName](...state.args);
+  state = ZapcodeSnapshotHandle.load(state.snapshot).resume(result);
+}
+console.log(state.output);
+```
+
+**Python:**
+
+```python
+import anthropic
+from zapcode import Zapcode
+
+client = anthropic.Anthropic()
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1024,
+    system="""Write TypeScript to answer the user's question.
+Available functions (use await): getWeather(city: string) → { condition, temp }
+Last expression = output. No markdown fences.""",
+    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
+)
+code = response.content[0].text
+
+sandbox = Zapcode(code, external_functions=["getWeather"])
+state = sandbox.start()
+while state.get("suspended"):
+    result = get_weather(*state["args"])
+    state = state["snapshot"].resume(result)
+print(state["output"])
+```
+
+See [`examples/typescript/ai-agent-anthropic.ts`](examples/typescript/ai-agent-anthropic.ts) and [`examples/python/ai_agent_anthropic.py`](examples/python/ai_agent_anthropic.py).
+</details>
+
+<details>
+<summary><strong>Multi-SDK support</strong></summary>
+
+`zapcode()` returns adapters for all major AI SDKs from a single call:
+
+```typescript
+const { system, tools, openaiTools, anthropicTools, handleToolCall } = zapcode({
+  tools: { getWeather: { ... } },
+});
+
+// Vercel AI SDK
+await generateText({ model: anthropic("claude-sonnet-4-20250514"), system, tools, messages });
+
+// OpenAI SDK
+await openai.chat.completions.create({
+  messages: [{ role: "system", content: system }, ...userMessages],
+  tools: openaiTools,
+});
+
+// Anthropic SDK
+await anthropic.messages.create({ system, tools: anthropicTools, messages });
+
+// Any SDK — just extract the code from the tool call and pass it to handleToolCall
+const result = await handleToolCall(codeFromToolCall);
+```
+
+```python
+b = zapcode(tools={...})
+b.anthropic_tools  # → Anthropic SDK format
+b.openai_tools     # → OpenAI SDK format
+b.handle_tool_call(code)  # → Universal handler
+```
+</details>
+
+<details>
+<summary><strong>Custom adapters</strong></summary>
+
+Build a custom adapter for any AI SDK without forking Zapcode:
+
+```typescript
+import { zapcode, createAdapter } from "@unchartedfr/zapcode-ai";
+
+const myAdapter = createAdapter("my-sdk", (ctx) => {
+  return {
+    systemMessage: ctx.system,
+    actions: [{
+      id: ctx.toolName,
+      schema: ctx.toolSchema,
+      run: async (input: { code: string }) => {
+        return ctx.handleToolCall(input.code);
+      },
+    }],
+  };
+});
+
+const { custom } = zapcode({
+  tools: { ... },
+  adapters: [myAdapter],
+});
+
+const myConfig = custom["my-sdk"];
+```
+
+```python
+from zapcode_ai import zapcode, Adapter, AdapterContext
+
+class LangChainAdapter(Adapter):
+    name = "langchain"
+
+    def adapt(self, ctx: AdapterContext):
+        from langchain_core.tools import StructuredTool
+        return StructuredTool.from_function(
+            func=lambda code: ctx.handle_tool_call(code),
+            name=ctx.tool_name,
+            description=ctx.tool_description,
+        )
+
+b = zapcode(tools={...}, adapters=[LangChainAdapter()])
+langchain_tool = b.custom["langchain"]
+```
+
+The adapter receives an `AdapterContext` with everything needed: system prompt, tool name, tool JSON schema, and a `handleToolCall` function. Return whatever shape your SDK expects.
+</details>
+
+## What Zapcode Can and Cannot Do
+
+**Can do:**
+
+- Execute a useful subset of TypeScript — variables, functions, classes, generators, async/await, closures, destructuring, spread/rest, optional chaining, nullish coalescing, template literals, try/catch
+- Strip TypeScript types at parse time via [oxc](https://oxc.rs) — no `tsc` needed
+- Snapshot execution to bytes and resume later, even in a different process or machine
+- Call from Rust, Node.js, Python, or WebAssembly
+- Track and limit resources — memory, allocations, stack depth, and wall-clock time
+- 30+ string methods, 25+ array methods, plus Math, JSON, Object, and Promise builtins
+
+**Cannot do:**
+
+- Run arbitrary npm packages or the full Node.js standard library
+- Execute regular expressions (parsing supported, execution is a no-op)
+- Provide full `Promise` semantics (`.then()` chains, `Promise.race`, etc.)
+- Run code that requires `this` in non-class contexts
+
+These are intentional constraints, not bugs. Zapcode targets one use case: **running code written by AI agents** inside a secure, embeddable sandbox.
+
+## Supported Syntax
+
+| Feature | Status |
+|---|---|
+| Variables (`const`, `let`) | Supported |
+| Functions (declarations, arrows, expressions) | Supported |
+| Classes (`constructor`, methods, `extends`, `super`, `static`) | Supported |
+| Generators (`function*`, `yield`, `.next()`) | Supported |
+| Async/await | Supported |
+| Control flow (`if`, `for`, `while`, `do-while`, `switch`, `for-of`) | Supported |
+| Try/catch/finally, `throw` | Supported |
+| Closures with mutable capture | Supported |
+| Destructuring (object and array) | Supported |
+| Spread/rest operators | Supported |
+| Optional chaining (`?.`) | Supported |
+| Nullish coalescing (`??`) | Supported |
+| Template literals | Supported |
+| Type annotations, interfaces, type aliases | Stripped at parse time |
+| String methods (30+) | Supported |
+| Array methods (25+, including `map`, `filter`, `reduce`) | Supported |
+| Math, JSON, Object, Promise | Supported |
+| `import` / `require` / `eval` | Blocked (sandbox) |
+| Regular expressions | Parsed, not executed |
+| `var` declarations | Not supported (use `let`/`const`) |
+| Decorators | Not supported |
+| `Symbol`, `WeakMap`, `WeakSet` | Not supported |
+
+## Security
+
+Running AI-generated code is inherently dangerous. Unlike Docker, which isolates at the OS level, Zapcode isolates at the **language level** — no container, no process boundary, no syscall filter. The sandbox must be correct by construction, not by configuration.
+
+### Deny-by-default sandbox
+
+Guest code runs inside a bytecode VM with no access to the host:
+
+| Blocked | How |
+|---|---|
+| Filesystem (`fs`, `path`) | No `std::fs` in the core crate |
+| Network (`net`, `http`, `fetch`) | No `std::net` in the core crate |
+| Environment (`process.env`, `os`) | No `std::env` in the core crate |
+| `eval`, `Function()`, dynamic import | Blocked at parse time |
+| `import`, `require` | Blocked at parse time |
+| `globalThis`, `global` | Blocked at parse time |
+| Prototype pollution | Not applicable — objects are plain `IndexMap` values |
+
+The **only** escape hatch is external functions that you explicitly register. When guest code calls one, the VM suspends and returns a snapshot — your code resolves the call, not the guest.
+
+### Resource limits
+
+| Limit | Default | Configurable |
+|---|---|---|
+| Memory | 32 MB | `memory_limit_bytes` |
+| Execution time | 5 seconds | `time_limit_ms` |
+| Call stack depth | 512 frames | `max_stack_depth` |
+| Heap allocations | 100,000 | `max_allocations` |
+
+### Zero `unsafe` code
+
+The `zapcode-core` crate contains **zero `unsafe` blocks**. Memory safety is guaranteed by the Rust compiler.
+
+<details>
+<summary><strong>Adversarial test suite — 65 tests across 19 attack categories</strong></summary>
+
+| Attack category | Tests | Result |
+|---|---|---|
+| Prototype pollution (`Object.prototype`, `__proto__`) | 4 | Blocked |
+| Constructor chain escapes (`({}).constructor.constructor(...)`) | 3 | Blocked |
+| `eval`, `Function()`, indirect eval, dynamic import | 5 | Blocked at parse time |
+| `globalThis`, `process`, `require`, `import` | 6 | Blocked at parse time |
+| Stack overflow (direct + mutual recursion) | 2 | Caught by stack depth limit |
+| Memory exhaustion (huge arrays, string doubling) | 4 | Caught by allocation limit |
+| Infinite loops (`while(true)`, `for(;;)`) | 2 | Caught by time/allocation limit |
+| JSON bombs (deep nesting, huge payloads) | 2 | Depth-limited (max 64) |
+| Sparse array attacks (`arr[1e9]`, `arr[MAX_SAFE_INTEGER]`) | 3 | Capped growth (max +1024) |
+| toString/valueOf hijacking during coercion | 3 | Not invoked (by design) |
+| Unicode escapes for blocked keywords | 2 | Blocked |
+| Computed property access tricks | 2 | Returns undefined |
+| Timing side channels (`performance.now`) | 1 | Blocked |
+| Error message information leakage | 3 | No host paths/env exposed |
+| Type confusion attacks | 4 | Proper TypeError |
+| Promise/Generator internal abuse | 4 | No escape |
+| Negative array indices | 2 | Returns undefined |
+| `setTimeout`, `setInterval`, `Proxy`, `Reflect` | 6 | Blocked |
+| `with` statement, `arguments.callee` | 3 | Blocked |
+
+```bash
+cargo test -p zapcode-core --test security   # run the security tests
+```
+
+**Known limitations:**
+- `Object.freeze()` is not yet implemented — frozen objects can still be mutated (correctness gap, not a sandbox escape)
+- User-defined `toString()`/`valueOf()` are not called during implicit type coercion (intentional — prevents injection)
+</details>
+
+## Architecture
+
+```
+TypeScript source
+    │
+    ▼
+┌─────────┐   oxc_parser (fastest TS parser in Rust)
+│  Parse  │──────────────────────────────────────────►  Strip types
+└────┬────┘
+     ▼
+┌─────────┐
+│   IR    │   ZapcodeIR (statements, expressions, operators)
+└────┬────┘
+     ▼
+┌─────────┐
+│ Compile │   Stack-based bytecode (~50 instructions)
+└────┬────┘
+     ▼
+┌─────────┐
+│   VM    │   Execute, snapshot at external calls, resume later
+└────┬────┘
+     ▼
+  Result / Suspended { snapshot }
+```
+
+## Contributing
+
+```bash
+git clone https://github.com/TheUncharted/zapcode.git
+cd zapcode
+./scripts/dev-setup.sh   # installs toolchain, builds, runs tests
+```
+
+## License
+
+MIT

zapcode_ai-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "zapcode-ai"
+version = "1.0.0"
+description = "AI SDK integration for Zapcode — let LLMs write and execute TypeScript safely"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Uncharted"}]
+keywords = ["typescript", "interpreter", "sandbox", "ai", "mcp", "llm", "tool-use", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "zapcode",
+]
+
+[project.urls]
+Homepage = "https://github.com/TheUncharted/zapcode"
+Repository = "https://github.com/TheUncharted/zapcode"
+Issues = "https://github.com/TheUncharted/zapcode/issues"
+Documentation = "https://github.com/TheUncharted/zapcode#readme"
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.39.0"]
+openai = ["openai>=1.0.0"]
+langchain = ["langchain-core>=0.3.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zapcode_ai"]

zapcode_ai-1.0.0/src/zapcode_ai/__init__.py

@@ -0,0 +1,376 @@
+"""
+zapcode-ai — High-level AI SDK integration for Zapcode.
+
+Works with any AI SDK:
+
+    # Anthropic SDK
+    from zapcode_ai import zapcode
+    b = zapcode(tools={...})
+    response = client.messages.create(system=b.system, tools=b.anthropic_tools, ...)
+    result = b.handle_tool_call(code)
+
+    # OpenAI SDK
+    b = zapcode(tools={...})
+    response = client.chat.completions.create(
+        messages=[{"role": "system", "content": b.system}, ...],
+        tools=b.openai_tools,
+    )
+    result = b.handle_tool_call(code)
+
+    # Custom adapter
+    from zapcode_ai import zapcode, Adapter
+    class MyAdapter(Adapter):
+        name = "my-sdk"
+        def adapt(self, ctx):
+            return {"system": ctx.system, "tool": ctx.tool_schema}
+    b = zapcode(tools={...}, adapters=[MyAdapter()])
+    config = b.custom["my-sdk"]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Awaitable
+
+from zapcode import Zapcode, ZapcodeSnapshot
+
+
+# ---------------------------------------------------------------------------
+# Public types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ParamDef:
+    """Schema for a single parameter."""
+    type: str  # "string" | "number" | "boolean" | "object" | "array"
+    description: str = ""
+    optional: bool = False
+
+
+@dataclass
+class ToolDefinition:
+    """Definition for a single tool that guest code can call."""
+    description: str
+    parameters: dict[str, ParamDef]
+    execute: Callable[..., Any]  # (args: dict) -> Any or awaitable
+
+
+@dataclass
+class ExecutionResult:
+    """Result of executing guest code."""
+    output: Any
+    stdout: str
+    tool_calls: list[dict[str, Any]]
+
+
+# ---------------------------------------------------------------------------
+# Adapter protocol
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AdapterContext:
+    """Context passed to custom adapters."""
+    system: str
+    tool_name: str
+    tool_description: str
+    tool_schema: dict[str, Any]
+    handle_tool_call: Callable[[str], ExecutionResult]
+
+
+class Adapter:
+    """
+    Base class for custom SDK adapters.
+
+    Subclass this to add support for any AI SDK:
+
+        class LangChainAdapter(Adapter):
+            name = "langchain"
+            def adapt(self, ctx: AdapterContext):
+                from langchain_core.tools import StructuredTool
+                return StructuredTool.from_function(
+                    func=lambda code: ctx.handle_tool_call(code),
+                    name=ctx.tool_name,
+                    description=ctx.tool_description,
+                )
+    """
+    name: str = ""
+
+    def adapt(self, ctx: AdapterContext) -> Any:
+        raise NotImplementedError
+
+
+# ---------------------------------------------------------------------------
+# System prompt generation
+# ---------------------------------------------------------------------------
+
+def _generate_signature(name: str, defn: ToolDefinition) -> str:
+    params = ", ".join(
+        f"{pname}{'?' if pdef.optional else ''}: {pdef.type}"
+        for pname, pdef in defn.parameters.items()
+    )
+    return f"{name}({params})"
+
+
+def _build_system_prompt(
+    tools: dict[str, ToolDefinition],
+    user_system: str | None = None,
+) -> str:
+    tool_docs = "\n".join(
+        f"- await {_generate_signature(name, defn)}\n  {defn.description}"
+        for name, defn in tools.items()
+    )
+
+    parts = []
+    if user_system:
+        parts.append(user_system)
+
+    parts.append(
+        f"""When you need to use tools or compute something, write TypeScript code and pass it to the execute_code tool.
+The code runs in a sandboxed interpreter with these functions available (use await):
+
+{tool_docs}
+
+Rules:
+- Write ONLY TypeScript code, no markdown fences, no explanation.
+- The last expression in your code is the return value.
+- You can use variables, loops, conditionals, array methods, etc.
+- All tool calls must use `await`.
+- If the user's question doesn't need tools, you can compute the answer directly."""
+    )
+
+    return "\n\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Execution engine
+# ---------------------------------------------------------------------------
+
+def _execute_code(
+    code: str,
+    tool_defs: dict[str, ToolDefinition],
+    *,
+    memory_limit_bytes: int | None = None,
+    time_limit_ms: int | None = None,
+) -> ExecutionResult:
+    tool_names = list(tool_defs.keys())
+    tool_calls: list[dict[str, Any]] = []
+
+    kwargs: dict[str, Any] = {"external_functions": tool_names}
+    if time_limit_ms is not None:
+        kwargs["time_limit_ms"] = time_limit_ms
+    if memory_limit_bytes is not None:
+        kwargs["memory_limit_bytes"] = memory_limit_bytes
+
+    sandbox = Zapcode(code, **kwargs)
+    state = sandbox.start()
+
+    while state.get("suspended"):
+        fn_name = state["function_name"]
+        args = state["args"]
+
+        tool_def = tool_defs.get(fn_name)
+        if not tool_def:
+            raise ValueError(
+                f"Guest code called unknown function '{fn_name}'. "
+                f"Available: {', '.join(tool_names)}"
+            )
+
+        # Build named args from positional args
+        param_names = list(tool_def.parameters.keys())
+        named_args = {
+            param_names[i]: args[i]
+            for i in range(min(len(param_names), len(args)))
+        }
+
+        result = tool_def.execute(named_args)
+        tool_calls.append({"name": fn_name, "args": args, "result": result})
+
+        snapshot: ZapcodeSnapshot = state["snapshot"]
+        state = snapshot.resume(result)
+
+    return ExecutionResult(
+        output=state.get("output"),
+        stdout=state.get("stdout", ""),
+        tool_calls=tool_calls,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tool schema
+# ---------------------------------------------------------------------------
+
+_CODE_TOOL_DESCRIPTION = (
+    "Execute TypeScript code in a secure sandbox. "
+    "The code can call the available tool functions using await. "
+    "The last expression is the return value."
+)
+
+_CODE_TOOL_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "code": {
+            "type": "string",
+            "description": "TypeScript code to execute in the sandbox",
+        },
+    },
+    "required": ["code"],
+}
+
+
+# ---------------------------------------------------------------------------
+# Result object
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ZapcodeAI:
+    """Result of `zapcode()` — adapters for every major AI SDK."""
+
+    system: str
+    """System prompt instructing the LLM to write TypeScript."""
+
+    anthropic_tools: list[dict[str, Any]]
+    """Anthropic SDK tool format. Use with `messages.create(tools=...)`."""
+
+    openai_tools: list[dict[str, Any]]
+    """OpenAI SDK tool format. Use with `chat.completions.create(tools=...)`."""
+
+    handle_tool_call: Callable[[str], ExecutionResult]
+    """Execute code from a tool call. Works with any SDK."""
+
+    custom: dict[str, Any] = field(default_factory=dict)
+    """Output from custom adapters, keyed by adapter name."""
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def zapcode(
+    tools: dict[str, ToolDefinition],
+    *,
+    system: str | None = None,
+    memory_limit_bytes: int | None = None,
+    time_limit_ms: int = 10_000,
+    adapters: list[Adapter] | None = None,
+) -> ZapcodeAI:
+    """
+    Create AI SDK-compatible system prompt and tools for Zapcode.
+
+    Returns adapters for every major AI SDK:
+    - `anthropic_tools` → Anthropic SDK (`messages.create`)
+    - `openai_tools` → OpenAI SDK (`chat.completions.create`)
+    - `handle_tool_call(code)` → Universal handler for any SDK
+    - `custom` → Output from custom adapters
+
+    Example with Anthropic SDK::
+
+        from zapcode_ai import zapcode, ToolDefinition, ParamDef
+        import anthropic
+
+        b = zapcode(
+            tools={
+                "getWeather": ToolDefinition(
+                    description="Get weather for a city",
+                    parameters={"city": ParamDef(type="string")},
+                    execute=lambda args: get_weather(args["city"]),
+                ),
+            },
+            system="You are a helpful travel assistant.",
+        )
+
+        client = anthropic.Anthropic()
+        response = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            system=b.system,
+            tools=b.anthropic_tools,
+            messages=[{"role": "user", "content": "Weather in Tokyo?"}],
+        )
+
+        for block in response.content:
+            if block.type == "tool_use":
+                result = b.handle_tool_call(block.input["code"])
+                print(result.output)
+    """
+    system_prompt = _build_system_prompt(tools, system)
+
+    def handle_tool_call(code: str) -> ExecutionResult:
+        return _execute_code(
+            code, tools,
+            memory_limit_bytes=memory_limit_bytes,
+            time_limit_ms=time_limit_ms,
+        )
+
+    # Anthropic SDK format
+    anthropic_tools = [
+        {
+            "name": "execute_code",
+            "description": _CODE_TOOL_DESCRIPTION,
+            "input_schema": _CODE_TOOL_SCHEMA,
+        }
+    ]
+
+    # OpenAI SDK format
+    openai_tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "execute_code",
+                "description": _CODE_TOOL_DESCRIPTION,
+                "parameters": _CODE_TOOL_SCHEMA,
+            },
+        }
+    ]
+
+    # Run custom adapters
+    custom: dict[str, Any] = {}
+    if adapters:
+        ctx = AdapterContext(
+            system=system_prompt,
+            tool_name="execute_code",
+            tool_description=_CODE_TOOL_DESCRIPTION,
+            tool_schema=_CODE_TOOL_SCHEMA,
+            handle_tool_call=handle_tool_call,
+        )
+        for adapter in adapters:
+            custom[adapter.name] = adapter.adapt(ctx)
+
+    return ZapcodeAI(
+        system=system_prompt,
+        anthropic_tools=anthropic_tools,
+        openai_tools=openai_tools,
+        handle_tool_call=handle_tool_call,
+        custom=custom,
+    )
+
+
+def execute(
+    code: str,
+    tools: dict[str, ToolDefinition],
+    *,
+    memory_limit_bytes: int | None = None,
+    time_limit_ms: int | None = None,
+) -> ExecutionResult:
+    """
+    Execute TypeScript code directly in a Zapcode sandbox with tool resolution.
+
+    Lower-level API if you don't need AI SDK integration::
+
+        from zapcode_ai import execute, ToolDefinition, ParamDef
+
+        result = execute(
+            'const w = await getWeather("Tokyo"); w.temp',
+            tools={
+                "getWeather": ToolDefinition(
+                    description="Get weather",
+                    parameters={"city": ParamDef(type="string")},
+                    execute=lambda args: {"temp": 26, "condition": "Clear"},
+                ),
+            },
+        )
+        print(result.output)  # 26
+    """
+    return _execute_code(
+        code, tools,
+        memory_limit_bytes=memory_limit_bytes,
+        time_limit_ms=time_limit_ms,
+    )