@tanstack/ai-sandbox-cloudflare 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/esm/provider.js

@@ -19,7 +19,7 @@ class CloudflareProvider {
     return { transport: this.config.transport ?? "rpc" };
   }
   async create(input) {
-    const id = crypto.randomUUID();
+    const id = input.id ?? crypto.randomUUID();
     const sandbox = getSandbox(this.config.binding, id, this.sandboxOptions);
     if (input.env && Object.keys(input.env).length > 0) {
       await sandbox.setEnvVars(input.env);

package/dist/esm/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sources":["../../src/provider.ts"],"sourcesContent":["import { getSandbox } from '@cloudflare/sandbox'\nimport { CLOUDFLARE_CAPS, CloudflareHandle } from './handle'\nimport type { Sandbox, SandboxTransport } from '@cloudflare/sandbox'\nimport type {\n  SandboxCapabilities,\n  SandboxCreateInput,\n  SandboxDestroyInput,\n  SandboxHandle,\n  SandboxProvider,\n  SandboxResumeInput,\n} from '@tanstack/ai-sandbox'\n\nconst DEFAULT_WORKDIR = '/workspace'\n\nexport interface CloudflareSandboxConfig {\n  /**\n   * The Sandbox Durable Object namespace binding (e.g. `env.Sandbox`).\n   * Available inside a Worker `fetch` handler.\n   */\n  binding: DurableObjectNamespace<Sandbox>\n  /** Working directory inside the container. Defaults to `/workspace`. */\n  workdir?: string\n  /**\n   * Your Worker's request hostname, required by `ports.connect` to expose a\n   * preview URL (Cloudflare routes exposed ports by hostname).\n   */\n  previewHostname?: string\n  /**\n   * Container-control transport. Defaults to `'rpc'` (the SDK's primary path)\n   * because `sandbox.tunnels` — used by `exposePreviewTool` to mint quick-tunnel\n   * preview URLs — ONLY exists on the RPC transport; on `'http'`/`'websocket'` it\n   * throws \"requires the RPC transport\". The transport must be the same for every\n   * `getSandbox()` of a given id, so this provider applies it to create/resume/\n   * destroy alike. Override to `'http'` only if you don't use preview tunnels.\n   */\n  transport?: SandboxTransport\n}\n\nclass CloudflareProvider implements SandboxProvider {\n  readonly name = 'cloudflare'\n\n  constructor(private readonly config: CloudflareSandboxConfig) {}\n\n  capabilities(): SandboxCapabilities {\n    return CLOUDFLARE_CAPS\n  }\n\n  private get workdir(): string {\n    return this.config.workdir ?? DEFAULT_WORKDIR\n  }\n\n  // `transport: 'rpc'` by default so `sandbox.tunnels` (preview URLs) works; must be\n  // identical across every `getSandbox()` for an id, so all three paths share this.\n  private get sandboxOptions(): { transport: SandboxTransport } {\n    return { transport: this.config.transport ?? 'rpc' }\n  }\n\n  async create(input: SandboxCreateInput): Promise<SandboxHandle> {\n    const id = crypto.randomUUID()\n    const sandbox = getSandbox(this.config.binding, id, this.sandboxOptions)\n    if (input.env && Object.keys(input.env).length > 0) {\n      await sandbox.setEnvVars(input.env)\n    }\n    await sandbox.mkdir(this.workdir, { recursive: true })\n    return new CloudflareHandle(\n      id,\n      sandbox,\n      this.workdir,\n      this.config.previewHostname,\n    )\n  }\n\n  resume(input: SandboxResumeInput): Promise<SandboxHandle | null> {\n    // The Durable Object is durable, so the sandbox is always addressable by\n    // id. (The container disk may have been wiped on cold start — withSandbox\n    // re-bootstraps under the same identity when durableFilesystem is false.)\n    const sandbox = getSandbox(\n      this.config.binding,\n      input.id,\n      this.sandboxOptions,\n    )\n    return Promise.resolve(\n      new CloudflareHandle(\n        input.id,\n        sandbox,\n        this.workdir,\n        this.config.previewHostname,\n      ),\n    )\n  }\n\n  async destroy(input: SandboxDestroyInput): Promise<void> {\n    const sandbox = getSandbox(\n      this.config.binding,\n      input.id,\n      this.sandboxOptions,\n    )\n    await sandbox.destroy()\n  }\n}\n\n/**\n * Cloudflare sandbox provider — runs harness adapters inside Cloudflare\n * Containers at the edge. Construct it inside a Worker with the Sandbox Durable\n * Object namespace binding. See the stdin/snapshot limitations in `handle.ts`.\n */\nexport function cloudflareSandbox(\n  config: CloudflareSandboxConfig,\n): SandboxProvider {\n  return new CloudflareProvider(config)\n}\n"],"names":[],"mappings":";;AAYA,MAAM,kBAAkB;AA0BxB,MAAM,mBAA8C;AAAA,EAGlD,YAA6B,QAAiC;AAAjC,SAAA,SAAA;AAAA,EAAkC;AAAA,EAAlC;AAAA,EAFpB,OAAO;AAAA,EAIhB,eAAoC;AAClC,WAAO;AAAA,EACT;AAAA,EAEA,IAAY,UAAkB;AAC5B,WAAO,KAAK,OAAO,WAAW;AAAA,EAChC;AAAA;AAAA;AAAA,EAIA,IAAY,iBAAkD;AAC5D,WAAO,EAAE,WAAW,KAAK,OAAO,aAAa,MAAA;AAAA,EAC/C;AAAA,EAEA,MAAM,OAAO,OAAmD;AAC9D,UAAM,KAAK,OAAO,WAAA;AAClB,UAAM,UAAU,WAAW,KAAK,OAAO,SAAS,IAAI,KAAK,cAAc;AACvE,QAAI,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,EAAE,SAAS,GAAG;AAClD,YAAM,QAAQ,WAAW,MAAM,GAAG;AAAA,IACpC;AACA,UAAM,QAAQ,MAAM,KAAK,SAAS,EAAE,WAAW,MAAM;AACrD,WAAO,IAAI;AAAA,MACT;AAAA,MACA;AAAA,MACA,KAAK;AAAA,MACL,KAAK,OAAO;AAAA,IAAA;AAAA,EAEhB;AAAA,EAEA,OAAO,OAA0D;AAI/D,UAAM,UAAU;AAAA,MACd,KAAK,OAAO;AAAA,MACZ,MAAM;AAAA,MACN,KAAK;AAAA,IAAA;AAEP,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,MAAM;AAAA,QACN;AAAA,QACA,KAAK;AAAA,QACL,KAAK,OAAO;AAAA,MAAA;AAAA,IACd;AAAA,EAEJ;AAAA,EAEA,MAAM,QAAQ,OAA2C;AACvD,UAAM,UAAU;AAAA,MACd,KAAK,OAAO;AAAA,MACZ,MAAM;AAAA,MACN,KAAK;AAAA,IAAA;AAEP,UAAM,QAAQ,QAAA;AAAA,EAChB;AACF;AAOO,SAAS,kBACd,QACiB;AACjB,SAAO,IAAI,mBAAmB,MAAM;AACtC;"}
+{"version":3,"file":"provider.js","sources":["../../src/provider.ts"],"sourcesContent":["import { getSandbox } from '@cloudflare/sandbox'\nimport { CLOUDFLARE_CAPS, CloudflareHandle } from './handle'\nimport type { Sandbox, SandboxTransport } from '@cloudflare/sandbox'\nimport type {\n  SandboxCapabilities,\n  SandboxCreateInput,\n  SandboxDestroyInput,\n  SandboxHandle,\n  SandboxProvider,\n  SandboxResumeInput,\n} from '@tanstack/ai-sandbox'\n\nconst DEFAULT_WORKDIR = '/workspace'\n\nexport interface CloudflareSandboxConfig {\n  /**\n   * The Sandbox Durable Object namespace binding (e.g. `env.Sandbox`).\n   * Available inside a Worker `fetch` handler.\n   */\n  binding: DurableObjectNamespace<Sandbox>\n  /** Working directory inside the container. Defaults to `/workspace`. */\n  workdir?: string\n  /**\n   * Your Worker's request hostname, required by `ports.connect` to expose a\n   * preview URL (Cloudflare routes exposed ports by hostname).\n   */\n  previewHostname?: string\n  /**\n   * Container-control transport. Defaults to `'rpc'` (the SDK's primary path)\n   * because `sandbox.tunnels` — used by `exposePreviewTool` to mint quick-tunnel\n   * preview URLs — ONLY exists on the RPC transport; on `'http'`/`'websocket'` it\n   * throws \"requires the RPC transport\". The transport must be the same for every\n   * `getSandbox()` of a given id, so this provider applies it to create/resume/\n   * destroy alike. Override to `'http'` only if you don't use preview tunnels.\n   */\n  transport?: SandboxTransport\n}\n\nclass CloudflareProvider implements SandboxProvider {\n  readonly name = 'cloudflare'\n\n  constructor(private readonly config: CloudflareSandboxConfig) {}\n\n  capabilities(): SandboxCapabilities {\n    return CLOUDFLARE_CAPS\n  }\n\n  private get workdir(): string {\n    return this.config.workdir ?? DEFAULT_WORKDIR\n  }\n\n  // `transport: 'rpc'` by default so `sandbox.tunnels` (preview URLs) works; must be\n  // identical across every `getSandbox()` for an id, so all three paths share this.\n  private get sandboxOptions(): { transport: SandboxTransport } {\n    return { transport: this.config.transport ?? 'rpc' }\n  }\n\n  async create(input: SandboxCreateInput): Promise<SandboxHandle> {\n    // Honor the deterministic id `ensure()` supplies so reconnecting consumers\n    // (e.g. a preview iframe) address the same DO the agent edits. The DO id is\n    // `idFromName(id)`, so any stable string works; fall back to a random id\n    // when created outside `defineSandbox` (advanced direct use).\n    const id = input.id ?? crypto.randomUUID()\n    const sandbox = getSandbox(this.config.binding, id, this.sandboxOptions)\n    if (input.env && Object.keys(input.env).length > 0) {\n      await sandbox.setEnvVars(input.env)\n    }\n    await sandbox.mkdir(this.workdir, { recursive: true })\n    return new CloudflareHandle(\n      id,\n      sandbox,\n      this.workdir,\n      this.config.previewHostname,\n    )\n  }\n\n  resume(input: SandboxResumeInput): Promise<SandboxHandle | null> {\n    // The Durable Object is durable, so the sandbox is always addressable by\n    // id. (The container disk may have been wiped on cold start — withSandbox\n    // re-bootstraps under the same identity when durableFilesystem is false.)\n    const sandbox = getSandbox(\n      this.config.binding,\n      input.id,\n      this.sandboxOptions,\n    )\n    return Promise.resolve(\n      new CloudflareHandle(\n        input.id,\n        sandbox,\n        this.workdir,\n        this.config.previewHostname,\n      ),\n    )\n  }\n\n  async destroy(input: SandboxDestroyInput): Promise<void> {\n    const sandbox = getSandbox(\n      this.config.binding,\n      input.id,\n      this.sandboxOptions,\n    )\n    await sandbox.destroy()\n  }\n}\n\n/**\n * Cloudflare sandbox provider — runs harness adapters inside Cloudflare\n * Containers at the edge. Construct it inside a Worker with the Sandbox Durable\n * Object namespace binding. See the stdin/snapshot limitations in `handle.ts`.\n */\nexport function cloudflareSandbox(\n  config: CloudflareSandboxConfig,\n): SandboxProvider {\n  return new CloudflareProvider(config)\n}\n"],"names":[],"mappings":";;AAYA,MAAM,kBAAkB;AA0BxB,MAAM,mBAA8C;AAAA,EAGlD,YAA6B,QAAiC;AAAjC,SAAA,SAAA;AAAA,EAAkC;AAAA,EAAlC;AAAA,EAFpB,OAAO;AAAA,EAIhB,eAAoC;AAClC,WAAO;AAAA,EACT;AAAA,EAEA,IAAY,UAAkB;AAC5B,WAAO,KAAK,OAAO,WAAW;AAAA,EAChC;AAAA;AAAA;AAAA,EAIA,IAAY,iBAAkD;AAC5D,WAAO,EAAE,WAAW,KAAK,OAAO,aAAa,MAAA;AAAA,EAC/C;AAAA,EAEA,MAAM,OAAO,OAAmD;AAK9D,UAAM,KAAK,MAAM,MAAM,OAAO,WAAA;AAC9B,UAAM,UAAU,WAAW,KAAK,OAAO,SAAS,IAAI,KAAK,cAAc;AACvE,QAAI,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,EAAE,SAAS,GAAG;AAClD,YAAM,QAAQ,WAAW,MAAM,GAAG;AAAA,IACpC;AACA,UAAM,QAAQ,MAAM,KAAK,SAAS,EAAE,WAAW,MAAM;AACrD,WAAO,IAAI;AAAA,MACT;AAAA,MACA;AAAA,MACA,KAAK;AAAA,MACL,KAAK,OAAO;AAAA,IAAA;AAAA,EAEhB;AAAA,EAEA,OAAO,OAA0D;AAI/D,UAAM,UAAU;AAAA,MACd,KAAK,OAAO;AAAA,MACZ,MAAM;AAAA,MACN,KAAK;AAAA,IAAA;AAEP,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,MAAM;AAAA,QACN;AAAA,QACA,KAAK;AAAA,QACL,KAAK,OAAO;AAAA,MAAA;AAAA,IACd;AAAA,EAEJ;AAAA,EAEA,MAAM,QAAQ,OAA2C;AACvD,UAAM,UAAU;AAAA,MACd,KAAK,OAAO;AAAA,MACZ,MAAM;AAAA,MACN,KAAK;AAAA,IAAA;AAEP,UAAM,QAAQ,QAAA;AAAA,EAChB;AACF;AAOO,SAAS,kBACd,QACiB;AACjB,SAAO,IAAI,mBAAmB,MAAM;AACtC;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-sandbox-cloudflare",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Cloudflare sandbox provider for TanStack AI — run harness adapters inside Cloudflare Containers (edge) through the uniform SandboxHandle.",
   "author": "",
   "license": "MIT",
@@ -40,35 +40,32 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "vite build",
-    "clean": "premove ./build ./dist",
-    "lint:fix": "eslint ./src --fix",
-    "test:build": "publint --strict",
-    "test:eslint": "eslint ./src",
-    "test:lib": "vitest",
-    "test:lib:dev": "pnpm test:lib --watch",
-    "test:types": "tsc"
-  },
   "dependencies": {
     "@cloudflare/sandbox": "^0.12.1"
   },
   "peerDependencies": {
-    "@tanstack/ai": "workspace:^",
-    "@tanstack/ai-sandbox": "workspace:^",
-    "@tanstack/ai-sandbox-local-process": "workspace:^",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@tanstack/ai": "^0.39.1",
+    "@tanstack/ai-sandbox": "^0.2.1",
+    "@tanstack/ai-sandbox-local-process": "^0.2.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260317.1",
-    "@tanstack/ai": "workspace:*",
-    "@tanstack/ai-sandbox": "workspace:*",
-    "@tanstack/ai-sandbox-local-process": "workspace:*",
     "@types/node": "^24.10.1",
     "@vitest/coverage-v8": "4.0.14",
-    "zod": "^4.2.0"
+    "zod": "^4.2.0",
+    "@tanstack/ai": "0.39.1",
+    "@tanstack/ai-sandbox": "0.2.1",
+    "@tanstack/ai-sandbox-local-process": "0.2.0"
   },
-  "publishConfig": {
-    "access": "public"
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
   }
-}
+}

package/src/provider.ts

@@ -56,7 +56,11 @@ class CloudflareProvider implements SandboxProvider {
   }
 
   async create(input: SandboxCreateInput): Promise<SandboxHandle> {
-    const id = crypto.randomUUID()
+    // Honor the deterministic id `ensure()` supplies so reconnecting consumers
+    // (e.g. a preview iframe) address the same DO the agent edits. The DO id is
+    // `idFromName(id)`, so any stable string works; fall back to a random id
+    // when created outside `defineSandbox` (advanced direct use).
+    const id = input.id ?? crypto.randomUUID()
     const sandbox = getSandbox(this.config.binding, id, this.sandboxOptions)
     if (input.env && Object.keys(input.env).length > 0) {
       await sandbox.setEnvVars(input.env)