refactor(codemode): modular SDK — remove internal LLM, add Executor interface

[mattzcarey]

Summary

Rewrites @cloudflare/codemode from a monolithic experimental_codemode() + CodeModeProxy entrypoint into a modular, composable SDK with proper test coverage, documentation, and examples.

What changed

Package (@cloudflare/codemode):

• Delete src/ai.ts — removes experimental_codemode(), CodeModeProxy, the internal LLM call (generateObject with hardcoded gpt-4.1). The package no longer owns an LLM call or model choice.
• New @cloudflare/codemode/ai export — createCodeTool() returns a standard AI SDK Tool. Users wire their own model via streamText/generateText. The /ai subpath isolates the ai peer dependency — the root export (@cloudflare/codemode) contains executor, type generation, and utilities with no ai dependency.
• New Executor interface — minimal execute(code, fns) → ExecuteResult contract. Implement it for any sandbox. Ships DynamicWorkerExecutor for Cloudflare Workers.
• ToolDispatcher replaces CodeModeProxy — both use Workers RPC, but ToolDispatcher is passed as a parameter to evaluate(dispatcher) instead of being injected as an env binding. No service bindings needed.
• globalOutbound: null by default — fetch() and connect() are blocked at the runtime level. Configurable per-executor.
• AST-based code normalization — uses acorn to parse LLM output into async arrow functions. Handles edge cases regex couldn't.
• sanitizeToolName() — converts MCP-style tool names (hyphens, dots) into valid JS identifiers.
• needsApproval filtering — tools with needsApproval are automatically excluded from codemode (both from type generation and the executor). They should be used via standard AI SDK tool calling instead. Full approval support is planned.
• Console capture — console.log/warn/error captured and returned in ExecuteResult.logs.
• Execution timeout — configurable via DynamicWorkerExecutorOptions.timeout (default 30s).
• Build aligned with other packages — fixedExtension: false, skipNodeModulesBundle: true, .js/.d.ts output, require condition in exports.

Tests:

• 55 unit/integration tests — vitest-pool-workers with a real WorkerLoader binding. No mocks. Tests cover executor, tool creation, type generation, code normalization, needsApproval filtering.
• 5 e2e tests — Playwright + wrangler dev with a real AI binding (@cf/zai-org/glm-4.7-flash). Full pipeline: user prompt → LLM generates code → DynamicWorkerExecutor runs it → tools called via RPC → result returned.

Examples:

• Codemode example (examples/codemode/) — rewritten with AIChatAgent + useAgentChat, Kumo design system, @cloudflare/agents-ui (ConnectionIndicator, ModeToggle, PoweredByAgents, ThemeProvider). Settings panel for switching executors. SQLite-backed project management tools.
• Playground demo (examples/playground/) — new Codemode demo under the AI category. Uses AIChatAgent, Kumo components, collapsible tool cards with code/result/console output.

Documentation:

• docs/codemode.md — full rewrite covering createCodeTool, DynamicWorkerExecutor, Executor interface, network isolation, API reference, agent integration, MCP tools, limitations.
• packages/codemode/README.md — updated for the new API with architecture diagram, configuration tables, and usage examples.

Architecture

User message
  → User calls streamText/generateText with their own model + codemode tool
  → LLM generates code
  → DynamicWorkerExecutor spins up dynamic Worker via WorkerLoader
  → ToolDispatcher (extends RpcTarget) passed directly to Worker's evaluate() method
  → Tool calls: codemode.tool() → dispatcher.call(name, args) → RPC back to host

Required wrangler config:

{
  "worker_loaders": [{ "binding": "LOADER" }]
}

One binding (WorkerLoader) instead of three.

The Executor interface

interface Executor {
  execute(
    code: string,
    fns: Record<string, (...args: unknown[]) => Promise<unknown>>
  ): Promise<ExecuteResult>;
}

interface ExecuteResult {
  result: unknown;
  error?: string;
  logs?: string[];
}

Import paths

// AI-dependent (createCodeTool)
import { createCodeTool } from "@cloudflare/codemode/ai";

// AI-independent (executor, types, utilities)
import { DynamicWorkerExecutor, generateTypes, sanitizeToolName } from "@cloudflare/codemode";

Test plan

• npm run test in packages/codemode/ — 55 tests pass (executor, tool, types, needsApproval) via vitest-pool-workers
• npm run test:e2e in packages/codemode/ — 5 e2e tests pass via Playwright + wrangler dev + real AI binding
• npm run build — package builds with clean .js/.d.ts output
• npx tsc --noEmit — no type errors in package, examples, or playground
• Playground builds and type-checks with new Codemode demo
• Codemode example builds and type-checks with AIChatAgent + Kumo

[changeset-bot]

🦋 Changeset detected

Latest commit: d9e8e4c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/codemode	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[threepointone]

if this is ready for review, then please write a PR description that details what this is, what reviewers should look out for, just help me out here haha. Also please add a detailed changeset.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@879

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/ai-chat@879

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/codemode@879

npm i https://pkg.pr.new/cloudflare/agents/hono-agents@879

commit: d9e8e4c

[threepointone]

approving, but please test all the changes I've made

[threepointone]

I updated the PR:

• rewrote the example with kumo and AIChatAgent, expanded README
• added a codemode section to the playground
• rewrote docs/codemode.md
• moved createCodeTool to /ai
• documented a limitation that this won't work with tools with needsApproval (and we'll figure that out later)
• added e2e tests
• some misc cleanups

please test all my changes and try out your example and the playground. tentatively stamping, land when you're happy with it