@ny4n/codemode 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,325 @@
-# Temporary Holding Version
+# @ny4n/codemode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs model-written JavaScript in a QuickJS VM (compiled to WebAssembly) where the only capability is calling injected tools. Nested tool calls never enter the LLM context; only the script's output and return value do.
+
+Scripts use `tools`, `ALL_TOOLS`, `text`, `image`, `exit`, `store`, and `load`, and may start with a `// @options:` line. The coding agent uses it for its built-in `codemode` tool. It has no nyan dependencies and can be used on its own to expose any functions (remote APIs, MCP servers, application services) to model-written scripts.
+
+The package runs in two kinds of environments. Each has its own sandbox class, but they share one API, one script environment, and one result format:
+
+| Environment | Sandbox | Import from | Where scripts run |
+| --- | --- | --- | --- |
+| Node and Bun | `CodemodeSandbox` | `@ny4n/codemode` | a worker thread per execution |
+| Cloudflare Workers and Durable Objects | `RemoteCodemodeSandbox` | `@ny4n/codemode/portable` | a Durable Object in a separately deployed Worker |
+
+See [Usage on Node and Bun](#usage-on-node-and-bun) and [Usage on Cloudflare Workers](#usage-on-cloudflare-workers). A third sandbox, `InlineCodemodeSandbox`, runs scripts on the calling thread for other runtimes, or on Cloudflare when blocking the caller is acceptable.
+
+## Usage on Node and Bun
+
+```ts
+import { CodemodeSandbox } from "@ny4n/codemode";
+
+const sandbox = new CodemodeSandbox({
+	timeoutMs: 60_000,
+	tools: [
+		{
+			name: "read",
+			execute: async (args, { signal }) => {
+				const { path } = args as { path: string };
+				return await readFile(path, "utf8");
+			},
+		},
+	],
+});
+
+const result = await sandbox.execute(`
+	const source = await tools.read({ path: "package.json" });
+	text("bytes " + source.length);
+	return JSON.parse(source).name;
+`);
+
+console.log(result.output); // [{ type: "text", text: "bytes 1234" }]
+if (result.ok) console.log(result.value); // "@ny4n/codemode"
+else console.error(result.error.kind, result.error.message);
+
+await sandbox.close();
+```
+
+`code` is the body of an async function: `return` and top-level `await` work. Inside the script, with every sandbox:
+
+- `tools.<name>(args)` returns a promise. Arguments and results make a JSON round trip. A tool that throws rejects with an `Error` carrying the same message. Tool names are also exposed as identifiers: characters that are not valid in identifiers become `_` (`toCodemodeIdentifier`), so `my-tool` is `tools.my_tool` as well as `tools["my-tool"]`.
+- `ALL_TOOLS` lists `{ name, description }` for every tool, with `name` as the identifier.
+- `text(value)` appends a text item to `result.output`; values other than strings are JSON-stringified. `console.log/info/warn/error/debug` append text items with `console: true`.
+- `image(urlOrItem)` appends an image item. It accepts a base64 `data:` URL, `{ image_url }`, or an MCP `ImageContent` block (`{ type: "image", data, mimeType }`). Remote URLs are rejected.
+- `exit()` ends the script successfully right away, keeping its output and store writes.
+- `globals` passed to the sandbox are called as top-level functions, for example a host helper `image(ref)`. They behave like tools but are not recorded in `result.calls`. A name like `models.classify` puts the function on a frozen `models` object. With `spread: true`, `execute` receives all call arguments as an array instead of the first one, and `signature` replaces the declaration generated from the schemas.
+- `store(key, value)` and `load(key)` read and write JSON values synchronously. See [Store](#store).
+- Nothing else: no timers, `fetch`, `process`, `require`, modules, or `WebAssembly`. `eval` and `Function` work but only produce more code inside the same VM.
+
+`timeoutMs: Infinity` disables the deadline; the script then runs until it settles or `signal` aborts it. A script that waits on a promise nothing can settle (no tool call pending, and the VM has no timers or I/O) fails right away instead of hanging.
+
+`memoryLimitBytes` caps the VM's heap. Allocations beyond it fail inside the script as `InternalError: out of memory`.
+
+## Store
+
+`store`/`load` let scripts keep values across executions. The sandbox does not persist anything itself: pass the current values as `options.store`, and a successful result reports what the script changed as `result.storeWrites` (`{ set, delete }`). Failed executions report no writes.
+
+```ts
+const result = await sandbox.execute(`store("runs", (load("runs") ?? 0) + 1)`, { store: saved });
+if (result.ok) {
+	for (const key of result.storeWrites.delete) delete saved[key];
+	Object.assign(saved, result.storeWrites.set);
+}
+```
+
+`load` returns a copy, so mutating it does not change the store. Storing `undefined` deletes the key. A value may be at most `MAX_STORE_VALUE_CHARS` (256 Ki) characters of JSON and all values together at most `MAX_STORE_TOTAL_CHARS` (1 Mi); larger writes throw a `RangeError` inside the script.
+
+## Source format
+
+`parseCodemodeSource()` accepts a script whose first line may be an options line:
+
+```js
+// @options: {"max_output_tokens": 2000, "timeout_ms": 30000}
+const source = await tools.read({ path: "package.json" });
+text(JSON.parse(source).name);
+```
+
+Supported fields are `max_output_tokens`, a token budget for the output, and `timeout_ms`, a hard deadline. The sandbox does not act on them; the caller decides. The options line is replaced by an empty line, so line numbers in stack traces still match the input. Empty input, invalid JSON, unknown fields, or an options line without code throw `CodemodeSourceError`. `CODEMODE_SOURCE_GRAMMAR` is a Lark grammar for providers that support grammar-constrained tool input. Both are also available from the lightweight `@ny4n/codemode/source` entry.
+
+## Bundled Node and Bun hosts
+
+By default `CodemodeSandbox` loads `quickjs-wasi/quickjs.wasm` from the installed package and starts the worker file that sits next to this package's module. Neither exists on disk when the host is bundled, so pass both:
+
+```ts
+import { CodemodeSandbox, loadQuickJSWasm } from "@ny4n/codemode";
+
+const sandbox = new CodemodeSandbox({
+	tools,
+	// Compiled once per path and cached.
+	wasm: loadQuickJSWasm(pathToQuickJSWasm),
+	// A file of your build containing `import "@ny4n/codemode/worker";`
+	workerUrl: new URL("./codemode-worker.js", import.meta.url),
+});
+```
+
+`workerUrl` accepts a URL or string. For a Bun compiled executable, include the worker as an
+additional build entrypoint and pass its relative source path as a string, for example
+`"./src/codemode-worker.ts"`; Bun resolves that form from its embedded module graph.
+
+## Usage on Cloudflare Workers
+
+`CodemodeSandbox` needs Node or Bun. It runs each script in a worker thread and reads the QuickJS binary from disk. Cloudflare Workers have neither, and they cannot compile WebAssembly at runtime. Two other sandboxes have the same API, the same script environment, and the same `CodemodeResult`. Only where the VM runs differs:
+
+| Sandbox | Where the VM runs | Use it for |
+| --- | --- | --- |
+| `CodemodeSandbox` | a worker thread | Node and Bun |
+| `RemoteCodemodeSandbox` | another isolate, usually a Durable Object in a separate Worker | a Durable Object that runs an agent session |
+| `InlineCodemodeSandbox` | the calling thread | anywhere else with WebAssembly, when blocking the caller is acceptable |
+
+Import the last two from `@ny4n/codemode/portable`, which has no Node imports. On Cloudflare, `@ny4n/codemode/cloudflare` adds the deployable Durable Object and the QuickJS module compiled by Wrangler.
+
+### Why a separate Worker
+
+QuickJS runs synchronously, so a script that computes holds its thread until it awaits a tool. Measured on Cloudflare (October 2026), a script that computed for ten seconds delayed every other request to the session object by the full ten seconds in two placements:
+
+- inside the session's Durable Object
+- in a Dynamic Worker loaded by that object
+
+In a Durable Object of a separately deployed Worker, the delay was about 50 ms. `RemoteCodemodeSandbox` therefore keeps the tools and call records in the session and sends only the VM to the sandbox Worker. Each tool call travels back to the session over Workers RPC.
+
+### Deploying the sandbox Worker
+
+A complete setup is in [`examples/cloudflare`](https://github.com/blxzer77/nyan/tree/main/packages/codemode/examples/cloudflare). The sandbox Worker is one file:
+
+```ts
+// sandbox/src/index.ts
+export { CodemodeSandboxDurableObject as CodemodeSandbox } from "@ny4n/codemode/cloudflare";
+
+export default {
+	fetch: () => new Response("Not found", { status: 404 }),
+};
+```
+
+```jsonc
+// sandbox/wrangler.jsonc
+{
+	"name": "nyan-codemode-sandbox",
+	"main": "src/index.ts",
+	"compatibility_date": "2026-04-22",
+	"workers_dev": false,
+	"preview_urls": false,
+	"migrations": [{ "tag": "v1", "new_sqlite_classes": ["CodemodeSandbox"] }],
+	"limits": { "cpu_ms": 60000 }
+}
+```
+
+Install `@ny4n/codemode` in the sandbox Worker's project and run `npx wrangler deploy`. Wrangler bundles QuickJS (about 640 KB) as a compiled WebAssembly module. The object has no routes and keeps no state, and it never uses its storage.
+
+### Using it from the agent's Worker
+
+Bind the class with `script_name`. Binding a class exported from the agent's own Worker would bring back the blocking described above.
+
+```jsonc
+// agent/wrangler.jsonc
+"durable_objects": {
+	"bindings": [
+		{ "name": "CODEMODE_SANDBOX", "class_name": "CodemodeSandbox", "script_name": "nyan-codemode-sandbox" }
+	]
+}
+```
+
+Then replace the sandbox. Tools, options other than `wasm` and `workerUrl`, and results stay the same:
+
+```ts
+import type { CodemodeSandboxDurableObject } from "@ny4n/codemode/cloudflare";
+import { RemoteCodemodeSandbox } from "@ny4n/codemode/portable";
+
+interface Env {
+	CODEMODE_SANDBOX: DurableObjectNamespace<CodemodeSandboxDurableObject>;
+}
+
+// Before: new CodemodeSandbox({ tools, timeoutMs: 60_000 })
+const sandbox = new RemoteCodemodeSandbox({
+	tools,
+	timeoutMs: 60_000,
+	remote: () => env.CODEMODE_SANDBOX.getByName(sessionId),
+});
+const result = await sandbox.execute(code, { signal, store });
+```
+
+Import the sandbox from `/portable` in the agent's Worker. Importing `/cloudflare` would also bundle QuickJS there. `remote` is called once per execution and picks the Durable Object that runs it.
+
+- **One object per session**, `getByName(sessionId)`, keeps a session's scripts together. Two scripts of the same session take turns on one thread.
+- **One object per execution**, `getByName(crypto.randomUUID())`, runs every script on its own.
+
+Run both Workers locally with `wrangler dev -c agent/wrangler.jsonc -c sandbox/wrangler.jsonc`.
+
+### Limits on Cloudflare
+
+- **Interrupt budget.** While a script computes without calling a tool, no timer can run, and `Date.now()` does not advance. A script that never yields is limited only by the interrupt budget, not by `timeoutMs`. QuickJS polls an interrupt handler while it runs, and the sandbox counts the polls. Past the budget, the execution fails with `kind: "timeout"`.
+   - The default `DEFAULT_INTERRUPT_BUDGET` of 100,000 polls is about 2 seconds of a tight loop on an Apple M-series laptop and about 10 seconds on Cloudflare.
+   - Keep the budget below the Worker's `cpu_ms` limit (30 seconds by default). Hitting that limit resets the object instead of failing one script.
+- **Memory.** Each VM may use up to 32 MiB by default. All VMs in one isolate share its 128 MB.
+- **Changing the limits.** The Durable Object caps every request at its own limits, whatever the client asks for. To change them, subclass it in the sandbox Worker:
+
+```ts
+import { CodemodeSandboxDurableObject } from "@ny4n/codemode/cloudflare";
+
+export class CodemodeSandbox extends CodemodeSandboxDurableObject {
+	protected maxInterruptBudget = 200_000;
+	protected maxMemoryLimitBytes = 64 * 1024 * 1024;
+}
+```
+
+- **Aborts and timeouts.** `timeoutMs` and `signal` end the execution in the caller right away, with `kind: "timeout"` or `kind: "aborted"`. The remote VM stops at its next tool call. A remote VM that is computing at that moment keeps running until it calls a tool or uses up its budget.
+- **Billing.** Each execution is one Durable Object request. The sandbox object is billed for wall-clock duration while an execution runs, including time spent waiting on tools.
+
+### On the calling thread
+
+When blocking the caller is acceptable, for example in a stateless Worker that serves one request, run the VM on the caller's thread instead. Nothing extra needs to be deployed:
+
+```ts
+import { createInlineCodemodeSandbox } from "@ny4n/codemode/cloudflare";
+
+const sandbox = createInlineCodemodeSandbox({ tools, timeoutMs: 60_000, interruptBudget: 50_000 });
+const result = await sandbox.execute(code);
+```
+
+`createInlineCodemodeSandbox()` passes the QuickJS module Wrangler compiled to `InlineCodemodeSandbox`. With another bundler, import `InlineCodemodeSandbox` from `/portable` and pass your own compiled module as `wasm`.
+
+- **Blocking.** A script that computes blocks the caller until it awaits a tool or uses up its `interruptBudget`.
+- **Stack.** QuickJS's stack guard is reduced to `INLINE_MAX_STACK_SIZE`, so that it trips before the caller's smaller stack runs out.
+
+## Declarations for the model
+
+Tools and globals can carry `description`, `inputSchema`, and `outputSchema` (JSON Schema). `renderDeclarations()` turns them into TypeScript declarations for a model-facing tool description:
+
+```ts
+renderDeclarations({ tools: sandbox.tools, globals: sandbox.globals });
+// declare const tools: {
+//   /** Read a file */
+//   read(args: {
+//     path: string;
+//   }): Promise<string>;
+// };
+```
+
+Schemas only shape the declarations; values are not validated against them. Local references (`#/$defs/...`, `#/definitions/...`) are expanded; recursive and remote references render as `unknown`.
+
+## Using with @ny4n/agent-core
+
+To give an `Agent` a codemode tool, expose its other tools to the sandbox and wrap `execute()` as an `AgentTool`:
+
+```ts
+import type { AgentTool } from "@ny4n/agent-core";
+import {
+	type CodemodeJsonSchema,
+	CodemodeSandbox,
+	type CodemodeTool,
+	renderDeclarations,
+} from "@ny4n/codemode";
+import { Type } from "typebox";
+
+const sandboxTools: CodemodeTool[] = agentTools.map((tool) => ({
+	name: tool.name,
+	description: tool.description,
+	inputSchema: tool.parameters as CodemodeJsonSchema,
+	outputSchema: (tool.outputSchema as CodemodeJsonSchema | undefined) ?? { type: "string" },
+	execute: async (args, { signal }) => {
+		const result = await tool.execute("nested", args as never, signal);
+		if (tool.outputSchema && result.structuredContent !== undefined) return result.structuredContent;
+		return result.content.map((block) => (block.type === "text" ? block.text : "")).join("\n");
+	},
+}));
+
+const codemodeTool: AgentTool = {
+	name: "codemode",
+	label: "Codemode",
+	description: `Run JavaScript that calls tools as \`await tools.<name>(args)\`. Output with text() or return.\n\n${renderDeclarations({ tools: sandboxTools })}`,
+	parameters: Type.Object({ code: Type.String() }),
+	execute: async (_toolCallId, { code }, signal) => {
+		const sandbox = new CodemodeSandbox({ tools: sandboxTools });
+		try {
+			const result = await sandbox.execute(code, { signal });
+			const content = [...result.output];
+			if (result.ok && result.value !== undefined) content.push({ type: "text", text: JSON.stringify(result.value) });
+			if (!result.ok) content.push({ type: "text", text: result.error.stack ?? result.error.message });
+			return { content, details: undefined, isError: !result.ok };
+		} finally {
+			await sandbox.close();
+		}
+	},
+};
+```
+
+`result.output` items already have the shape of `@ny4n/ai`'s `TextContent` and `ImageContent`. Calling `tool.execute()` directly skips the agent's `beforeToolCall` and `afterToolCall` hooks. To apply them to nested calls too, run each call through `runToolCall()` from `@ny4n/agent-core`, as the [mcp-codemode example](https://github.com/blxzer77/nyan/tree/main/packages/agent/examples/mcp-codemode) does. That example also rejects failed nested calls inside the script and combines codemode with MCP tools.
+
+## Results
+
+`execute()` never rejects for script failures. `result.error.kind` is one of:
+
+| kind      | meaning                                                                     |
+| --------- | --------------------------------------------------------------------------- |
+| `script`  | the script threw or failed to parse; `stack` points at `codemode.js:<line>` |
+| `timeout` | the deadline expired or the interrupt budget ran out; the VM was stopped    |
+| `aborted` | `options.signal` fired or `close()` was called; the VM was stopped          |
+| `sandbox` | the VM or its transport failed, for example a wasm trap, a missing worker file, or a failed remote |
+
+`result.output` holds the text and image items in the order the script produced them, also for failed executions. The host keeps all of it until the script ends, so output is limited to `MAX_OUTPUT_CHARS` (16 Mi) characters of text and base64 image data and `MAX_OUTPUT_ITEMS` (100000) items. Past either limit the script fails with a `RangeError`, even if it catches the error. `result.calls` lists every tool call with `status: "ok" | "error" | "cancelled"`. A call that is still running when the script returns (not awaited) is aborted through the tool's `signal` and reported as `cancelled`.
+
+## How it works
+
+This section describes `CodemodeSandbox`. The other sandboxes share the same host side, prelude, and VM, and replace only the worker thread. See [Usage on Cloudflare Workers](#usage-on-cloudflare-workers).
+
+Each `execute()` starts a worker thread (about 20 ms including VM creation) that instantiates a fresh QuickJS VM from the compiled wasm module. The VM is a separate wasm instance with its own linear memory. Its only imports are a WASI shim (clock, random, and stdout/stderr writes, which the worker discards) and one host-call entry point, so the script cannot reach the host except through the functions the worker registers.
+
+The worker evaluates a prelude inside the VM that holds the single host bridge in a closure and builds `tools`, `console`, and globals on top of it. The script is compiled as an async function body.
+
+Tool calls are relayed to the host thread as messages; the host runs the tool and posts the JSON result back. The host owns the deadline and the abort signal. When either fires, it sets a shared interrupt flag that the VM polls, then calls `worker.terminate()`. The flag is needed on Bun, where `terminate()` cannot stop a thread that is spinning in wasm (`while (true) {}` or `while (true) await null`).
+
+The worker keeps script execution off the host thread: QuickJS runs synchronously, so a spinning script on the host thread would block its event loop.
+
+## Runtime notes
+
+- Works the same on Node and Bun, including memory limits, interrupts, and a catchable `RangeError` for deep recursion (QuickJS's stack guard is enabled; without it the wasm stack overflows and traps).
+- Stack traces use QuickJS frames (`at f (codemode.js:2:31)`), prefixed with `Name: message` like V8. The wrapper prefix shares line 1 with the script, so line numbers are exact; column numbers on line 1 are shifted.
+- QuickJS is an interpreter. Glue code and filtering tool results are fast enough; heavy computation is slower than in V8.

package/dist/cloudflare.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Cloudflare Workers entry, for Workers built with Wrangler.
+ *
+ * Wrangler's default `CompiledWasm` rule turns the `.wasm` import below into a
+ * `WebAssembly.Module`; Workers cannot compile WebAssembly from bytes at runtime. Other bundlers
+ * do not support the import: use `@ny4n/codemode/portable` with your own module there.
+ *
+ * Two ways to run codemode on Cloudflare:
+ * - `RemoteCodemodeSandbox` with a {@link CodemodeSandboxDurableObject} deployed as its own
+ *   Worker: scripts run in a separate isolate and never block the caller. Use this from a Durable
+ *   Object that serves a session.
+ * - {@link createInlineCodemodeSandbox}: scripts run on the caller's thread. Simplest; a script
+ *   that computes blocks the caller until it awaits a tool or uses up its interrupt budget.
+ */
+import { DurableObject } from "cloudflare:workers";
+import { InlineCodemodeSandbox, type InlineCodemodeSandboxOptions } from "./runtime/inline.ts";
+import { type CodemodeRemoteExchange, type CodemodeRemoteRequest } from "./runtime/remote.ts";
+import type { CodemodeWasmModule } from "./wasm.ts";
+export * from "./portable.ts";
+/** Default VM memory limit of {@link CodemodeSandboxDurableObject}. Isolates have 128 MB in total. */
+export declare const DEFAULT_REMOTE_MEMORY_LIMIT_BYTES: number;
+/** `quickjs-wasi/quickjs.wasm`, compiled by Wrangler. */
+export declare const cloudflareQuickJSWasm: CodemodeWasmModule;
+/** `InlineCodemodeSandbox` with the QuickJS module Wrangler bundled. */
+export declare function createInlineCodemodeSandbox(options?: Omit<InlineCodemodeSandboxOptions, "wasm">): InlineCodemodeSandbox;
+/**
+ * The remote end of `RemoteCodemodeSandbox`: a Durable Object whose one RPC method runs a script's
+ * VM and calls back into the client for every tool call.
+ *
+ * Deploy it as its own Worker and bind it from the Worker that runs your agent with `script_name`.
+ * A separate Worker is what keeps scripts off the agent's thread: a class in the same Worker can
+ * share an isolate, and therefore a thread, with the objects that call it.
+ *
+ * The object keeps no state between executions and never touches storage. Executions that reach
+ * the same instance share its thread: they interleave while they wait on tools, and a script that
+ * computes delays the others. Name instances per session (`getByName(sessionId)`) to keep one
+ * session's scripts together, or per execution for full independence.
+ *
+ * Limits apply to every request, whatever the client asks for. Override the fields in a subclass:
+ *
+ *     export class CodemodeSandbox extends CodemodeSandboxDurableObject {
+ *       protected maxInterruptBudget = 200_000;
+ *     }
+ */
+export declare class CodemodeSandboxDurableObject<Env = unknown> extends DurableObject<Env> {
+    /** Interrupt polls per execution; the client may only ask for less. See `InlineCodemodeSandboxOptions`. */
+    protected maxInterruptBudget: number;
+    /** VM memory per execution; the client may only ask for less. */
+    protected maxMemoryLimitBytes: number;
+    /** Called by `RemoteCodemodeSandbox` over RPC. Resolves when the script has settled or was stopped. */
+    execute(request: CodemodeRemoteRequest, exchange: CodemodeRemoteExchange): Promise<void>;
+}
+//# sourceMappingURL=cloudflare.d.ts.map

package/dist/cloudflare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAEN,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAuB,MAAM,qBAAqB,CAAC;AACnH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD,cAAc,eAAe,CAAC;AAM9B,sGAAsG;AACtG,eAAO,MAAM,iCAAiC,QAAmB,CAAC;AAElE,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,EAAE,kBAAgC,CAAC;AAErE,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,IAAI,CAAC,4BAA4B,EAAE,MAAM,CAAM,yBAEnG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,4BAA4B,CAAC,GAAG,GAAG,OAAO,CAAE,SAAQ,aAAa,CAAC,GAAG,CAAC;IAClF,2GAA2G;IAC3G,SAAS,CAAC,kBAAkB,EAAE,MAAM,CAA4B;IAChE,iEAAiE;IACjE,SAAS,CAAC,mBAAmB,EAAE,MAAM,CAAqC;IAE1E,uGAAuG;IACvG,OAAO,CAAC,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;CACD"}

package/dist/cloudflare.js

@@ -0,0 +1,64 @@
+/**
+ * Cloudflare Workers entry, for Workers built with Wrangler.
+ *
+ * Wrangler's default `CompiledWasm` rule turns the `.wasm` import below into a
+ * `WebAssembly.Module`; Workers cannot compile WebAssembly from bytes at runtime. Other bundlers
+ * do not support the import: use `@ny4n/codemode/portable` with your own module there.
+ *
+ * Two ways to run codemode on Cloudflare:
+ * - `RemoteCodemodeSandbox` with a {@link CodemodeSandboxDurableObject} deployed as its own
+ *   Worker: scripts run in a separate isolate and never block the caller. Use this from a Durable
+ *   Object that serves a session.
+ * - {@link createInlineCodemodeSandbox}: scripts run on the caller's thread. Simplest; a script
+ *   that computes blocks the caller until it awaits a tool or uses up its interrupt budget.
+ */
+import { DurableObject } from "cloudflare:workers";
+import quickjsWasmImport from "quickjs-wasi/quickjs.wasm";
+import { DEFAULT_INTERRUPT_BUDGET, InlineCodemodeSandbox, } from "./runtime/inline.js";
+import { serveCodemodeRemote } from "./runtime/remote.js";
+export * from "./portable.js";
+// Wrangler's `CompiledWasm` rule makes this a compiled module; the declaration cannot say so (see
+// cloudflare-modules.d.ts).
+const quickjsWasm = quickjsWasmImport;
+/** Default VM memory limit of {@link CodemodeSandboxDurableObject}. Isolates have 128 MB in total. */
+export const DEFAULT_REMOTE_MEMORY_LIMIT_BYTES = 32 * 1024 * 1024;
+/** `quickjs-wasi/quickjs.wasm`, compiled by Wrangler. */
+export const cloudflareQuickJSWasm = quickjsWasm;
+/** `InlineCodemodeSandbox` with the QuickJS module Wrangler bundled. */
+export function createInlineCodemodeSandbox(options = {}) {
+    return new InlineCodemodeSandbox({ ...options, wasm: quickjsWasm });
+}
+/**
+ * The remote end of `RemoteCodemodeSandbox`: a Durable Object whose one RPC method runs a script's
+ * VM and calls back into the client for every tool call.
+ *
+ * Deploy it as its own Worker and bind it from the Worker that runs your agent with `script_name`.
+ * A separate Worker is what keeps scripts off the agent's thread: a class in the same Worker can
+ * share an isolate, and therefore a thread, with the objects that call it.
+ *
+ * The object keeps no state between executions and never touches storage. Executions that reach
+ * the same instance share its thread: they interleave while they wait on tools, and a script that
+ * computes delays the others. Name instances per session (`getByName(sessionId)`) to keep one
+ * session's scripts together, or per execution for full independence.
+ *
+ * Limits apply to every request, whatever the client asks for. Override the fields in a subclass:
+ *
+ *     export class CodemodeSandbox extends CodemodeSandboxDurableObject {
+ *       protected maxInterruptBudget = 200_000;
+ *     }
+ */
+export class CodemodeSandboxDurableObject extends DurableObject {
+    /** Interrupt polls per execution; the client may only ask for less. See `InlineCodemodeSandboxOptions`. */
+    maxInterruptBudget = DEFAULT_INTERRUPT_BUDGET;
+    /** VM memory per execution; the client may only ask for less. */
+    maxMemoryLimitBytes = DEFAULT_REMOTE_MEMORY_LIMIT_BYTES;
+    /** Called by `RemoteCodemodeSandbox` over RPC. Resolves when the script has settled or was stopped. */
+    execute(request, exchange) {
+        return serveCodemodeRemote(request, exchange, {
+            wasm: quickjsWasm,
+            maxInterruptBudget: this.maxInterruptBudget,
+            maxMemoryLimitBytes: this.maxMemoryLimitBytes,
+        });
+    }
+}
+//# sourceMappingURL=cloudflare.js.map

package/dist/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../src/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,iBAAiB,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EACN,wBAAwB,EACxB,qBAAqB,GAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAA2D,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAGnH,cAAc,eAAe,CAAC;AAE9B,kGAAkG;AAClG,4BAA4B;AAC5B,MAAM,WAAW,GAAG,iBAAkD,CAAC;AAEvE,sGAAsG;AACtG,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAElE,yDAAyD;AACzD,MAAM,CAAC,MAAM,qBAAqB,GAAuB,WAAW,CAAC;AAErE,wEAAwE;AACxE,MAAM,UAAU,2BAA2B,CAAC,OAAO,GAA+C,EAAE;IACnG,OAAO,IAAI,qBAAqB,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,4BAA4C,SAAQ,aAAkB;IAClF,2GAA2G;IACjG,kBAAkB,GAAW,wBAAwB,CAAC;IAChE,iEAAiE;IACvD,mBAAmB,GAAW,iCAAiC,CAAC;IAE1E,uGAAuG;IACvG,OAAO,CAAC,OAA8B,EAAE,QAAgC;QACvE,OAAO,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;YAC3C,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;SAC7C,CAAC,CAAC;IACJ,CAAC;CACD","sourcesContent":["/**\n * Cloudflare Workers entry, for Workers built with Wrangler.\n *\n * Wrangler's default `CompiledWasm` rule turns the `.wasm` import below into a\n * `WebAssembly.Module`; Workers cannot compile WebAssembly from bytes at runtime. Other bundlers\n * do not support the import: use `@ny4n/codemode/portable` with your own module there.\n *\n * Two ways to run codemode on Cloudflare:\n * - `RemoteCodemodeSandbox` with a {@link CodemodeSandboxDurableObject} deployed as its own\n *   Worker: scripts run in a separate isolate and never block the caller. Use this from a Durable\n *   Object that serves a session.\n * - {@link createInlineCodemodeSandbox}: scripts run on the caller's thread. Simplest; a script\n *   that computes blocks the caller until it awaits a tool or uses up its interrupt budget.\n */\nimport { DurableObject } from \"cloudflare:workers\";\nimport quickjsWasmImport from \"quickjs-wasi/quickjs.wasm\";\nimport {\n\tDEFAULT_INTERRUPT_BUDGET,\n\tInlineCodemodeSandbox,\n\ttype InlineCodemodeSandboxOptions,\n} from \"./runtime/inline.ts\";\nimport { type CodemodeRemoteExchange, type CodemodeRemoteRequest, serveCodemodeRemote } from \"./runtime/remote.ts\";\nimport type { CodemodeWasmModule } from \"./wasm.ts\";\n\nexport * from \"./portable.ts\";\n\n// Wrangler's `CompiledWasm` rule makes this a compiled module; the declaration cannot say so (see\n// cloudflare-modules.d.ts).\nconst quickjsWasm = quickjsWasmImport as unknown as CodemodeWasmModule;\n\n/** Default VM memory limit of {@link CodemodeSandboxDurableObject}. Isolates have 128 MB in total. */\nexport const DEFAULT_REMOTE_MEMORY_LIMIT_BYTES = 32 * 1024 * 1024;\n\n/** `quickjs-wasi/quickjs.wasm`, compiled by Wrangler. */\nexport const cloudflareQuickJSWasm: CodemodeWasmModule = quickjsWasm;\n\n/** `InlineCodemodeSandbox` with the QuickJS module Wrangler bundled. */\nexport function createInlineCodemodeSandbox(options: Omit<InlineCodemodeSandboxOptions, \"wasm\"> = {}) {\n\treturn new InlineCodemodeSandbox({ ...options, wasm: quickjsWasm });\n}\n\n/**\n * The remote end of `RemoteCodemodeSandbox`: a Durable Object whose one RPC method runs a script's\n * VM and calls back into the client for every tool call.\n *\n * Deploy it as its own Worker and bind it from the Worker that runs your agent with `script_name`.\n * A separate Worker is what keeps scripts off the agent's thread: a class in the same Worker can\n * share an isolate, and therefore a thread, with the objects that call it.\n *\n * The object keeps no state between executions and never touches storage. Executions that reach\n * the same instance share its thread: they interleave while they wait on tools, and a script that\n * computes delays the others. Name instances per session (`getByName(sessionId)`) to keep one\n * session's scripts together, or per execution for full independence.\n *\n * Limits apply to every request, whatever the client asks for. Override the fields in a subclass:\n *\n *     export class CodemodeSandbox extends CodemodeSandboxDurableObject {\n *       protected maxInterruptBudget = 200_000;\n *     }\n */\nexport class CodemodeSandboxDurableObject<Env = unknown> extends DurableObject<Env> {\n\t/** Interrupt polls per execution; the client may only ask for less. See `InlineCodemodeSandboxOptions`. */\n\tprotected maxInterruptBudget: number = DEFAULT_INTERRUPT_BUDGET;\n\t/** VM memory per execution; the client may only ask for less. */\n\tprotected maxMemoryLimitBytes: number = DEFAULT_REMOTE_MEMORY_LIMIT_BYTES;\n\n\t/** Called by `RemoteCodemodeSandbox` over RPC. Resolves when the script has settled or was stopped. */\n\texecute(request: CodemodeRemoteRequest, exchange: CodemodeRemoteExchange): Promise<void> {\n\t\treturn serveCodemodeRemote(request, exchange, {\n\t\t\twasm: quickjsWasm,\n\t\t\tmaxInterruptBudget: this.maxInterruptBudget,\n\t\t\tmaxMemoryLimitBytes: this.maxMemoryLimitBytes,\n\t\t});\n\t}\n}\n"]}

package/dist/declarations.d.ts

@@ -0,0 +1,58 @@
+import { toCodemodeIdentifier } from "./identifier.ts";
+export { toCodemodeIdentifier };
+import type { CodemodeJsonSchema, CodemodeTool } from "./types.ts";
+/** Largest rendered input type, in characters, before it becomes `unknown`. */
+export declare const DEFAULT_INPUT_SCHEMA_MAX_CHARS = 16000;
+/**
+ * TypeScript types for MCP results, from the MCP `CallToolResult` schema, so `CallToolResult<T>`
+ * declarations can refer to them.
+ */
+export declare const MCP_TYPESCRIPT_PREAMBLE = "type Role = \"user\" | \"assistant\";\ntype MetaObject = Record<string, unknown>;\ntype Annotations = {\n  audience?: Role[];\n  priority?: number;\n  lastModified?: string;\n};\ntype Icon = {\n  src: string;\n  mimeType?: string;\n  sizes?: string[];\n  theme?: \"light\" | \"dark\";\n};\ntype TextResourceContents = {\n  uri: string;\n  mimeType?: string;\n  _meta?: MetaObject;\n  text: string;\n};\ntype BlobResourceContents = {\n  uri: string;\n  mimeType?: string;\n  _meta?: MetaObject;\n  blob: string;\n};\ntype TextContent = {\n  type: \"text\";\n  text: string;\n  annotations?: Annotations;\n  _meta?: MetaObject;\n};\ntype ImageContent = {\n  type: \"image\";\n  data: string;\n  mimeType: string;\n  annotations?: Annotations;\n  _meta?: MetaObject;\n};\ntype AudioContent = {\n  type: \"audio\";\n  data: string;\n  mimeType: string;\n  annotations?: Annotations;\n  _meta?: MetaObject;\n};\ntype ResourceLink = {\n  icons?: Icon[];\n  name: string;\n  title?: string;\n  uri: string;\n  description?: string;\n  mimeType?: string;\n  annotations?: Annotations;\n  size?: number;\n  _meta?: MetaObject;\n  type: \"resource_link\";\n};\ntype EmbeddedResource = {\n  type: \"resource\";\n  resource: TextResourceContents | BlobResourceContents;\n  annotations?: Annotations;\n  _meta?: MetaObject;\n};\ntype ContentBlock =\n  | TextContent\n  | ImageContent\n  | AudioContent\n  | ResourceLink\n  | EmbeddedResource;\ntype CallToolResult<TStructured = { [key: string]: unknown }> = {\n  _meta?: MetaObject;\n  content: ContentBlock[];\n  isError?: boolean;\n  structuredContent?: TStructured;\n  [key: string]: unknown;\n};";
+export interface RenderDeclarationsOptions {
+    tools?: readonly CodemodeTool[];
+    globals?: readonly CodemodeTool[];
+}
+/**
+ * Render TypeScript declarations for the script-visible API. Tools become members of
+ * `declare const tools`, globals become `declare function` statements, and `ns.member` globals
+ * members of `declare const ns`. Descriptions become doc comments; schemas become types.
+ */
+export declare function renderDeclarations(options: RenderDeclarationsOptions): string;
+/**
+ * One tool as a member of the `tools` object: `name(args: T): Promise<R>;` with the
+ * name as the identifier scripts use. Input types longer than `inputMaxChars` render as `unknown`.
+ * Tools whose output schema is an MCP `CallToolResult` render as `Promise<CallToolResult<T>>`,
+ * which needs {@link MCP_TYPESCRIPT_PREAMBLE}.
+ */
+export declare function renderToolSignature(tool: Pick<CodemodeTool, "name" | "inputSchema" | "outputSchema">, options?: {
+    inputMaxChars?: number;
+}): string;
+/**
+ * A tool's sample: the description followed by the tool's declaration. Used for tool
+ * listings and `ALL_TOOLS` entries.
+ */
+export declare function renderToolSample(tool: Pick<CodemodeTool, "name" | "description" | "inputSchema" | "outputSchema">, options?: {
+    inputMaxChars?: number;
+}): string;
+/**
+ * The `structuredContent` schema of an MCP `CallToolResult` output schema (detected by a
+ * `content` array of objects, boolean `isError`, and object `_meta`), `true` when it declares none, or
+ * `undefined` when the schema is not a `CallToolResult`.
+ */
+export declare function mcpStructuredContentSchema(schema: CodemodeJsonSchema | undefined): CodemodeJsonSchema | undefined;
+/**
+ * The type a tool call resolves to: `CallToolResult<T>` for MCP output schemas (needs
+ * {@link MCP_TYPESCRIPT_PREAMBLE}), the schema's type otherwise, and `unknown` without a schema.
+ */
+export declare function renderToolOutputType(schema: CodemodeJsonSchema | undefined): string;
+/**
+ * Convert a JSON Schema to a TypeScript type expression: objects on one line (`{ a: string; b?: number; }`) with properties sorted by name,
+ * or one property per line with `//` comments when a property has a description; `Array<T>` for
+ * arrays. Local references (`#/$defs/...`, `#/definitions/...`) resolve against `schema`;
+ * recursive and remote references render as `unknown`. A result longer than `maxChars` renders as
+ * `unknown`.
+ */
+export declare function schemaToType(schema: CodemodeJsonSchema, options?: {
+    maxChars?: number;
+}): string;
+//# sourceMappingURL=declarations.d.ts.map

package/dist/declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarations.d.ts","sourceRoot":"","sources":["../src/declarations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAInE,+EAA+E;AAC/E,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAIrD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,ymDA2EjC,CAAC;AAEJ,MAAM,WAAW,yBAAyB;IACzC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,CAyB7E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,CAAC,EACjE,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACtC,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,GAAG,cAAc,CAAC,EACjF,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACtC,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CASjH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAOnF;AAiCD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAGpG"}