@cloudflare/codemode 0.0.8 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @cloudflare/codemode
 
+## 0.1.0
+
+### Minor Changes
+
+- [#879](https://github.com/cloudflare/agents/pull/879) [`90e54da`](https://github.com/cloudflare/agents/commit/90e54dab21f7c2c783aac117693918765e8b254b) Thanks [@mattzcarey](https://github.com/mattzcarey)! - Remove experimental_codemode() and CodeModeProxy. Replace with createCodeTool() from @cloudflare/codemode/ai which returns a standard AI SDK Tool. The package no longer owns an LLM call or model choice. Users call streamText/generateText with their own model and pass the codemode tool.
+
+  The AI-dependent export (createCodeTool) is now at @cloudflare/codemode/ai. The root export (@cloudflare/codemode) contains the executor, type generation, and utilities which do not require the ai peer dependency.
+
+  ToolDispatcher (extends RpcTarget) replaces CodeModeProxy (extends WorkerEntrypoint) for dispatching tool calls from the sandbox back to the host. It is passed as a parameter to the dynamic worker's evaluate() method instead of being injected as an env binding, removing the need for CodeModeProxy and globalOutbound service bindings. Only a WorkerLoader binding is required now. globalOutbound on DynamicWorkerExecutor defaults to null which blocks fetch/connect at the runtime level. New Executor interface (execute(code, fns) => ExecuteResult) allows custom sandbox implementations. DynamicWorkerExecutor is the Cloudflare Workers implementation. Console output captured in ExecuteResult.logs. Configurable execution timeout.
+
+  AST-based code normalization via acorn replaces regex. sanitizeToolName() exported for converting MCP-style tool names to valid JS identifiers.
+
+### Patch Changes
+
+- [#954](https://github.com/cloudflare/agents/pull/954) [`943c407`](https://github.com/cloudflare/agents/commit/943c4070992bb836625abb5bf4e3271a6f52f7a2) Thanks [@threepointone](https://github.com/threepointone)! - update dependencies
+
 ## 0.0.8
 
 ### Patch Changes

package/README.md

@@ -1,75 +1,33 @@
-### 💻 `@cloudflare/codemode` - Code Mode: The Better Way to Use MCP
+# `@cloudflare/codemode`
 
-Instead of asking LLMs to call tools directly, Code Mode lets them write executable code that orchestrates multiple operations. **LLMs are better at writing code than calling tools** - they've seen millions of lines of real-world TypeScript but only contrived tool-calling examples.
+Instead of asking LLMs to call tools directly, Code Mode lets them write executable code that orchestrates multiple operations. LLMs are better at writing code than calling tools — they've seen millions of lines of real-world TypeScript but only contrived tool-calling examples.
 
-Code Mode converts your tools (especially MCP servers) into TypeScript APIs, enabling complex workflows, error handling, and multi-step operations that are natural in code but difficult with traditional tool calling.
+Code Mode converts your tools into TypeScript APIs and executes the generated code in secure, isolated sandboxes with millisecond startup times.
 
-Built on Cloudflare's Worker Loader API, Code Mode executes generated code in secure, isolated sandboxes with millisecond startup times.
+> **Experimental** — may have breaking changes. Use with caution in production.
 
-> **⚠️ Experimental Feature**: Code Mode is currently experimental and may have breaking changes in future releases. Use with caution in production environments.
-
----
-
-### 🌱 Installation
+## Installation
 
 ```sh
-npm install @cloudflare/codemode agents ai
+npm install @cloudflare/codemode agents ai zod
 ```
 
-### 📝 Your First Code Mode Agent
-
-Transform your tool-calling agent into a code-generating one:
+## Quick Start
 
-#### Before (Traditional Tool Calling)
+`createCodeTool` takes your tools and an executor, and returns a single AI SDK tool that lets the LLM write code instead of making individual tool calls.
 
 ```ts
-import { streamText } from "ai";
-import { tool } from "ai";
+import { createCodeTool } from "@cloudflare/codemode/ai";
+import { DynamicWorkerExecutor } from "@cloudflare/codemode";
+import { streamText, tool } from "ai";
 import { z } from "zod";
 
-const result = streamText({
-  model: openai("gpt-4o"),
-  messages,
-  tools: {
-    getWeather: tool({
-      description: "Get weather for a location",
-      inputSchema: z.object({ location: z.string() }),
-      execute: async ({ location }) => {
-        return `Weather in ${location}: 72°F, sunny`;
-      }
-    }),
-    sendEmail: tool({
-      description: "Send an email",
-      inputSchema: z.object({
-        to: z.string(),
-        subject: z.string(),
-        body: z.string()
-      }),
-      execute: async ({ to, subject, body }) => {
-        // Send email logic
-        return `Email sent to ${to}`;
-      }
-    })
-  }
-});
-```
-
-#### After (With Code Mode)
-
-```ts
-import { experimental_codemode as codemode } from "@cloudflare/codemode/ai";
-import { streamText } from "ai";
-import { tool } from "ai";
-import { z } from "zod";
-
-// Define your tools as usual
+// 1. Define your tools using the AI SDK tool() wrapper
 const tools = {
   getWeather: tool({
     description: "Get weather for a location",
     inputSchema: z.object({ location: z.string() }),
-    execute: async ({ location }) => {
-      return `Weather in ${location}: 72°F, sunny`;
-    }
+    execute: async ({ location }) => `Weather in ${location}: 72°F, sunny`
   }),
   sendEmail: tool({
     description: "Send an email",
@@ -78,259 +36,228 @@ const tools = {
       subject: z.string(),
       body: z.string()
     }),
-    execute: async ({ to, subject, body }) => {
-      // Send email logic
-      return `Email sent to ${to}`;
-    }
+    execute: async ({ to, subject, body }) => `Email sent to ${to}`
   })
 };
 
-// Configure Code Mode
-const { prompt, tools: wrappedTools } = await codemode({
-  model: openai("gpt-4o"), // optional, defaults to openai("gpt-4.1")
-  prompt: "You are a helpful assistant...",
-  tools,
-  globalOutbound: env.globalOutbound,
-  loader: env.LOADER,
-  proxy: this.ctx.exports.CodeModeProxy({
-    props: {
-      binding: "MyAgent",
-      name: this.name,
-      callback: "callTool"
-    }
-  })
+// 2. Create an executor (runs code in an isolated Worker)
+const executor = new DynamicWorkerExecutor({
+  loader: env.LOADER
 });
 
-// Use the wrapped tools - now the LLM will generate code instead!
+// 3. Create the codemode tool
+const codemode = createCodeTool({ tools, executor });
+
+// 4. Use it with streamText — the LLM writes code that calls your tools
 const result = streamText({
-  model: openai("gpt-4o"),
-  system: prompt,
+  model,
+  system: "You are a helpful assistant.",
   messages,
-  tools: wrappedTools // Single "codemode" tool that generates code
+  tools: { codemode }
 });
 ```
 
-That's it! Your agent now generates executable code that orchestrates your tools.
-
-### 🏰 Configuration
-
-Define the required bindings in your `wrangler.toml`:
+The LLM sees a typed `codemode` object and writes code like:
 
-```jsonc
-{
-  "compatibility_flags": ["experimental", "enable_ctx_exports"],
-  "worker_loaders": [
-    {
-      "binding": "LOADER"
-    }
-  ],
-  "services": [
-    {
-      "binding": "globalOutbound",
-      "service": "your-service",
-      "entrypoint": "globalOutbound"
-    },
-    {
-      "binding": "CodeModeProxy",
-      "service": "your-service",
-      "entrypoint": "CodeModeProxy"
-    }
-  ]
-}
+```js
+async () => {
+  const weather = await codemode.getWeather({ location: "London" });
+  if (weather.includes("sunny")) {
+    await codemode.sendEmail({
+      to: "team@example.com",
+      subject: "Nice day!",
+      body: `It's ${weather}`
+    });
+  }
+  return { weather, notified: true };
+};
 ```
 
-### 🎭 Agent Integration
+## Architecture
 
-#### With MCP Servers
+### How it works
 
-```ts
-import { Agent } from "agents";
-import { experimental_codemode as codemode } from "@cloudflare/codemode/ai";
-import { streamText, convertToModelMessages } from "ai";
-import { openai } from "@ai-sdk/openai";
+```
+┌─────────────┐        ┌──────────────────────────────────────┐
+│             │        │  Dynamic Worker (isolated sandbox)   │
+│  Host       │  RPC   │                                      │
+│  Worker     │◄──────►│  LLM-generated code runs here        │
+│             │        │  codemode.myTool() → dispatcher.call()│
+│  ToolDispatcher      │                                      │
+│  holds tool fns      │  fetch() blocked by default          │
+└─────────────┘        └──────────────────────────────────────┘
+```
 
-export class CodeModeAgent extends Agent<Env> {
-  async onChatMessage() {
-    const allTools = {
-      ...regularTools,
-      ...this.mcp.getAITools() // Include MCP tools
-    };
-
-    const { prompt, tools: wrappedTools } = await codemode({
-      model: openai("gpt-4o"), // optional, defaults to openai("gpt-4.1")
-      prompt: "You are a helpful assistant...",
-      tools: allTools,
-      globalOutbound: env.globalOutbound,
-      loader: env.LOADER,
-      proxy: this.ctx.exports.CodeModeProxy({
-        props: {
-          binding: "CodeModeAgent",
-          name: this.name,
-          callback: "callTool"
-        }
-      })
-    });
+1. `createCodeTool` generates TypeScript type definitions from your tools and builds a description the LLM can read
+2. The LLM writes an async arrow function that calls `codemode.toolName(args)`
+3. Code is normalized via AST parsing (acorn) and sent to the executor
+4. `DynamicWorkerExecutor` spins up an isolated Worker via `WorkerLoader`
+5. Inside the sandbox, a `Proxy` intercepts `codemode.*` calls and routes them back to the host via Workers RPC (`ToolDispatcher extends RpcTarget`)
+6. Console output is captured and returned alongside the result
 
-    const result = streamText({
-      model: openai("gpt-4o"),
-      system: prompt,
-      messages: await convertToModelMessages(this.messages),
-      tools: wrappedTools
-    });
+### Network isolation
 
-    return result.toUIMessageStreamResponse();
-  }
+External `fetch()` and `connect()` are **blocked by default** — enforced at the Workers runtime level via `globalOutbound: null`. Sandboxed code can only interact with the host through `codemode.*` tool calls.
 
-  callTool(functionName: string, args: unknown[]) {
-    return this.tools[functionName]?.execute?.(args, {
-      abortSignal: new AbortController().signal,
-      toolCallId: "codemode",
-      messages: []
-    });
-  }
-}
+To allow controlled outbound access, pass a `Fetcher`:
 
-export { CodeModeProxy } from "@cloudflare/codemode/ai";
+```ts
+const executor = new DynamicWorkerExecutor({
+  loader: env.LOADER,
+  globalOutbound: null // default — fully isolated
+  // globalOutbound: env.MY_OUTBOUND_SERVICE, // route through a Fetcher
+});
 ```
 
-### 🌊 Generated Code Example
-
-Code Mode enables complex workflows that chain multiple operations:
+## The Executor Interface
 
-```javascript
-// Example generated code orchestrating multiple MCP servers:
-async function executeTask() {
-  const files = await codemode.listFiles({ path: "/projects" });
-  const recentProject = files
-    .filter((f) => f.type === "directory")
-    .sort((a, b) => new Date(b.modified) - new Date(a.modified))[0];
+The `Executor` interface is deliberately minimal — implement it to run code in any sandbox:
 
-  const projectStatus = await codemode.queryDatabase({
-    query: "SELECT * FROM projects WHERE name = ?",
-    params: [recentProject.name]
-  });
-
-  if (projectStatus.length === 0 || projectStatus[0].status === "incomplete") {
-    await codemode.createTask({
-      title: `Review project: ${recentProject.name}`,
-      priority: "high"
-    });
-    await codemode.sendEmail({
-      to: "team@company.com",
-      subject: "Project Review Needed"
-    });
-  }
+```ts
+interface Executor {
+  execute(
+    code: string,
+    fns: Record<string, (...args: unknown[]) => Promise<unknown>>
+  ): Promise<ExecuteResult>;
+}
 
-  return { success: true, project: recentProject };
+interface ExecuteResult {
+  result: unknown;
+  error?: string;
+  logs?: string[];
 }
 ```
 
-### 🔒 Security
-
-Code runs in isolated Workers with millisecond startup times. No network access by default - only through explicit bindings. API keys are hidden in bindings, preventing leaks.
+`DynamicWorkerExecutor` is the Cloudflare Workers implementation, but you can build your own for Node VM, QuickJS, containers, or anything else.
 
 ```ts
-export const globalOutbound = {
-  fetch: async (input: string | URL | RequestInfo, init?: RequestInit) => {
-    const url = new URL(typeof input === "string" ? input : input.toString());
-    if (url.hostname === "example.com") {
-      return new Response("Not allowed", { status: 403 });
+// Example: a simple Node VM executor
+class NodeVMExecutor implements Executor {
+  async execute(code, fns): Promise<ExecuteResult> {
+    try {
+      const fn = new AsyncFunction("codemode", `return await (${code})()`);
+      const result = await fn(fns);
+      return { result };
+    } catch (err) {
+      return { result: undefined, error: err.message };
     }
-    return fetch(input, init);
   }
-};
+}
 ```
 
-### 🔧 Setup
+## Configuration
 
-**Required bindings:**
+### Wrangler bindings
 
-- `LOADER`: Worker Loader for code execution
-- `globalOutbound`: Service for network access control
-- `CodeModeProxy`: Service for tool execution proxy
+```jsonc
+// wrangler.jsonc
+{
+  "worker_loaders": [{ "binding": "LOADER" }],
+  "compatibility_flags": ["nodejs_compat"]
+}
+```
 
-**Environment:**
+### DynamicWorkerExecutor options
 
-```ts
-export const globalOutbound = {
-  fetch: async (input: string | URL | RequestInfo, init?: RequestInit) => {
-    // Your security policies
-    return fetch(input, init);
-  }
-};
+| Option           | Type              | Default  | Description                                                  |
+| ---------------- | ----------------- | -------- | ------------------------------------------------------------ |
+| `loader`         | `WorkerLoader`    | required | Worker Loader binding from `env.LOADER`                      |
+| `timeout`        | `number`          | `30000`  | Execution timeout in ms                                      |
+| `globalOutbound` | `Fetcher \| null` | `null`   | Network access control. `null` = blocked, `Fetcher` = routed |
 
-export { CodeModeProxy } from "@cloudflare/codemode/ai";
-```
+### createCodeTool options
 
-**Proxy configuration:**
+| Option        | Type                         | Default        | Description                                            |
+| ------------- | ---------------------------- | -------------- | ------------------------------------------------------ |
+| `tools`       | `ToolSet \| ToolDescriptors` | required       | Your tools (AI SDK `tool()` or raw descriptors)        |
+| `executor`    | `Executor`                   | required       | Where to run the generated code                        |
+| `description` | `string`                     | auto-generated | Custom tool description. Use `{{types}}` for type defs |
 
-```ts
-proxy: this.ctx.exports.CodeModeProxy({
-  props: {
-    binding: "YourAgentClass",
-    name: this.name,
-    callback: "callTool"
-  }
-});
-```
+## Agent Integration
 
-### 🎯 Real-World Examples
+The user sends a message, the agent passes it to an LLM with the codemode tool, and the LLM writes and executes code to fulfill the request.
 
-Explore these examples to see Code Mode in action:
+```ts
+import { Agent } from "agents";
+import { createCodeTool } from "@cloudflare/codemode/ai";
+import { DynamicWorkerExecutor } from "@cloudflare/codemode";
+import { streamText, convertToModelMessages, stepCountIs } from "ai";
 
-- **Complete Demo**: [`examples/codemode/`](../../examples/codemode/) - Full working example with MCP integration
-- **Documentation**: [`docs/codemode.md`](../../docs/codemode.md) - Detailed guide and examples
-- **Blog Post**: [Code Mode: the better way to use MCP](https://blog.cloudflare.com/code-mode/) - Deep dive into the philosophy and implementation
+export class MyAgent extends Agent<Env, State> {
+  async onChatMessage() {
+    const executor = new DynamicWorkerExecutor({
+      loader: this.env.LOADER
+    });
+
+    const codemode = createCodeTool({
+      tools: myTools,
+      executor
+    });
 
-### 📚 API Reference
+    const result = streamText({
+      model,
+      system: "You are a helpful assistant.",
+      messages: await convertToModelMessages(this.state.messages),
+      tools: { codemode },
+      stopWhen: stepCountIs(10)
+    });
 
-#### `experimental_codemode(options)`
+    // Stream response back to client...
+  }
+}
+```
 
-Wraps your tools with Code Mode, converting them into a single code-generating tool.
+### With MCP tools
 
-**Options:**
+MCP tools work the same way — just merge them into the tool set:
 
-- `tools: ToolSet` - Your tool definitions (including MCP tools)
-- `prompt: string` - System prompt for the LLM
-- `globalOutbound: Fetcher` - Service binding for network access control
-- `loader: WorkerLoader` - Worker Loader binding for code execution
-- `proxy: Fetcher<CodeModeProxy>` - Proxy binding for tool execution
-- `model?: LanguageModel` - The language model to use for code generation (optional, defaults to `openai("gpt-4.1")`)
+```ts
+const codemode = createCodeTool({
+  tools: {
+    ...myTools,
+    ...this.mcp.getAITools()
+  },
+  executor
+});
+```
 
-**Returns:**
+## Utilities
 
-- `prompt: string` - Enhanced system prompt
-- `tools: ToolSet` - Wrapped tools (single "codemode" tool)
+### `generateTypes(tools)`
 
-#### `CodeModeProxy`
+Generates TypeScript type definitions from your tools. Used internally by `createCodeTool` but exported for custom use (e.g. displaying types in a frontend).
 
-Worker entrypoint that routes tool calls back to your agent.
+```ts
+import { generateTypes } from "@cloudflare/codemode";
 
-**Props:**
+const types = generateTypes(myTools);
+// Returns TypeScript declarations like:
+// type CreateProjectInput = { name: string; description?: string }
+// declare const codemode: { createProject: (input: CreateProjectInput) => Promise<...>; }
+```
 
-- `binding: string` - Your agent class name
-- `name: string` - Agent instance name
-- `callback: string` - Method name to call for tool execution
+### `sanitizeToolName(name)`
 
-### 🔗 Integration
+Converts tool names into valid JavaScript identifiers. Handles hyphens, dots, digits, reserved words.
 
-`@cloudflare/codemode` integrates with the [`agents`](../agents/) framework and works with any agent that extends `Agent`, including MCP server integration via `Agent.mcp`.
+```ts
+import { sanitizeToolName } from "@cloudflare/codemode";
 
-### 🚀 Limitations
+sanitizeToolName("my-tool"); // "my_tool"
+sanitizeToolName("3d-render"); // "_3d_render"
+sanitizeToolName("delete"); // "delete_"
+```
 
-- **Experimental**: Subject to breaking changes
-- **Requires Cloudflare Workers**: Uses Worker Loader API (beta)
-- **JavaScript Only**: Python support planned
+## Limitations
 
-### Contributing
+- **Tool approval (`needsApproval`) is not supported yet.** Tools with `needsApproval: true` execute immediately inside the sandbox without pausing for approval. Support for approval flows within codemode is planned. For now, do not pass approval-required tools to `createCodeTool` — use them through standard AI SDK tool calling instead.
+- Requires Cloudflare Workers environment for `DynamicWorkerExecutor`
+- Limited to JavaScript execution
 
-Contributions are welcome! Please:
+## Examples
 
-1. Open an issue to discuss your proposal
-2. Ensure your changes align with the package's goals
-3. Include tests for new features
-4. Update documentation as needed
+- [`examples/codemode/`](../../examples/codemode/) — Full working example with task management tools
 
-### License
+## License
 
-MIT licensed. See the LICENSE file at the root of this repository for details.
+MIT

package/dist/ai.d.ts

@@ -1,31 +1,31 @@
-import { LanguageModel, ToolSet } from "ai";
-import { WorkerEntrypoint } from "cloudflare:workers";
+import { i as Executor, s as ToolDescriptors } from "./executor-Czw9jKZH.js";
+import { Tool, ToolSet } from "ai";
+import { z } from "zod";
 
-//#region src/ai.d.ts
-declare class CodeModeProxy extends WorkerEntrypoint<
-  Cloudflare.Env,
-  {
-    binding: string;
-    name: string;
-    callback: string;
-  }
-> {
-  callFunction(options: {
-    functionName: string;
-    args: unknown[];
-  }): Promise<any>;
+//#region src/tool.d.ts
+interface CreateCodeToolOptions {
+  tools: ToolDescriptors | ToolSet;
+  executor: Executor;
+  /**
+   * Custom tool description. Use {{types}} as a placeholder for the generated type definitions.
+   */
+  description?: string;
 }
-declare function experimental_codemode(options: {
-  tools: ToolSet;
-  prompt: string;
-  globalOutbound: Fetcher;
-  loader: WorkerLoader;
-  proxy: Fetcher<CodeModeProxy>;
-  model?: LanguageModel;
-}): Promise<{
-  prompt: string;
-  tools: ToolSet;
-}>;
+declare const codeSchema: z.ZodObject<
+  {
+    code: z.ZodString;
+  },
+  z.core.$strip
+>;
+type CodeInput = z.infer<typeof codeSchema>;
+type CodeOutput = {
+  code: string;
+  result: unknown;
+  logs?: string[];
+};
+declare function createCodeTool(
+  options: CreateCodeToolOptions
+): Tool<CodeInput, CodeOutput>;
 //#endregion
-export { CodeModeProxy, experimental_codemode };
+export { type CreateCodeToolOptions, createCodeTool };
 //# sourceMappingURL=ai.d.ts.map