@tanstack/ai-isolate-cloudflare 0.1.0

package/dist/esm/worker/wrap-code.d.ts

@@ -0,0 +1,13 @@
+import { ToolResultPayload, ToolSchema } from '../types.js';
+/**
+ * Generate tool wrapper code that collects calls or returns cached results.
+ *
+ * Tool calls are identified by a sequential index (__toolCallIdx) rather than
+ * by hashing the input. This avoids mismatches when re-executing code whose
+ * inputs contain non-deterministic values (e.g. random UUIDs).
+ */
+export declare function generateToolWrappers(tools: Array<ToolSchema>, toolResults?: Record<string, ToolResultPayload>): string;
+/**
+ * Wrap user code in an async IIFE with tool wrappers
+ */
+export declare function wrapCode(code: string, tools: Array<ToolSchema>, toolResults?: Record<string, ToolResultPayload>): string;

package/dist/esm/worker/wrap-code.js

@@ -0,0 +1,102 @@
+function generateToolWrappers(tools, toolResults) {
+  const wrappers = [];
+  for (const tool of tools) {
+    if (toolResults) {
+      wrappers.push(`
+        async function ${tool.name}(input) {
+          const callId = 'tc_' + (__toolCallIdx++);
+          const result = __toolResults[callId];
+          if (!result) {
+            __pendingToolCalls.push({ id: callId, name: '${tool.name}', args: input });
+            throw new __ToolCallNeeded(callId);
+          }
+          if (!result.success) {
+            throw new Error(result.error || 'Tool call failed');
+          }
+          return result.value;
+        }
+      `);
+    } else {
+      wrappers.push(`
+        async function ${tool.name}(input) {
+          const callId = 'tc_' + (__toolCallIdx++);
+          __pendingToolCalls.push({ id: callId, name: '${tool.name}', args: input });
+          throw new __ToolCallNeeded(callId);
+        }
+      `);
+    }
+  }
+  return wrappers.join("\n");
+}
+function wrapCode(code, tools, toolResults) {
+  const toolWrappers = generateToolWrappers(tools, toolResults);
+  const toolResultsJson = toolResults ? JSON.stringify(toolResults) : "{}";
+  return `
+    (async function() {
+      // Tool call tracking (sequential index for stable IDs across re-executions)
+      let __toolCallIdx = 0;
+      const __pendingToolCalls = [];
+      const __toolResults = ${toolResultsJson};
+      const __logs = [];
+
+      // Special error class for tool calls
+      class __ToolCallNeeded extends Error {
+        constructor(callId) {
+          super('Tool call needed: ' + callId);
+          this.callId = callId;
+        }
+      }
+
+      // Console capture
+      const console = {
+        log: (...args) => __logs.push(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+        error: (...args) => __logs.push('ERROR: ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+        warn: (...args) => __logs.push('WARN: ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+        info: (...args) => __logs.push('INFO: ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+      };
+
+      // Tool wrappers
+      ${toolWrappers}
+
+      try {
+        // Execute user code
+        const __userResult = await (async function() {
+          ${code}
+        })();
+
+        return {
+          status: 'done',
+          success: true,
+          value: __userResult,
+          logs: __logs
+        };
+      } catch (__error) {
+        if (__error instanceof __ToolCallNeeded) {
+          // Tool calls needed - return pending calls
+          return {
+            status: 'need_tools',
+            toolCalls: __pendingToolCalls,
+            logs: __logs
+          };
+        }
+
+        // Regular error
+        return {
+          status: 'done',
+          success: false,
+          error: {
+            name: __error.name || 'Error',
+            message: __error.message || String(__error),
+            stack: __error.stack
+          },
+          logs: __logs
+        };
+      }
+    })()
+  `;
+}
+export {
+  generateToolWrappers,
+  wrapCode
+};
+//# sourceMappingURL=wrap-code.js.map

