@cloudflare/codemode 0.0.8 → 0.1.0

package/src/tool.ts

@@ -0,0 +1,131 @@
+import { tool, type Tool } from "ai";
+import { z } from "zod";
+import type { ToolSet } from "ai";
+import * as acorn from "acorn";
+import { generateTypes, sanitizeToolName, type ToolDescriptors } from "./types";
+import type { Executor } from "./executor";
+
+const DEFAULT_DESCRIPTION = `Execute code to achieve a goal.
+
+Available:
+{{types}}
+
+Write an async arrow function that returns the result.
+Do NOT define named functions then call them — just write the arrow function body directly.
+
+Example: async () => { const r = await codemode.searchWeb({ query: "test" }); return r; }`;
+
+export interface CreateCodeToolOptions {
+  tools: ToolDescriptors | ToolSet;
+  executor: Executor;
+  /**
+   * Custom tool description. Use {{types}} as a placeholder for the generated type definitions.
+   */
+  description?: string;
+}
+
+const codeSchema = z.object({
+  code: z.string().describe("JavaScript async arrow function to execute")
+});
+
+type CodeInput = z.infer<typeof codeSchema>;
+type CodeOutput = { code: string; result: unknown; logs?: string[] };
+
+function normalizeCode(code: string): string {
+  const trimmed = code.trim();
+  if (!trimmed) return "async () => {}";
+
+  try {
+    const ast = acorn.parse(trimmed, {
+      ecmaVersion: "latest",
+      sourceType: "module"
+    });
+
+    // Already an arrow function — pass through
+    if (ast.body.length === 1 && ast.body[0].type === "ExpressionStatement") {
+      const expr = (ast.body[0] as acorn.ExpressionStatement).expression;
+      if (expr.type === "ArrowFunctionExpression") return trimmed;
+    }
+
+    // Last statement is expression → splice in return
+    const last = ast.body[ast.body.length - 1];
+    if (last?.type === "ExpressionStatement") {
+      const exprStmt = last as acorn.ExpressionStatement;
+      const before = trimmed.slice(0, last.start);
+      const exprText = trimmed.slice(
+        exprStmt.expression.start,
+        exprStmt.expression.end
+      );
+      return `async () => {\n${before}return (${exprText})\n}`;
+    }
+
+    return `async () => {\n${trimmed}\n}`;
+  } catch {
+    return `async () => {\n${trimmed}\n}`;
+  }
+}
+
+/**
+ * Create a codemode tool that allows LLMs to write and execute code
+ * with access to your tools in a sandboxed environment.
+ *
+ * Returns an AI SDK compatible tool.
+ */
+function hasNeedsApproval(t: Record<string, unknown>): boolean {
+  return "needsApproval" in t && t.needsApproval != null;
+}
+
+export function createCodeTool(
+  options: CreateCodeToolOptions
+): Tool<CodeInput, CodeOutput> {
+  const tools: ToolDescriptors | ToolSet = {};
+  for (const [name, t] of Object.entries(options.tools)) {
+    if (!hasNeedsApproval(t as Record<string, unknown>)) {
+      (tools as Record<string, unknown>)[name] = t;
+    }
+  }
+
+  const types = generateTypes(tools);
+  const executor = options.executor;
+
+  const description = (options.description ?? DEFAULT_DESCRIPTION).replace(
+    "{{types}}",
+    types
+  );
+
+  return tool({
+    description,
+    inputSchema: codeSchema,
+    execute: async ({ code }) => {
+      // Extract execute functions from tools, keyed by name
+      const fns: Record<string, (...args: unknown[]) => Promise<unknown>> = {};
+
+      for (const [name, t] of Object.entries(tools)) {
+        const execute =
+          "execute" in t
+            ? (t.execute as (args: unknown) => Promise<unknown>)
+            : undefined;
+        if (execute) {
+          fns[sanitizeToolName(name)] = execute;
+        }
+      }
+
+      const normalizedCode = normalizeCode(code);
+
+      const executeResult = await executor.execute(normalizedCode, fns);
+
+      if (executeResult.error) {
+        const logCtx = executeResult.logs?.length
+          ? `\n\nConsole output:\n${executeResult.logs.join("\n")}`
+          : "";
+        throw new Error(
+          `Code execution failed: ${executeResult.error}${logCtx}`
+        );
+      }
+
+      const output: CodeOutput = { code, result: executeResult.result };
+      if (executeResult.logs) output.logs = executeResult.logs;
+      return output;
+    }
+  });
+}

package/src/types.ts

