@cloudflare/codemode 0.0.8 → 0.1.0

package/src/executor.ts

@@ -0,0 +1,170 @@
+/**
+ * Executor interface and DynamicWorkerExecutor implementation.
+ *
+ * The Executor interface is the core abstraction — implement it to run
+ * LLM-generated code in any sandbox (Workers, QuickJS, Node VM, etc.).
+ */
+
+import { RpcTarget } from "cloudflare:workers";
+
+export interface ExecuteResult {
+  result: unknown;
+  error?: string;
+  logs?: string[];
+}
+
+/**
+ * An executor runs LLM-generated code in a sandbox, making the provided
+ * tool functions callable as `codemode.*` inside the sandbox.
+ *
+ * Implementations should never throw — errors are returned in `ExecuteResult.error`.
+ */
+export interface Executor {
+  execute(
+    code: string,
+    fns: Record<string, (...args: unknown[]) => Promise<unknown>>
+  ): Promise<ExecuteResult>;
+}
+
+// -- ToolDispatcher (RPC target for tool calls from sandboxed Workers) --
+
+/**
+ * An RpcTarget that dispatches tool calls from the sandboxed Worker
+ * back to the host. Passed via Workers RPC to the dynamic Worker's
+ * evaluate() method — no globalOutbound or Fetcher bindings needed.
+ */
+export class ToolDispatcher extends RpcTarget {
+  #fns: Record<string, (...args: unknown[]) => Promise<unknown>>;
+
+  constructor(fns: Record<string, (...args: unknown[]) => Promise<unknown>>) {
+    super();
+    this.#fns = fns;
+  }
+
+  async call(name: string, argsJson: string): Promise<string> {
+    const fn = this.#fns[name];
+    if (!fn) {
+      return JSON.stringify({ error: `Tool "${name}" not found` });
+    }
+    try {
+      const args = argsJson ? JSON.parse(argsJson) : {};
+      const result = await fn(args);
+      return JSON.stringify({ result });
+    } catch (err) {
+      return JSON.stringify({
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+}
+
+// -- DynamicWorkerExecutor (Cloudflare Workers) --
+
+export interface DynamicWorkerExecutorOptions {
+  loader: WorkerLoader;
+  /**
+   * Timeout in milliseconds for code execution. Defaults to 30000 (30s).
+   */
+  timeout?: number;
+  /**
+   * Controls outbound network access from sandboxed code.
+   * - `null` (default): fetch() and connect() throw — sandbox is fully isolated.
+   * - `undefined`: inherits parent Worker's network access (full internet).
+   * - A `Fetcher`: all outbound requests route through this handler.
+   */
+  globalOutbound?: Fetcher | null;
+}
+
+/**
+ * Executes code in an isolated Cloudflare Worker via WorkerLoader.
+ * Tool calls are dispatched via Workers RPC — the host passes a
+ * ToolDispatcher (RpcTarget) to the Worker's evaluate() method.
+ *
+ * External fetch() and connect() are blocked by default via
+ * `globalOutbound: null` (runtime-enforced). Pass a Fetcher to
+ * `globalOutbound` to allow controlled outbound access.
+ */
+export class DynamicWorkerExecutor implements Executor {
+  #loader: WorkerLoader;
+  #timeout: number;
+  #globalOutbound: Fetcher | null;
+
+  constructor(options: DynamicWorkerExecutorOptions) {
+    this.#loader = options.loader;
+    this.#timeout = options.timeout ?? 30000;
+    this.#globalOutbound = options.globalOutbound ?? null;
+  }
+
+  async execute(
+    code: string,
+    fns: Record<string, (...args: unknown[]) => Promise<unknown>>
+  ): Promise<ExecuteResult> {
+    const timeoutMs = this.#timeout;
+
+    const modulePrefix = [
+      'import { WorkerEntrypoint } from "cloudflare:workers";',
+      "",
+      "export default class CodeExecutor extends WorkerEntrypoint {",
+      "  async evaluate(dispatcher) {",
+      "    const __logs = [];",
+      '    console.log = (...a) => { __logs.push(a.map(String).join(" ")); };',
+      '    console.warn = (...a) => { __logs.push("[warn] " + a.map(String).join(" ")); };',
+      '    console.error = (...a) => { __logs.push("[error] " + a.map(String).join(" ")); };',
+      "    const codemode = new Proxy({}, {",
+      "      get: (_, toolName) => async (args) => {",
+      "        const resJson = await dispatcher.call(String(toolName), JSON.stringify(args ?? {}));",
+      "        const data = JSON.parse(resJson);",
+      "        if (data.error) throw new Error(data.error);",
+      "        return data.result;",
+      "      }",
+      "    });",
+      "",
+      "    try {",
+      "      const result = await Promise.race([",
+      "        ("
+    ].join("\n");
+
+    const moduleSuffix = [
+      ")(),",
+      '        new Promise((_, reject) => setTimeout(() => reject(new Error("Execution timed out")), ' +
+        timeoutMs +
+        "))",
+      "      ]);",
+      "      return { result, logs: __logs };",
+      "    } catch (err) {",
+      "      return { result: undefined, error: err.message, logs: __logs };",
+      "    }",
+      "  }",
+      "}"
+    ].join("\n");
+
+    const executorModule = modulePrefix + code + moduleSuffix;
+
+    const dispatcher = new ToolDispatcher(fns);
+
+    const worker = this.#loader.get(`codemode-${crypto.randomUUID()}`, () => ({
+      compatibilityDate: "2025-06-01",
+      compatibilityFlags: ["nodejs_compat"],
+      mainModule: "executor.js",
+      modules: {
+        "executor.js": executorModule
+      },
+      globalOutbound: this.#globalOutbound
+    }));
+
+    const entrypoint = worker.getEntrypoint() as unknown as {
+      evaluate(dispatcher: ToolDispatcher): Promise<{
+        result: unknown;
+        error?: string;
+        logs?: string[];
+      }>;
+    };
+    const response = await entrypoint.evaluate(dispatcher);
+
+    if (response.error) {
+      return { result: undefined, error: response.error, logs: response.logs };
+    }
+
+    return { result: response.result, logs: response.logs };
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export {
+  DynamicWorkerExecutor,
+  ToolDispatcher,
+  type DynamicWorkerExecutorOptions,
+  type Executor,
+  type ExecuteResult
+} from "./executor";
+export {
+  generateTypes,
+  sanitizeToolName,
+  type ToolDescriptor,
+  type ToolDescriptors
+} from "./types";

package/src/tests/cloudflare-test.d.ts

@@ -0,0 +1,5 @@
+declare module "cloudflare:test" {
+  interface ProvidedEnv {
+    LOADER: WorkerLoader;
+  }
+}

package/src/tests/executor.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Tests for the Executor interface contract and DynamicWorkerExecutor.
+ *
+ * Uses vitest-pool-workers — tests run inside a real Workers runtime
+ * with a real WorkerLoader binding, no mocks needed.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { env } from "cloudflare:test";
+import { DynamicWorkerExecutor, ToolDispatcher } from "../executor";
+
+type ToolFns = Record<string, (...args: unknown[]) => Promise<unknown>>;
+
+describe("ToolDispatcher", () => {
+  it("should dispatch tool calls and return JSON result", async () => {
+    const double = vi.fn(async (...args: unknown[]) => {
+      const input = args[0] as Record<string, unknown>;
+      return { doubled: (input.n as number) * 2 };
+    });
+    const fns: ToolFns = { double };
+    const dispatcher = new ToolDispatcher(fns);
+
+    const resJson = await dispatcher.call("double", JSON.stringify({ n: 5 }));
+    const data = JSON.parse(resJson);
+
+    expect(data.result).toEqual({ doubled: 10 });
+    expect(double).toHaveBeenCalledWith({ n: 5 });
+  });
+
+  it("should return error for unknown tool", async () => {
+    const dispatcher = new ToolDispatcher({});
+
+    const resJson = await dispatcher.call("nonexistent", "{}");
+    const data = JSON.parse(resJson);
+
+    expect(data.error).toContain("nonexistent");
+  });
+
+  it("should return error when tool function throws", async () => {
+    const fns: ToolFns = {
+      broken: async () => {
+        throw new Error("something broke");
+      }
+    };
+    const dispatcher = new ToolDispatcher(fns);
+
+    const resJson = await dispatcher.call("broken", "{}");
+    const data = JSON.parse(resJson);
+
+    expect(data.error).toBe("something broke");
+  });
+
+  it("should handle empty args string", async () => {
+    const noArgs = vi.fn(async () => "ok");
+    const fns: ToolFns = { noArgs };
+    const dispatcher = new ToolDispatcher(fns);
+
+    const resJson = await dispatcher.call("noArgs", "");
+    const data = JSON.parse(resJson);
+
+    expect(data.result).toBe("ok");
+    expect(noArgs).toHaveBeenCalledWith({});
+  });
+});
+
+describe("DynamicWorkerExecutor", () => {
+  it("should execute simple code that returns a value", async () => {
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute("async () => 42", {});
+    expect(result.result).toBe(42);
+    expect(result.error).toBeUndefined();
+  });
+
+  it("should call tool functions via codemode proxy", async () => {
+    const add = vi.fn(async (...args: unknown[]) => {
+      const input = args[0] as Record<string, unknown>;
+      return (input.a as number) + (input.b as number);
+    });
+    const fns: ToolFns = { add };
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute(
+      "async () => await codemode.add({ a: 3, b: 4 })",
+      fns
+    );
+
+    expect(result.result).toBe(7);
+    expect(add).toHaveBeenCalledWith({ a: 3, b: 4 });
+  });
+
+  it("should handle multiple sequential tool calls", async () => {
+    const getWeather = vi.fn(async () => ({ temp: 72 }));
+    const searchWeb = vi.fn(async (...args: unknown[]) => {
+      const input = args[0] as Record<string, unknown>;
+      return { results: [`news about ${input.query as string}`] };
+    });
+    const fns: ToolFns = { getWeather, searchWeb };
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const code = `async () => {
+      const weather = await codemode.getWeather({});
+      const news = await codemode.searchWeb({ query: "temp " + weather.temp });
+      return { weather, news };
+    }`;
+
+    const result = await executor.execute(code, fns);
+    expect(result.result).toEqual({
+      weather: { temp: 72 },
+      news: { results: ["news about temp 72"] }
+    });
+    expect(getWeather).toHaveBeenCalledTimes(1);
+    expect(searchWeb).toHaveBeenCalledTimes(1);
+  });
+
+  it("should return error when code throws", async () => {
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute(
+      'async () => { throw new Error("boom"); }',
+      {}
+    );
+    expect(result.error).toBe("boom");
+  });
+
+  it("should return error when tool function throws", async () => {
+    const fail = vi.fn(async () => {
+      throw new Error("tool error");
+    });
+    const fns: ToolFns = { fail };
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute(
+      "async () => await codemode.fail({})",
+      fns
+    );
+    expect(result.error).toBe("tool error");
+  });
+
+  it("should handle concurrent tool calls via Promise.all", async () => {
+    const fns: ToolFns = {
+      slow: async (...args: unknown[]) => {
+        const input = args[0] as Record<string, unknown>;
+        return { id: input.id as number };
+      }
+    };
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const code = `async () => {
+      const [a, b, c] = await Promise.all([
+        codemode.slow({ id: 1 }),
+        codemode.slow({ id: 2 }),
+        codemode.slow({ id: 3 })
+      ]);
+      return [a, b, c];
+    }`;
+
+    const result = await executor.execute(code, fns);
+    expect(result.result).toEqual([{ id: 1 }, { id: 2 }, { id: 3 }]);
+  });
+
+  it("should capture console.log output", async () => {
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute(
+      'async () => { console.log("hello"); console.warn("careful"); return "done"; }',
+      {}
+    );
+
+    expect(result.result).toBe("done");
+    expect(result.logs).toContain("hello");
+    expect(result.logs).toContain("[warn] careful");
+  });
+
+  it("should handle code containing backticks and template literals", async () => {
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute(
+      'async () => { return `hello ${"world"}`; }',
+      {}
+    );
+
+    expect(result.result).toBe("hello world");
+  });
+
+  it("should block external fetch by default (globalOutbound: null)", async () => {
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute(
+      'async () => { const r = await fetch("https://example.com"); return r.status; }',
+      {}
+    );
+
+    // fetch should fail because globalOutbound defaults to null
+    expect(result.error).toBeDefined();
+  });
+
+  it("should preserve closures in tool functions", async () => {
+    const secret = "api-key-123";
+    const fns: ToolFns = {
+      getSecret: async () => ({ key: secret })
+    };
+    const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
+
+    const result = await executor.execute(
+      "async () => await codemode.getSecret({})",
+      fns
+    );
+    expect(result.result).toEqual({ key: "api-key-123" });
+  });
+
+  it("should include timeout in execution", async () => {
+    const executor = new DynamicWorkerExecutor({
+      loader: env.LOADER,
+      timeout: 100
+    });
+
+    const result = await executor.execute(
+      "async () => { await new Promise(r => setTimeout(r, 5000)); return 'done'; }",
+      {}
+    );
+
+    expect(result.error).toContain("timed out");
+  });
+});