package/dist/esm/worker/wrap-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-code.js","sources":["../../../src/worker/wrap-code.ts"],"sourcesContent":["/**\n * Code wrapping utilities for the Cloudflare Worker.\n * Extracted for testability without UNSAFE_EVAL.\n */\n\nimport type { ToolResultPayload, ToolSchema } from '../types'\n\n/**\n * Generate tool wrapper code that collects calls or returns cached results.\n *\n * Tool calls are identified by a sequential index (__toolCallIdx) rather than\n * by hashing the input. This avoids mismatches when re-executing code whose\n * inputs contain non-deterministic values (e.g. random UUIDs).\n */\nexport function generateToolWrappers(\n  tools: Array<ToolSchema>,\n  toolResults?: Record<string, ToolResultPayload>,\n): string {\n  const wrappers: Array<string> = []\n\n  for (const tool of tools) {\n    if (toolResults) {\n      wrappers.push(`\n        async function ${tool.name}(input) {\n          const callId = 'tc_' + (__toolCallIdx++);\n          const result = __toolResults[callId];\n          if (!result) {\n            __pendingToolCalls.push({ id: callId, name: '${tool.name}', args: input });\n            throw new __ToolCallNeeded(callId);\n          }\n          if (!result.success) {\n            throw new Error(result.error || 'Tool call failed');\n          }\n          return result.value;\n        }\n      `)\n    } else {\n      wrappers.push(`\n        async function ${tool.name}(input) {\n          const callId = 'tc_' + (__toolCallIdx++);\n          __pendingToolCalls.push({ id: callId, name: '${tool.name}', args: input });\n          throw new __ToolCallNeeded(callId);\n        }\n      `)\n    }\n  }\n\n  return wrappers.join('\\n')\n}\n\n/**\n * Wrap user code in an async IIFE with tool wrappers\n */\nexport function wrapCode(\n  code: string,\n  tools: Array<ToolSchema>,\n  toolResults?: Record<string, ToolResultPayload>,\n): string {\n  const toolWrappers = generateToolWrappers(tools, toolResults)\n  const toolResultsJson = toolResults ? JSON.stringify(toolResults) : '{}'\n\n  return `\n    (async function() {\n      // Tool call tracking (sequential index for stable IDs across re-executions)\n      let __toolCallIdx = 0;\n      const __pendingToolCalls = [];\n      const __toolResults = ${toolResultsJson};\n      const __logs = [];\n\n      // Special error class for tool calls\n      class __ToolCallNeeded extends Error {\n        constructor(callId) {\n          super('Tool call needed: ' + callId);\n          this.callId = callId;\n        }\n      }\n\n      // Console capture\n      const console = {\n        log: (...args) => __logs.push(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),\n        error: (...args) => __logs.push('ERROR: ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),\n        warn: (...args) => __logs.push('WARN: ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),\n        info: (...args) => __logs.push('INFO: ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),\n      };\n\n      // Tool wrappers\n      ${toolWrappers}\n\n      try {\n        // Execute user code\n        const __userResult = await (async function() {\n          ${code}\n        })();\n\n        return {\n          status: 'done',\n          success: true,\n          value: __userResult,\n          logs: __logs\n        };\n      } catch (__error) {\n        if (__error instanceof __ToolCallNeeded) {\n          // Tool calls needed - return pending calls\n          return {\n            status: 'need_tools',\n            toolCalls: __pendingToolCalls,\n            logs: __logs\n          };\n        }\n\n        // Regular error\n        return {\n          status: 'done',\n          success: false,\n          error: {\n            name: __error.name || 'Error',\n            message: __error.message || String(__error),\n            stack: __error.stack\n          },\n          logs: __logs\n        };\n      }\n    })()\n  `\n}\n"],"names":[],"mappings":"AAcO,SAAS,qBACd,OACA,aACQ;AACR,QAAM,WAA0B,CAAA;AAEhC,aAAW,QAAQ,OAAO;AACxB,QAAI,aAAa;AACf,eAAS,KAAK;AAAA,yBACK,KAAK,IAAI;AAAA;AAAA;AAAA;AAAA,2DAIyB,KAAK,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,OAQ7D;AAAA,IACH,OAAO;AACL,eAAS,KAAK;AAAA,yBACK,KAAK,IAAI;AAAA;AAAA,yDAEuB,KAAK,IAAI;AAAA;AAAA;AAAA,OAG3D;AAAA,IACH;AAAA,EACF;AAEA,SAAO,SAAS,KAAK,IAAI;AAC3B;AAKO,SAAS,SACd,MACA,OACA,aACQ;AACR,QAAM,eAAe,qBAAqB,OAAO,WAAW;AAC5D,QAAM,kBAAkB,cAAc,KAAK,UAAU,WAAW,IAAI;AAEpE,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA,8BAKqB,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAoBrC,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA,YAKR,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiChB;"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@tanstack/ai-isolate-cloudflare",
+  "version": "0.1.0",
+  "description": "Cloudflare Workers driver for TanStack AI Code Mode - execute code on the edge",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-isolate-cloudflare"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./worker": {
+      "types": "./dist/esm/worker/index.d.ts",
+      "import": "./dist/esm/worker/index.js"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src",
+    "worker",
+    "wrangler.toml"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "dev:worker": "node dev-server.mjs",
+    "deploy:worker": "wrangler deploy",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "code-mode",
+    "cloudflare",
+    "workers",
+    "edge",
+    "isolate"
+  ],
+  "dependencies": {
+    "@tanstack/ai-code-mode": "workspace:*"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241230.0",
+    "@vitest/coverage-v8": "4.0.14",
+    "esbuild": "^0.25.12",
+    "miniflare": "^4.20260305.0",
+    "wrangler": "^4.19.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @tanstack/ai-isolate-cloudflare
+ *
+ * Cloudflare Workers driver for TanStack AI Code Mode.
+ * Execute LLM-generated code on Cloudflare's global edge network.
+ *
+ * @example
+ * ```typescript
+ * import { createCloudflareIsolateDriver } from '@tanstack/ai-isolate-cloudflare'
+ *
+ * const driver = createCloudflareIsolateDriver({
+ *   workerUrl: 'https://your-worker.workers.dev',
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export {
+  createCloudflareIsolateDriver,
+  type CloudflareIsolateDriverConfig,
+} from './isolate-driver'
+
+export type {
+  ExecuteRequest,
+  ExecuteResponse,
+  ToolSchema,
+  ToolCallRequest,
+  ToolResultPayload,
+} from './types'

package/src/isolate-driver.ts

@@ -0,0 +1,310 @@
+import type {
+  ExecutionResult,
+  IsolateConfig,
+  IsolateContext,
+  IsolateDriver,
+  ToolBinding,
+} from '@tanstack/ai-code-mode'
+import type {
+  ExecuteRequest,
+  ExecuteResponse,
+  ToolResultPayload,
+  ToolSchema,
+} from './types'
+
+/**
+ * Configuration for the Cloudflare Workers isolate driver
+ */
+export interface CloudflareIsolateDriverConfig {
+  /**
+   * URL of the deployed Cloudflare Worker
+   * For local development, use: http://localhost:8787
+   */
+  workerUrl: string
+
+  /**
+   * Optional authorization header value
+   * Useful for protecting your Worker endpoint
+   */
+  authorization?: string
+
+  /**
+   * Default execution timeout in ms (default: 30000)
+   */
+  timeout?: number
+
+  /**
+   * Maximum number of tool callback rounds (default: 10)
+   * Prevents infinite loops
+   */
+  maxToolRounds?: number
+}
+
+/**
+ * Convert tool bindings to schemas for the Worker
+ */
+function bindingsToSchemas(
+  bindings: Record<string, ToolBinding>,
+): Array<ToolSchema> {
+  return Object.entries(bindings).map(([name, binding]) => ({
+    name,
+    description: binding.description,
+    inputSchema: binding.inputSchema,
+  }))
+}
+
+/**
+ * Normalize errors from various sources
+ */
+function normalizeError(error: unknown): { name: string; message: string } {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message }
+  }
+  if (typeof error === 'object' && error !== null) {
+    const e = error as Record<string, unknown>
+    return {
+      name: String(e.name || 'Error'),
+      message: String(e.message || JSON.stringify(error)),
+    }
+  }
+  return { name: 'Error', message: String(error) }
+}
+
+/**
+ * IsolateContext implementation using Cloudflare Workers
+ */
+class CloudflareIsolateContext implements IsolateContext {
+  private workerUrl: string
+  private authorization?: string
+  private timeout: number
+  private maxToolRounds: number
+  private bindings: Record<string, ToolBinding>
+  private disposed = false
+
+  constructor(
+    workerUrl: string,
+    bindings: Record<string, ToolBinding>,
+    timeout: number,
+    maxToolRounds: number,
+    authorization?: string,
+  ) {
+    this.workerUrl = workerUrl
+    this.bindings = bindings
+    this.timeout = timeout
+    this.maxToolRounds = maxToolRounds
+    this.authorization = authorization
+  }
+
+  async execute<T = unknown>(code: string): Promise<ExecutionResult<T>> {
+    if (this.disposed) {
+      return {
+        success: false,
+        error: {
+          name: 'DisposedError',
+          message: 'Context has been disposed',
+        },
+        logs: [],
+      }
+    }
+
+    const tools = bindingsToSchemas(this.bindings)
+    let toolResults: Record<string, ToolResultPayload> | undefined
+    let allLogs: Array<string> = []
+    let rounds = 0
+
+    // Request/response loop for tool callbacks
+    while (rounds < this.maxToolRounds) {
+      rounds++
+
+      const request: ExecuteRequest = {
+        code,
+        tools,
+        toolResults,
+        timeout: this.timeout,
+      }
+
+      try {
+        const headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+        }
+
+        if (this.authorization) {
+          headers['Authorization'] = this.authorization
+        }
+
+        const response = await fetch(this.workerUrl, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(request),
+        })
+
+        if (!response.ok) {
+          const errorText = await response.text()
+          return {
+            success: false,
+            error: {
+              name: 'WorkerError',
+              message: `Worker returned ${response.status}: ${errorText}`,
+            },
+            logs: allLogs,
+          }
+        }
+
+        const result: ExecuteResponse = await response.json()
+
+        if (result.status === 'error') {
+          return {
+            success: false,
+            error: result.error,
+            logs: allLogs,
+          }
+        }
+
+        if (result.status === 'done') {
+          allLogs = [...allLogs, ...result.logs]
+          return {
+            success: result.success,
+            value: result.value as T,
+            error: result.error,
+            logs: allLogs,
+          }
+        }
+
+        // status === 'need_tools'
+        // Collect logs from this round
+        allLogs = [...allLogs, ...result.logs]
+
+        // Execute tool calls locally
+        toolResults = {}
+
+        for (const toolCall of result.toolCalls) {
+          const binding = this.bindings[toolCall.name] as
+            | ToolBinding
+            | undefined
+
+          if (!binding) {
+            toolResults[toolCall.id] = {
+              success: false,
+              error: `Unknown tool: ${toolCall.name}`,
+            }
+            continue
+          }
+
+          try {
+            const toolResult = await binding.execute(toolCall.args)
+            toolResults[toolCall.id] = {
+              success: true,
+              value: toolResult,
+            }
+          } catch (toolError) {
+            const err = normalizeError(toolError)
+            toolResults[toolCall.id] = {
+              success: false,
+              error: err.message,
+            }
+          }
+        }
+
+        // Continue loop to send results back to Worker
+      } catch (fetchError) {
+        const err = normalizeError(fetchError)
+        return {
+          success: false,
+          error: {
+            name: 'NetworkError',
+            message: `Failed to communicate with Worker: ${err.message}`,
+          },
+          logs: allLogs,
+        }
+      }
+    }
+
+    // Max rounds exceeded
+    return {
+      success: false,
+      error: {
+        name: 'MaxRoundsExceeded',
+        message: `Exceeded maximum tool callback rounds (${this.maxToolRounds})`,
+      },
+      logs: allLogs,
+    }
+  }
+
+  dispose(): Promise<void> {
+    this.disposed = true
+    return Promise.resolve()
+  }
+}
+
+/**
+ * Create a Cloudflare Workers isolate driver
+ *
+ * This driver executes code on Cloudflare's global edge network,
+ * providing true distributed execution capabilities.
+ *
+ * Tool calls are handled via a request/response loop:
+ * 1. Code is sent to the Worker
+ * 2. Worker executes until it needs a tool
+ * 3. Tool call is returned to the driver
+ * 4. Driver executes the tool locally
+ * 5. Result is sent back to the Worker
+ * 6. Worker continues execution
+ *
+ * @example
+ * ```typescript
+ * import { createCloudflareIsolateDriver } from '@tanstack/ai-isolate-cloudflare'
+ *
+ * // For local development with wrangler
+ * const driver = createCloudflareIsolateDriver({
+ *   workerUrl: 'http://localhost:8787',
+ * })
+ *
+ * // For production
+ * const driver = createCloudflareIsolateDriver({
+ *   workerUrl: 'https://code-mode-worker.your-account.workers.dev',
+ *   authorization: 'Bearer your-secret-token',
+ * })
+ *
+ * const context = await driver.createContext({
+ *   bindings: {
+ *     readFile: {
+ *       name: 'readFile',
+ *       description: 'Read a file',
+ *       inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+ *       execute: async ({ path }) => fs.readFile(path, 'utf-8'),
+ *     },
+ *   },
+ * })
+ *
+ * const result = await context.execute(`
+ *   const content = await readFile({ path: './data.json' })
+ *   return JSON.parse(content)
+ * `)
+ * ```
+ */
+export function createCloudflareIsolateDriver(
+  config: CloudflareIsolateDriverConfig,
+): IsolateDriver {
+  const {
+    workerUrl,
+    authorization,
+    timeout: defaultTimeout = 30000,
+    maxToolRounds = 10,
+  } = config
+
+  return {
+    createContext(isolateConfig: IsolateConfig): Promise<IsolateContext> {
+      const timeout = isolateConfig.timeout ?? defaultTimeout
+
+      return Promise.resolve(
+        new CloudflareIsolateContext(
+          workerUrl,
+          isolateConfig.bindings,
+          timeout,
+          maxToolRounds,
+          authorization,
+        ),
+      )
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared types between the Cloudflare Worker and the driver
+ */
+
+/**
+ * Tool schema passed to the worker
+ */
+export interface ToolSchema {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+/**
+ * Request to execute code in the worker
+ */
+export interface ExecuteRequest {
+  /** The code to execute */
+  code: string
+  /** Tool schemas available for the code to call */
+  tools: Array<ToolSchema>
+  /** Results from previous tool calls (for continuation) */
+  toolResults?: Record<string, ToolResultPayload>
+  /** Execution timeout in ms */
+  timeout?: number
+}
+
+/**
+ * Tool call requested by the worker
+ */
+export interface ToolCallRequest {
+  /** Unique ID for this tool call */
+  id: string
+  /** Name of the tool to call */
+  name: string
+  /** Arguments to pass to the tool */
+  args: unknown
+}
+
+/**
+ * Result of a tool call
+ */
+export interface ToolResultPayload {
+  /** Whether the tool call succeeded */
+  success: boolean
+  /** The result value if successful */
+  value?: unknown
+  /** Error message if failed */
+  error?: string
+}
+
+/**
+ * Response from the worker - either done or needs tool calls
+ */
+export type ExecuteResponse =
+  | {
+      status: 'done'
+      success: boolean
+      value?: unknown
+      error?: {
+        name: string
+        message: string
+        stack?: string
+      }
+      logs: Array<string>
+    }
+  | {
+      status: 'need_tools'
+      toolCalls: Array<ToolCallRequest>
+      logs: Array<string>
+      /** Continuation state to send back with tool results */
+      continuationId: string
+    }
+  | {
+      status: 'error'
+      error: {
+        name: string
+        message: string
+      }
+    }