@@ -0,0 +1,202 @@
+import {
+  zodToTs,
+  printNode as printNodeZodToTs,
+  createTypeAlias,
+  createAuxiliaryTypeStore
+} from "zod-to-ts";
+import type { ZodType } from "zod";
+import type { ToolSet } from "ai";
+
+const JS_RESERVED = new Set([
+  "abstract",
+  "arguments",
+  "await",
+  "boolean",
+  "break",
+  "byte",
+  "case",
+  "catch",
+  "char",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "double",
+  "else",
+  "enum",
+  "eval",
+  "export",
+  "extends",
+  "false",
+  "final",
+  "finally",
+  "float",
+  "for",
+  "function",
+  "goto",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "int",
+  "interface",
+  "let",
+  "long",
+  "native",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "short",
+  "static",
+  "super",
+  "switch",
+  "synchronized",
+  "this",
+  "throw",
+  "throws",
+  "transient",
+  "true",
+  "try",
+  "typeof",
+  "undefined",
+  "var",
+  "void",
+  "volatile",
+  "while",
+  "with",
+  "yield"
+]);
+
+/**
+ * Sanitize a tool name into a valid JavaScript identifier.
+ * Replaces hyphens, dots, and spaces with `_`, strips other invalid chars,
+ * prefixes digit-leading names with `_`, and appends `_` to JS reserved words.
+ */
+export function sanitizeToolName(name: string): string {
+  if (!name) return "_";
+
+  // Replace common separators with underscores
+  let sanitized = name.replace(/[-.\s]/g, "_");
+
+  // Strip any remaining non-identifier characters
+  sanitized = sanitized.replace(/[^a-zA-Z0-9_$]/g, "");
+
+  if (!sanitized) return "_";
+
+  // Prefix with _ if starts with a digit
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  // Append _ to reserved words
+  if (JS_RESERVED.has(sanitized)) {
+    sanitized = sanitized + "_";
+  }
+
+  return sanitized;
+}
+
+function toCamelCase(str: string) {
+  return str
+    .replace(/_([a-z])/g, (_, letter) => letter.toUpperCase())
+    .replace(/^[a-z]/, (letter) => letter.toUpperCase());
+}
+
+/**
+ * Extract field descriptions from a Zod object schema's `.shape`, if available.
+ * Returns an array of `@param input.fieldName - description` lines.
+ */
+function extractParamDescriptions(schema: ZodType): string[] {
+  const descriptions: string[] = [];
+  const shape = (schema as { shape?: Record<string, ZodType> }).shape;
+  if (!shape || typeof shape !== "object") return descriptions;
+
+  for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+    const desc = (fieldSchema as { description?: string }).description;
+    if (desc) {
+      descriptions.push(`@param input.${fieldName} - ${desc}`);
+    }
+  }
+  return descriptions;
+}
+
+export interface ToolDescriptor {
+  description?: string;
+  inputSchema: ZodType;
+  outputSchema?: ZodType;
+  execute?: (args: unknown) => Promise<unknown>;
+}
+
+export type ToolDescriptors = Record<string, ToolDescriptor>;
+
+/**
+ * Generate TypeScript type definitions from tool descriptors or an AI SDK ToolSet.
+ * These types can be included in tool descriptions to help LLMs write correct code.
+ */
+export function generateTypes(tools: ToolDescriptors | ToolSet): string {
+  let availableTools = "";
+  let availableTypes = "";
+
+  const auxiliaryTypeStore = createAuxiliaryTypeStore();
+
+  for (const [toolName, tool] of Object.entries(tools)) {
+    // Handle both our ToolDescriptor and AI SDK Tool types
+    const inputSchema =
+      "inputSchema" in tool ? tool.inputSchema : tool.parameters;
+    const outputSchema = "outputSchema" in tool ? tool.outputSchema : undefined;
+    const description = tool.description;
+
+    const safeName = sanitizeToolName(toolName);
+
+    const inputType = printNodeZodToTs(
+      createTypeAlias(
+        zodToTs(inputSchema as ZodType, { auxiliaryTypeStore }).node,
+        `${toCamelCase(safeName)}Input`
+      )
+    );
+
+    const outputType = outputSchema
+      ? printNodeZodToTs(
+          createTypeAlias(
+            zodToTs(outputSchema as ZodType, { auxiliaryTypeStore }).node,
+            `${toCamelCase(safeName)}Output`
+          )
+        )
+      : `type ${toCamelCase(safeName)}Output = unknown`;
+
+    availableTypes += `\n${inputType.trim()}`;
+    availableTypes += `\n${outputType.trim()}`;
+
+    // Build JSDoc comment with description and param descriptions
+    const paramDescs = extractParamDescriptions(inputSchema as ZodType);
+    const jsdocLines: string[] = [];
+    if (description?.trim()) {
+      jsdocLines.push(description.trim());
+    } else {
+      jsdocLines.push(toolName);
+    }
+    for (const pd of paramDescs) {
+      jsdocLines.push(pd);
+    }
+
+    const jsdocBody = jsdocLines.map((l) => `\t * ${l}`).join("\n");
+    availableTools += `\n\t/**\n${jsdocBody}\n\t */`;
+    availableTools += `\n\t${safeName}: (input: ${toCamelCase(safeName)}Input) => Promise<${toCamelCase(safeName)}Output>;`;
+    availableTools += "\n";
+  }
+
+  availableTools = `\ndeclare const codemode: {${availableTools}}`;
+
+  return `
+${availableTypes}
+${availableTools}
+  `.trim();
+}

package/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    name: "workers",
+    include: ["src/tests/**/*.test.ts"],
+    poolOptions: {
+      workers: {
+        isolatedStorage: false,
+        singleWorker: true,
+        wrangler: {
+          configPath: "./wrangler.jsonc"
+        }
+      }
+    }
+  }
+});

package/wrangler.jsonc

@@ -0,0 +1,16 @@
+{
+  "compatibility_date": "2026-01-28",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "enable_nodejs_tty_module",
+    "enable_nodejs_fs_module",
+    "enable_nodejs_http_modules",
+    "enable_nodejs_perf_hooks_module"
+  ],
+  "worker_loaders": [
+    {
+      "binding": "LOADER"
+    }
+  ],
+  "main": "src/index.ts"
+}