@douglas-agent/sandbank-cloudflare 0.2.0

package/README.md

@@ -0,0 +1,53 @@
+# @douglas-agent/sandbank-cloudflare
+
+> Cloudflare Workers sandbox adapter for [Sandbank](../../README.md).
+
+## Install
+
+```bash
+pnpm add @douglas-agent/sandbank-core @douglas-agent/sandbank-cloudflare
+```
+
+## Usage
+
+```typescript
+import { createProvider } from '@douglas-agent/sandbank-core'
+import { CloudflareAdapter } from '@douglas-agent/sandbank-cloudflare'
+
+const adapter = new CloudflareAdapter({
+  namespace: env.SANDBOX,       // DurableObject binding
+  hostname: 'myapp.dev',
+  sleepAfter: '30m',
+  storage: {                    // enables volumes capability
+    endpoint: 'https://xxx.r2.cloudflarestorage.com',
+    provider: 'r2',
+  },
+})
+
+const provider = createProvider(adapter)
+const sandbox = await provider.create({ image: 'node:22' })
+const { stdout } = await sandbox.exec('echo hello')
+await provider.destroy(sandbox.id)
+```
+
+## Capabilities
+
+| Capability | Supported |
+|------------|:---------:|
+| `exec.stream` | ✅ |
+| `terminal` | ✅ |
+| `port.expose` | ✅ |
+| `snapshot` | ✅ |
+| `volumes` | ✅ (with `storage` config) |
+
+## Characteristics
+
+- **Runtime:** V8 isolate + container
+- **Cold start:** ~1s
+- **File I/O:** Native SDK
+- **Region:** Global edge
+- **Dependency:** `@cloudflare/sandbox`
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -0,0 +1,39 @@
+import type { AdapterSandbox, Capability, CreateConfig, ListFilter, SandboxAdapter, SandboxInfo, VolumeConfig, VolumeInfo } from '@douglas-agent/sandbank-core';
+import { type Sandbox as CloudflareSandbox } from '@cloudflare/sandbox';
+export interface CloudflareAdapterConfig {
+    /** DurableObjectNamespace<Sandbox> binding */
+    namespace: DurableObjectNamespace<CloudflareSandbox>;
+    /** Hostname for port exposure, e.g. 'myapp.dev' */
+    hostname: string;
+    /** Auto-sleep duration, e.g. '30m' (optional) */
+    sleepAfter?: string;
+    /** Keep the container alive indefinitely (prevents auto-sleep). Must be explicitly destroyed. */
+    keepAlive?: boolean;
+    /** R2/S3 storage config (enables 'volumes' capability) */
+    storage?: {
+        endpoint: string;
+        credentials?: {
+            accessKeyId: string;
+            secretAccessKey: string;
+        };
+        provider?: 'r2' | 's3' | 'gcs';
+    };
+}
+export declare class CloudflareAdapter implements SandboxAdapter {
+    readonly name = "cloudflare";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly config;
+    private readonly sandboxes;
+    private readonly volumes;
+    private readonly snapshots;
+    constructor(config: CloudflareAdapterConfig);
+    private getSnapshotsFor;
+    createSandbox(config: CreateConfig): Promise<AdapterSandbox>;
+    getSandbox(id: string): Promise<AdapterSandbox>;
+    listSandboxes(filter?: ListFilter): Promise<SandboxInfo[]>;
+    destroySandbox(id: string): Promise<void>;
+    createVolume(config: VolumeConfig): Promise<VolumeInfo>;
+    deleteVolume(id: string): Promise<void>;
+    listVolumes(): Promise<VolumeInfo[]>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,YAAY,EAGZ,UAAU,EACV,cAAc,EACd,WAAW,EAIX,YAAY,EACZ,UAAU,EACX,MAAM,8BAA8B,CAAA;AAErC,OAAO,EAAc,KAAK,OAAO,IAAI,iBAAiB,EAAwB,MAAM,qBAAqB,CAAA;AAIzG,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,SAAS,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,CAAA;IACpD,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAA;IAChB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iGAAiG;IACjG,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,0DAA0D;IAC1D,OAAO,CAAC,EAAE;QACR,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,eAAe,EAAE,MAAM,CAAA;SAAE,CAAA;QAC9D,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,KAAK,CAAA;KAC/B,CAAA;CACF;AAkKD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,IAAI,gBAAe;IAC5B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAAA;IAE9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkD;gBAEhE,MAAM,EAAE,uBAAuB;IAU3C,OAAO,CAAC,eAAe;IASjB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IA+C5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAmB/C,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA0B1D,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzC,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAYvD,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;CAQ3C"}

package/dist/adapter.js

@@ -0,0 +1,258 @@
+/// <reference types="@cloudflare/workers-types" />
+import { SandboxNotFoundError, ProviderError } from '@douglas-agent/sandbank-core';
+import { getSandbox } from '@cloudflare/sandbox';
+// --- Retry helper ---
+const CONTAINER_NOT_READY_RETRIES = 3;
+const CONTAINER_NOT_READY_DELAY = 2000;
+function isContainerNotReady(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.includes('CONTAINER_NOT_READY') || msg.includes('container not ready');
+}
+async function withRetry(fn) {
+    let lastError;
+    for (let i = 0; i < CONTAINER_NOT_READY_RETRIES; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (!isContainerNotReady(err) || i === CONTAINER_NOT_READY_RETRIES - 1)
+                throw err;
+            await new Promise(r => setTimeout(r, CONTAINER_NOT_READY_DELAY));
+        }
+    }
+    throw lastError;
+}
+// --- Sandbox wrapper ---
+function wrapCloudflareSandbox(id, sandbox, state, createdAt, hostname, sandboxSnapshots) {
+    return {
+        id,
+        state,
+        createdAt,
+        async exec(command, options) {
+            const result = await withRetry(() => sandbox.exec(command, {
+                timeout: options?.timeout,
+                cwd: options?.cwd,
+            }));
+            return {
+                exitCode: result.exitCode ?? (result.success ? 0 : 1),
+                stdout: result.stdout ?? '',
+                stderr: result.stderr ?? '',
+            };
+        },
+        async writeFile(path, content) {
+            if (typeof content === 'string') {
+                await sandbox.writeFile(path, content, { encoding: 'utf-8' });
+            }
+            else {
+                // CF SDK writeFile only accepts string; encode binary as base64
+                let binary = '';
+                for (let i = 0; i < content.length; i++) {
+                    binary += String.fromCharCode(content[i]);
+                }
+                await sandbox.writeFile(path, btoa(binary), { encoding: 'base64' });
+            }
+        },
+        async readFile(path) {
+            const result = await sandbox.readFile(path, { encoding: 'base64' });
+            const b64 = typeof result === 'string' ? result : result.content;
+            const binary = atob(b64);
+            const bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++) {
+                bytes[i] = binary.charCodeAt(i);
+            }
+            return bytes;
+        },
+        async execStream(command) {
+            return sandbox.execStream(command);
+        },
+        async exposePort(port) {
+            if (port === 3000) {
+                throw new Error('Port 3000 is reserved by the Cloudflare sandbox control plane. Use a different port (1024-65535, excluding 3000).');
+            }
+            const result = await sandbox.exposePort(port, { hostname });
+            return { url: result.url };
+        },
+        async createSnapshot(name) {
+            const backup = await sandbox.createBackup({ dir: '/', name: name ?? undefined });
+            const snapshotId = name ?? `snap-${crypto.randomUUID().slice(0, 8)}`;
+            sandboxSnapshots.set(snapshotId, backup);
+            return { snapshotId };
+        },
+        async restoreSnapshot(snapshotId) {
+            const backup = sandboxSnapshots.get(snapshotId);
+            if (!backup) {
+                throw new SandboxNotFoundError('cloudflare', snapshotId);
+            }
+            await sandbox.restoreBackup(backup);
+        },
+        async startTerminal(options) {
+            const port = 7681;
+            const shell = options?.shell ?? '/bin/bash';
+            const ttydBase = 'https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd';
+            // 1. Ensure ttyd is available (use wget fallback since curl may not be installed)
+            const check = await withRetry(() => sandbox.exec('which ttyd'));
+            if ((check.exitCode ?? (check.success ? 0 : 1)) !== 0) {
+                await withRetry(() => sandbox.exec(`ARCH=$(uname -m); case "$ARCH" in aarch64|arm64) ARCH=aarch64;; x86_64) ARCH=x86_64;; *) echo "Unsupported arch: $ARCH" >&2; exit 1;; esac; `
+                    + `TTYD_URL="${ttydBase}.$ARCH"; `
+                    + `command -v curl > /dev/null && curl -sL "$TTYD_URL" -o /usr/local/bin/ttyd`
+                    + ` || { command -v wget > /dev/null && wget -qO /usr/local/bin/ttyd "$TTYD_URL"; }`
+                    + ` || { apt-get update -qq && apt-get install -y -qq wget > /dev/null && wget -qO /usr/local/bin/ttyd "$TTYD_URL"; }`));
+                await withRetry(() => sandbox.exec('chmod +x /usr/local/bin/ttyd'));
+            }
+            // 2. Start ttyd in background (-W enables write)
+            await withRetry(() => sandbox.exec(`nohup ttyd -W -p ${port} '${shell.replace(/'/g, "'\\''")}' > /dev/null 2>&1 &`));
+            // 3. Wait for ttyd to be ready (check process is running)
+            await withRetry(() => sandbox.exec(`for i in $(seq 1 20); do pgrep -x ttyd > /dev/null && break || sleep 0.5; done`));
+            // 4. Expose port and return WebSocket URL
+            const exposed = await sandbox.exposePort(port, { hostname });
+            const url = exposed.url.replace(/\/$/, '') + '/ws';
+            return {
+                url,
+                port,
+            };
+        },
+    };
+}
+// --- Adapter ---
+export class CloudflareAdapter {
+    name = 'cloudflare';
+    capabilities;
+    config;
+    sandboxes = new Map();
+    volumes = new Map();
+    snapshots = new Map();
+    constructor(config) {
+        this.config = config;
+        const caps = ['exec.stream', 'terminal', 'port.expose', 'snapshot'];
+        if (config.storage) {
+            caps.push('volumes');
+        }
+        this.capabilities = new Set(caps);
+    }
+    getSnapshotsFor(sandboxId) {
+        let map = this.snapshots.get(sandboxId);
+        if (!map) {
+            map = new Map();
+            this.snapshots.set(sandboxId, map);
+        }
+        return map;
+    }
+    async createSandbox(config) {
+        const id = `cf-${crypto.randomUUID().slice(0, 8)}`;
+        const externalId = crypto.randomUUID().slice(0, 8);
+        const createdAt = new Date().toISOString();
+        try {
+            const opts = {};
+            if (this.config.keepAlive) {
+                opts['keepAlive'] = true;
+            }
+            else if (this.config.sleepAfter) {
+                opts['sleepAfter'] = this.config.sleepAfter;
+            }
+            const sandbox = getSandbox(this.config.namespace, externalId, opts);
+            // Set environment variables if provided
+            if (config.env && Object.keys(config.env).length > 0) {
+                await withRetry(() => sandbox.setEnvVars(config.env));
+            }
+            // Mount volumes if configured
+            if (config.volumes && config.volumes.length > 0 && this.config.storage) {
+                for (const vol of config.volumes) {
+                    await withRetry(() => sandbox.mountBucket(vol.id, vol.mountPath, {
+                        endpoint: this.config.storage.endpoint,
+                        provider: this.config.storage.provider ?? 'r2',
+                        credentials: this.config.storage.credentials,
+                    }));
+                }
+            }
+            const record = {
+                externalId,
+                sandboxRef: sandbox,
+                state: 'running',
+                createdAt,
+            };
+            this.sandboxes.set(id, record);
+            return wrapCloudflareSandbox(id, sandbox, 'running', createdAt, this.config.hostname, this.getSnapshotsFor(id));
+        }
+        catch (err) {
+            throw new ProviderError('cloudflare', err);
+        }
+    }
+    async getSandbox(id) {
+        const record = this.sandboxes.get(id);
+        if (!record || record.state === 'terminated') {
+            throw new SandboxNotFoundError('cloudflare', id);
+        }
+        // Reconnect lazily via getSandbox
+        const reconnectOpts = {};
+        if (this.config.keepAlive) {
+            reconnectOpts['keepAlive'] = true;
+        }
+        else if (this.config.sleepAfter) {
+            reconnectOpts['sleepAfter'] = this.config.sleepAfter;
+        }
+        const sandbox = getSandbox(this.config.namespace, record.externalId, reconnectOpts);
+        record.sandboxRef = sandbox;
+        return wrapCloudflareSandbox(id, sandbox, record.state, record.createdAt, this.config.hostname, this.getSnapshotsFor(id));
+    }
+    async listSandboxes(filter) {
+        let infos = [];
+        for (const [id, record] of this.sandboxes) {
+            infos.push({
+                id,
+                state: record.state,
+                createdAt: record.createdAt,
+                image: '', // CF container image is defined in wrangler.toml, not at runtime
+            });
+        }
+        // Apply state filter
+        if (filter?.state) {
+            const states = Array.isArray(filter.state) ? filter.state : [filter.state];
+            infos = infos.filter(s => states.includes(s.state));
+        }
+        // Apply limit
+        if (filter?.limit && filter.limit > 0) {
+            infos = infos.slice(0, filter.limit);
+        }
+        return infos;
+    }
+    async destroySandbox(id) {
+        const record = this.sandboxes.get(id);
+        if (!record)
+            return; // idempotent
+        if (record.state === 'terminated')
+            return; // already destroyed
+        try {
+            const sandbox = getSandbox(this.config.namespace, record.externalId);
+            await sandbox.destroy();
+        }
+        catch {
+            // Idempotent: ignore errors during destroy
+        }
+        record.state = 'terminated';
+    }
+    // --- Volume operations ---
+    async createVolume(config) {
+        // Lightweight registration: trust that the R2 bucket already exists
+        const id = config.name;
+        this.volumes.set(id, { id, name: config.name });
+        return {
+            id,
+            name: config.name,
+            sizeGB: config.sizeGB ?? 0,
+            attachedTo: null,
+        };
+    }
+    async deleteVolume(id) {
+        // Just remove from internal tracking; R2 bucket lifecycle is managed by the user
+        this.volumes.delete(id);
+    }
+    async listVolumes() {
+        return Array.from(this.volumes.values()).map(v => ({
+            id: v.id,
+            name: v.name,
+            sizeGB: 0,
+            attachedTo: null,
+        }));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CloudflareAdapter, type CloudflareAdapterConfig } from './adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { CloudflareAdapter } from './adapter.js';

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@douglas-agent/sandbank-cloudflare",
+  "version": "0.2.0",
+  "description": "Cloudflare Workers sandbox adapter for Sandbank",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://sandbank.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeonice/sandbank-douglas-agent.git",
+    "directory": "packages/cloudflare"
+  },
+  "keywords": [
+    "sandbox",
+    "ai-agent",
+    "cloudflare",
+    "workers",
+    "cloud"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts"
+  },
+  "dependencies": {
+    "@cloudflare/sandbox": "^0.7.0",
+    "@douglas-agent/sandbank-core": "^0.3.6"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250214.0",
+    "typescript": "^5.7.3",
+    "wrangler": "^4.0.0"
+  }
+}