@unchartedfr/zapcode-ai 1.0.0

package/README.md

@@ -0,0 +1,595 @@
+<p align="center">
+  <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>
+
+<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

package/dist/index.d.ts

@@ -0,0 +1,266 @@
+/**
+ * @unchartedfr/zapcode-ai — High-level AI SDK integration for Zapcode.
+ *
+ * Works with any AI SDK:
+ *
+ * ```typescript
+ * // Vercel AI SDK (recommended)
+ * import { zapcode } from "@unchartedfr/zapcode-ai";
+ * const { system, tools } = zapcode({ tools: { ... } });
+ * await generateText({ model, system, tools, messages });
+ *
+ * // OpenAI SDK
+ * import { zapcode } from "@unchartedfr/zapcode-ai";
+ * const { system, openaiTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const response = await openai.chat.completions.create({
+ *   messages: [{ role: "system", content: system }, ...],
+ *   tools: openaiTools,
+ * });
+ *
+ * // Anthropic SDK
+ * import { zapcode } from "@unchartedfr/zapcode-ai";
+ * const { system, anthropicTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const response = await anthropic.messages.create({
+ *   system, tools: anthropicTools, messages,
+ * });
+ * ```
+ */
+/** Definition for a single tool that guest code can call. */
+export interface ToolDefinition {
+    /** Human-readable description shown to the LLM. */
+    description: string;
+    /** Parameter schema — keys are parameter names. */
+    parameters: Record<string, ParamDef>;
+    /** The actual implementation. Called when guest code invokes this tool. */
+    execute: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+/** Schema for a single parameter. */
+export interface ParamDef {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    description?: string;
+    optional?: boolean;
+}
+/** Configuration for the `zapcode()` wrapper. */
+export interface ZapcodeAIOptions {
+    /** Tools available to guest code. */
+    tools: Record<string, ToolDefinition>;
+    /** Extra system prompt to prepend (optional). */
+    system?: string;
+    /** Memory limit in MB (default: 32). */
+    memoryLimitMb?: number;
+    /** Execution time limit in ms (default: 10000). */
+    timeLimitMs?: number;
+    /** Custom adapters for additional AI SDKs. */
+    adapters?: ZapcodeAdapter[];
+}
+/** Result of executing guest code. */
+export interface ExecutionResult {
+    output: unknown;
+    stdout: string;
+    toolCalls: Array<{
+        name: string;
+        args: unknown[];
+        result: unknown;
+    }>;
+}
+/** What `zapcode()` returns — adapters for every major AI SDK. */
+export interface ZapcodeAIResult {
+    /** System prompt instructing the LLM to write TypeScript. */
+    system: string;
+    /**
+     * Vercel AI SDK tool format.
+     * Use with `generateText({ tools })` or `streamText({ tools })`.
+     */
+    tools: Record<string, VercelAITool>;
+    /**
+     * OpenAI SDK tool format.
+     * Use with `openai.chat.completions.create({ tools: openaiTools })`.
+     */
+    openaiTools: OpenAITool[];
+    /**
+     * Anthropic SDK tool format.
+     * Use with `anthropic.messages.create({ tools: anthropicTools })`.
+     */
+    anthropicTools: AnthropicTool[];
+    /**
+     * Execute code from a tool call response.
+     * Works with any SDK — just extract the `code` argument from the
+     * `execute_code` tool call and pass it here.
+     */
+    handleToolCall: (code: string) => Promise<ExecutionResult>;
+    /**
+     * Output from custom adapters, keyed by adapter name.
+     * Access with `result.custom["my-adapter-name"]`.
+     */
+    custom: Record<string, unknown>;
+}
+/** Vercel AI SDK tool shape. */
+export interface VercelAITool {
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+    execute: (args: {
+        code: string;
+    }) => Promise<ExecutionResult>;
+}
+/** OpenAI SDK tool shape. */
+export interface OpenAITool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+    };
+}
+/** Anthropic SDK tool shape. */
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+}
+/**
+ * Create AI SDK-compatible system prompt and tools for Zapcode.
+ *
+ * Returns adapters for every major AI SDK:
+ * - `tools` → Vercel AI SDK (`generateText`, `streamText`)
+ * - `openaiTools` → OpenAI SDK (`chat.completions.create`)
+ * - `anthropicTools` → Anthropic SDK (`messages.create`)
+ * - `handleToolCall(code)` → Universal handler for any SDK
+ *
+ * @example
+ * ```typescript
+ * // Vercel AI SDK
+ * const { system, tools } = zapcode({ tools: { getWeather: { ... } } });
+ * await generateText({ model, system, tools, messages });
+ *
+ * // OpenAI SDK
+ * const { system, openaiTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const res = await openai.chat.completions.create({
+ *   messages: [{ role: "system", content: system }, ...],
+ *   tools: openaiTools,
+ * });
+ * const code = res.choices[0].message.tool_calls[0].function.arguments;
+ * const result = await handleToolCall(JSON.parse(code).code);
+ *
+ * // Anthropic SDK
+ * const { system, anthropicTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const res = await anthropic.messages.create({
+ *   system, tools: anthropicTools, messages,
+ * });
+ * const toolUse = res.content.find(b => b.type === "tool_use");
+ * const result = await handleToolCall(toolUse.input.code);
+ * ```
+ */
+export declare function zapcode(options: ZapcodeAIOptions): ZapcodeAIResult;
+/**
+ * Adapter interface for integrating Zapcode with any AI SDK.
+ *
+ * Implement this to add support for a new SDK. Your adapter receives
+ * the system prompt, tool description/schema, and a `handleToolCall`
+ * function, and returns whatever shape your SDK needs.
+ *
+ * @example
+ * ```typescript
+ * import { zapcode, createAdapter, ZapcodeAdapter } from "@unchartedfr/zapcode-ai";
+ *
+ * // Example: adapter for a hypothetical SDK
+ * const myAdapter: ZapcodeAdapter<MySDKConfig> = {
+ *   name: "my-sdk",
+ *   adapt({ system, toolDescription, toolSchema, handleToolCall }) {
+ *     return {
+ *       systemMessage: system,
+ *       actions: [{
+ *         id: "execute_code",
+ *         desc: toolDescription,
+ *         schema: toolSchema,
+ *         run: async (input) => handleToolCall(input.code),
+ *       }],
+ *     };
+ *   },
+ * };
+ *
+ * const { system, tools, custom } = zapcode({
+ *   tools: { ... },
+ *   adapters: [myAdapter],
+ * });
+ *
+ * const myConfig = custom["my-sdk"]; // typed as MySDKConfig
+ * ```
+ */
+export interface ZapcodeAdapter<TOutput = unknown> {
+    /** Unique name for this adapter (used as key in `custom` output). */
+    name: string;
+    /** Transform Zapcode's tool definition into your SDK's format. */
+    adapt(context: AdapterContext): TOutput;
+}
+/** Context passed to adapters. */
+export interface AdapterContext {
+    /** The generated system prompt. */
+    system: string;
+    /** Tool name (always "execute_code"). */
+    toolName: string;
+    /** Human-readable tool description. */
+    toolDescription: string;
+    /** JSON Schema for the tool parameters. */
+    toolSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+    /** Execute code in the sandbox. Pass the `code` string from the tool call. */
+    handleToolCall: (code: string) => Promise<ExecutionResult>;
+}
+/**
+ * Helper to create a typed adapter.
+ *
+ * @example
+ * ```typescript
+ * const langchainAdapter = createAdapter("langchain", (ctx) => {
+ *   return new DynamicStructuredTool({
+ *     name: ctx.toolName,
+ *     description: ctx.toolDescription,
+ *     func: async ({ code }) => JSON.stringify(await ctx.handleToolCall(code)),
+ *   });
+ * });
+ * ```
+ */
+export declare function createAdapter<TOutput>(name: string, adapt: (context: AdapterContext) => TOutput): ZapcodeAdapter<TOutput>;
+/**
+ * Execute TypeScript code directly in a Zapcode sandbox with tool resolution.
+ *
+ * This is the lower-level API if you don't need AI SDK integration — you
+ * provide the code yourself and Zapcode executes it with tool calls resolved.
+ *
+ * @example
+ * ```typescript
+ * import { execute } from "@unchartedfr/zapcode-ai";
+ *
+ * const result = await execute(
+ *   `const w = await getWeather("Tokyo"); w.temp`,
+ *   {
+ *     getWeather: {
+ *       description: "Get weather",
+ *       parameters: { city: { type: "string" } },
+ *       execute: async ({ city }) => ({ temp: 26, condition: "Clear" }),
+ *     },
+ *   },
+ * );
+ * console.log(result.output); // 26
+ * ```
+ */
+export declare function execute(code: string, tools: Record<string, ToolDefinition>, options?: {
+    memoryLimitMb?: number;
+    timeLimitMs?: number;
+}): Promise<ExecutionResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,254 @@
+/**
+ * @unchartedfr/zapcode-ai — High-level AI SDK integration for Zapcode.
+ *
+ * Works with any AI SDK:
+ *
+ * ```typescript
+ * // Vercel AI SDK (recommended)
+ * import { zapcode } from "@unchartedfr/zapcode-ai";
+ * const { system, tools } = zapcode({ tools: { ... } });
+ * await generateText({ model, system, tools, messages });
+ *
+ * // OpenAI SDK
+ * import { zapcode } from "@unchartedfr/zapcode-ai";
+ * const { system, openaiTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const response = await openai.chat.completions.create({
+ *   messages: [{ role: "system", content: system }, ...],
+ *   tools: openaiTools,
+ * });
+ *
+ * // Anthropic SDK
+ * import { zapcode } from "@unchartedfr/zapcode-ai";
+ * const { system, anthropicTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const response = await anthropic.messages.create({
+ *   system, tools: anthropicTools, messages,
+ * });
+ * ```
+ */
+import { Zapcode, ZapcodeSnapshotHandle } from "@unchartedfr/zapcode";
+import { jsonSchema, tool } from "ai";
+// ---------------------------------------------------------------------------
+// System prompt generation
+// ---------------------------------------------------------------------------
+function generateSignature(name, def) {
+    const params = Object.entries(def.parameters)
+        .map(([pName, pDef]) => {
+        const opt = pDef.optional ? "?" : "";
+        return `${pName}${opt}: ${pDef.type}`;
+    })
+        .join(", ");
+    return `${name}(${params})`;
+}
+function buildSystemPrompt(tools, userSystem) {
+    const toolDocs = Object.entries(tools)
+        .map(([name, def]) => `- await ${generateSignature(name, def)}\n  ${def.description}`)
+        .join("\n");
+    const parts = [];
+    if (userSystem) {
+        parts.push(userSystem);
+    }
+    parts.push(`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):
+
+${toolDocs}
+
+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 parts.join("\n\n");
+}
+// ---------------------------------------------------------------------------
+// Tool schema (shared across SDK formats)
+// ---------------------------------------------------------------------------
+const CODE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        code: {
+            type: "string",
+            description: "TypeScript code to execute in the sandbox",
+        },
+    },
+    required: ["code"],
+};
+const 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.";
+// ---------------------------------------------------------------------------
+// Execution engine
+// ---------------------------------------------------------------------------
+async function executeCode(code, toolDefs, options) {
+    const toolNames = Object.keys(toolDefs);
+    const toolCalls = [];
+    const sandbox = new Zapcode(code, {
+        externalFunctions: toolNames,
+        timeLimitMs: options.timeLimitMs ?? 10_000,
+        memoryLimitMb: options.memoryLimitMb ?? 32,
+    });
+    let state = sandbox.start();
+    let stdout = "";
+    // Snapshot/resume loop — resolve each tool call as the VM suspends
+    while (!state.completed) {
+        const { functionName, args } = state;
+        const toolDef = toolDefs[functionName];
+        if (!toolDef) {
+            throw new Error(`Guest code called unknown function '${functionName}'. ` +
+                `Available: ${toolNames.join(", ")}`);
+        }
+        // Build named args from positional args using the parameter schema
+        const paramNames = Object.keys(toolDef.parameters);
+        const namedArgs = {};
+        for (let i = 0; i < paramNames.length && i < args.length; i++) {
+            namedArgs[paramNames[i]] = args[i];
+        }
+        const result = await toolDef.execute(namedArgs);
+        toolCalls.push({ name: functionName, args, result });
+        // Resume the VM with the tool's return value
+        const snapshot = ZapcodeSnapshotHandle.load(state.snapshot);
+        state = snapshot.resume(result);
+    }
+    if (state.stdout) {
+        stdout = state.stdout;
+    }
+    return {
+        output: state.output,
+        stdout,
+        toolCalls,
+    };
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Create AI SDK-compatible system prompt and tools for Zapcode.
+ *
+ * Returns adapters for every major AI SDK:
+ * - `tools` → Vercel AI SDK (`generateText`, `streamText`)
+ * - `openaiTools` → OpenAI SDK (`chat.completions.create`)
+ * - `anthropicTools` → Anthropic SDK (`messages.create`)
+ * - `handleToolCall(code)` → Universal handler for any SDK
+ *
+ * @example
+ * ```typescript
+ * // Vercel AI SDK
+ * const { system, tools } = zapcode({ tools: { getWeather: { ... } } });
+ * await generateText({ model, system, tools, messages });
+ *
+ * // OpenAI SDK
+ * const { system, openaiTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const res = await openai.chat.completions.create({
+ *   messages: [{ role: "system", content: system }, ...],
+ *   tools: openaiTools,
+ * });
+ * const code = res.choices[0].message.tool_calls[0].function.arguments;
+ * const result = await handleToolCall(JSON.parse(code).code);
+ *
+ * // Anthropic SDK
+ * const { system, anthropicTools, handleToolCall } = zapcode({ tools: { ... } });
+ * const res = await anthropic.messages.create({
+ *   system, tools: anthropicTools, messages,
+ * });
+ * const toolUse = res.content.find(b => b.type === "tool_use");
+ * const result = await handleToolCall(toolUse.input.code);
+ * ```
+ */
+export function zapcode(options) {
+    const { tools: toolDefs, system: userSystem, memoryLimitMb, timeLimitMs, adapters } = options;
+    const system = buildSystemPrompt(toolDefs, userSystem);
+    const execOptions = { memoryLimitMb, timeLimitMs };
+    // Universal handler
+    const handleToolCall = async (code) => {
+        return executeCode(code, toolDefs, execOptions);
+    };
+    // Vercel AI SDK format — use tool() + jsonSchema() for proper integration
+    const tools = {
+        execute_code: tool({
+            description: CODE_TOOL_DESCRIPTION,
+            parameters: jsonSchema(CODE_TOOL_SCHEMA),
+            execute: async (args) => handleToolCall(args.code),
+        }),
+    };
+    // OpenAI SDK format
+    const openaiTools = [
+        {
+            type: "function",
+            function: {
+                name: "execute_code",
+                description: CODE_TOOL_DESCRIPTION,
+                parameters: CODE_TOOL_SCHEMA,
+            },
+        },
+    ];
+    // Anthropic SDK format
+    const anthropicTools = [
+        {
+            name: "execute_code",
+            description: CODE_TOOL_DESCRIPTION,
+            input_schema: CODE_TOOL_SCHEMA,
+        },
+    ];
+    // Run custom adapters
+    const custom = {};
+    if (adapters) {
+        const adapterContext = {
+            system,
+            toolName: "execute_code",
+            toolDescription: CODE_TOOL_DESCRIPTION,
+            toolSchema: CODE_TOOL_SCHEMA,
+            handleToolCall,
+        };
+        for (const adapter of adapters) {
+            custom[adapter.name] = adapter.adapt(adapterContext);
+        }
+    }
+    return { system, tools, openaiTools, anthropicTools, handleToolCall, custom };
+}
+/**
+ * Helper to create a typed adapter.
+ *
+ * @example
+ * ```typescript
+ * const langchainAdapter = createAdapter("langchain", (ctx) => {
+ *   return new DynamicStructuredTool({
+ *     name: ctx.toolName,
+ *     description: ctx.toolDescription,
+ *     func: async ({ code }) => JSON.stringify(await ctx.handleToolCall(code)),
+ *   });
+ * });
+ * ```
+ */
+export function createAdapter(name, adapt) {
+    return { name, adapt };
+}
+// ---------------------------------------------------------------------------
+// Convenience: standalone execution without AI SDK
+// ---------------------------------------------------------------------------
+/**
+ * Execute TypeScript code directly in a Zapcode sandbox with tool resolution.
+ *
+ * This is the lower-level API if you don't need AI SDK integration — you
+ * provide the code yourself and Zapcode executes it with tool calls resolved.
+ *
+ * @example
+ * ```typescript
+ * import { execute } from "@unchartedfr/zapcode-ai";
+ *
+ * const result = await execute(
+ *   `const w = await getWeather("Tokyo"); w.temp`,
+ *   {
+ *     getWeather: {
+ *       description: "Get weather",
+ *       parameters: { city: { type: "string" } },
+ *       execute: async ({ city }) => ({ temp: 26, condition: "Clear" }),
+ *     },
+ *   },
+ * );
+ * console.log(result.output); // 26
+ * ```
+ */
+export async function execute(code, tools, options) {
+    return executeCode(code, tools, options ?? {});
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@unchartedfr/zapcode-ai",
+  "version": "1.0.0",
+  "description": "AI SDK integration for Zapcode — let LLMs write and execute TypeScript safely",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@unchartedfr/zapcode": "^1.0.0"
+  },
+  "peerDependencies": {
+    "ai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "ai": "^4.1.0",
+    "@types/node": "^22.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "typescript",
+    "interpreter",
+    "sandbox",
+    "ai",
+    "mcp",
+    "llm",
+    "tool-use",
+    "agent"
+  ],
+  "homepage": "https://github.com/TheUncharted/zapcode#readme",
+  "bugs": "https://github.com/TheUncharted/zapcode/issues",
+  "license": "MIT",
+  "author": "Uncharted",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheUncharted/zapcode.git",
+    "directory": "packages/zapcode-ai"
+  }
+}