withruntime 0.5.1 → 0.6.1

package/dist/sandbox.js

@@ -1,5 +1,6 @@
 import { CommandError, RuntimeError } from "./errors.js";
 import { Page } from "./page.js";
+import { sandboxWatches, watchDirectory, } from "./products/watch.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
 const CHUNK = 1_048_576;
@@ -274,6 +275,13 @@ export class Sandbox {
     async snapshot(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
         await this.refresh();
+        // Straight after a fork or a wake the sandbox is still `resuming`, and
+        // after a pause still `pausing`: wait for where it is going, or a
+        // snapshot of it is refused as not paused (user lane, 23 September 2026).
+        if (this.state === "resuming" || this.state === "starting")
+            await this.waitFor("running");
+        else if (this.state === "pausing")
+            await this.waitFor("paused");
         const running = this.state === "running";
         if (running)
             await this.pause();
@@ -552,6 +560,22 @@ export class Files {
         this.sandboxId = sandboxId;
     }
     #path = (suffix) => `/v1/sandboxes/${enc(this.sandboxId)}${suffix}`;
+    /** Watch a directory: `onEvent` gets create, write, remove, rename and
+     * chmod events until `handle.stop()`. E2B's `watchDir`, plus filters,
+     * batches, and a watch that loses nothing across a pause:
+     *
+     *   const watch = await sbx.files.watch("/workspace", (e) => console.log(e.type, e.path),
+     *     { recursive: true, exclude: ["node_modules"] });
+     *   ...
+     *   await watch.stop();
+     */
+    watch(path, onEvent, options) {
+        return watchDirectory(this.t, this.sandboxId, path, onEvent, options);
+    }
+    /** The watches running in the sandbox, and polling reads by cursor. */
+    get watches() {
+        return sandboxWatches(this.t, this.sandboxId);
+    }
     /** A file's bytes, any size. */
     async read(path, options = {}) {
         return this.t.bytes({
@@ -566,8 +590,11 @@ export class Files {
         return new TextDecoder().decode(await this.read(path, options));
     }
     /** Writes a file of any size, atomically, making parent directories. Large
-     * ones go in parallel 1 MiB chunks checked against their SHA-256. */
-    async write(path, data, options = {}) {
+     * ones go in parallel 1 MiB chunks checked against their SHA-256. `mode`
+     * sets its permissions (0o755 for a program); 0o644 when left out. */
+    async write(path, data, writeOptions = {}) {
+        const { mode, ...options } = writeOptions;
+        const octal = mode === undefined ? undefined : (mode & 0o777).toString(8).padStart(3, "0");
         const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
         if (bytes.length <= CHUNK) {
             // bytes(), not send(): the answer is read, so its connection is free
@@ -575,7 +602,7 @@ export class Files {
             await this.t.bytes({
                 method: "PUT",
                 path: this.#path("/files/content"),
-                query: { path },
+                query: { path, ...(octal ? { mode: octal } : {}) },
                 bytes,
                 ...options,
             });
@@ -583,12 +610,55 @@ export class Files {
         }
         const { createHash } = await import("node:crypto");
         const sha256 = createHash("sha256").update(bytes).digest("hex");
-        const begin = await this.t.json({
-            method: "POST",
-            path: this.#path("/uploads"),
-            body: { path, size: bytes.length, sha256 },
+        // A guest journals mutations across operations, not per URL. One logical
+        // write therefore owns separate stable keys for each mutation phase.
+        const uploadKey = options.idempotencyKey ?? crypto.randomUUID();
+        const phaseOptions = (phase) => ({
             ...options,
+            idempotencyKey: createHash("sha256")
+                .update(JSON.stringify(["files.write", uploadKey, phase]))
+                .digest("hex"),
+        });
+        let begin;
+        try {
+            begin = await this.t.json({
+                method: "POST",
+                path: this.#path("/uploads"),
+                body: { path, size: bytes.length, sha256, ...(octal ? { mode: octal } : {}) },
+                ...phaseOptions("begin"),
+            });
+        }
+        catch (error) {
+            if (!octal || !(error instanceof RuntimeError) || error.code !== "guest_upgrade_required")
+                throw error;
+            // The API aborted the unsupported transfer before accepting chunks.
+            // A different body needs a different key; retain deterministic retries.
+            begin = await this.t.json({
+                method: "POST",
+                path: this.#path("/uploads"),
+                body: { path, size: bytes.length, sha256 },
+                ...phaseOptions("legacy-begin"),
+            });
+        }
+        const commit = () => this.t.json({
+            method: "POST",
+            path: this.#path(`/uploads/${enc(begin.uploadId)}:commit`),
+            body: {},
+            ...phaseOptions("commit"),
         });
+        let committed = false;
+        if (begin.replayed) {
+            // A completed commit removed the transfer. Ask its journal before
+            // resending chunks; an incomplete transfer alone is safe to continue.
+            try {
+                await commit();
+                committed = true;
+            }
+            catch (error) {
+                if (!(error instanceof RuntimeError) || error.code !== "upload_incomplete")
+                    throw error;
+            }
+        }
         const offsets = [];
         for (let offset = 0; offset < bytes.length; offset += begin.chunkBytes)
             offsets.push(offset);
@@ -605,13 +675,18 @@ export class Files {
             }
         };
         try {
-            await Promise.all(Array.from({ length: Math.min(PARALLEL, offsets.length) }, worker));
-            await this.t.json({
-                method: "POST",
-                path: this.#path(`/uploads/${enc(begin.uploadId)}:commit`),
-                body: {},
-                ...options,
-            });
+            if (!committed) {
+                await Promise.all(Array.from({ length: Math.min(PARALLEL, offsets.length) }, worker));
+                await commit();
+            }
+            // An older sandbox image ignores the mode in the upload; set it after.
+            if (octal && begin.mode !== octal)
+                await this.t.json({
+                    method: "POST",
+                    path: this.#path("/files:chmod"),
+                    body: { path, mode: octal },
+                    ...phaseOptions("chmod"),
+                });
         }
         catch (error) {
             await this.t
@@ -619,6 +694,7 @@ export class Files {
                 method: "POST",
                 path: this.#path(`/uploads/${enc(begin.uploadId)}:abort`),
                 body: {},
+                ...phaseOptions("abort"),
             })
                 .catch(() => undefined);
             throw error;
@@ -669,7 +745,8 @@ export class Files {
         const { stat, readFile } = await import("node:fs/promises");
         const info = await stat(localPath);
         if (info.isFile()) {
-            await this.write(remotePath, await readFile(localPath));
+            // Its permissions travel with it: an uploaded script stays runnable.
+            await this.write(remotePath, await readFile(localPath), { mode: info.mode & 0o777 });
             return;
         }
         const { packDirectory } = await import("./tar.js");
@@ -681,7 +758,7 @@ export class Files {
         const result = await new Sandbox(this.t, { id: this.sandboxId }).exec([
             "sh",
             "-c",
-            'mkdir -p "$1" && tar -xzf "$2" -C "$1"; code=$?; rm -f "$2"; exit $code',
+            'mkdir -p "$1" && tar -xpzf "$2" -C "$1"; code=$?; rm -f "$2"; exit $code',
             "sh",
             remotePath,
             staging,

package/dist/snapshots.d.ts

@@ -1,7 +1,8 @@
 import { Page } from "./page.js";
 import type { RequestOptions, Transport } from "./transport.js";
 /** A sandbox's whole machine (files, memory, running processes), kept on its
- * host to start new sandboxes from. */
+ * host to start new sandboxes from, and copied off the host so it survives
+ * losing that host. */
 export type Snapshot = {
     id: string;
     kind: "snapshot";
@@ -19,6 +20,15 @@ export type Snapshot = {
     /** What it stores, and what storage is metered for: the bytes it alone holds. */
     storedBytes: number | null;
     meteredBytes: number | null;
+    /** Whether its copy off the host is made and checked. */
+    backedUp: boolean;
+    /** Where that copy stands. `restoring`: its host was lost and it is being
+     * restored onto another; forks answer `snapshot_restoring` until it is. */
+    durability: {
+        state: "none" | "pending" | "durable" | "failed" | "restoring";
+        durableAt: string | null;
+        storedBytes: number | null;
+    };
     error: string | null;
     createdAt: string;
     readyAt: string | null;

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.5.1";
+export declare const VERSION = "0.6.1";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.5.1";
+export const VERSION = "0.6.1";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);
@@ -289,6 +289,9 @@ export class Transport {
                 yield JSON.parse(buffer);
         }
         finally {
+            // Returning early from the iterator must close the HTTP stream too.
+            // Cleanup must not replace a parse, network or callback error.
+            await reader.cancel().catch(() => undefined);
             reader.releaseLock();
         }
     }

package/dist/wireguard.d.ts

@@ -0,0 +1,7 @@
+/** A WireGuard key pair, as `wg genkey | wg pubkey` makes: X25519, each half
+ * 32 bytes of base64. Made on the machine that will use it, so the private
+ * key is never sent anywhere. */
+export declare function generateWireGuardKeyPair(): {
+    privateKey: string;
+    publicKey: string;
+};

package/dist/wireguard.js

@@ -0,0 +1,13 @@
+import { generateKeyPairSync } from "node:crypto";
+/** A WireGuard key pair, as `wg genkey | wg pubkey` makes: X25519, each half
+ * 32 bytes of base64. Made on the machine that will use it, so the private
+ * key is never sent anywhere. */
+export function generateWireGuardKeyPair() {
+    const { privateKey, publicKey } = generateKeyPairSync("x25519");
+    const d = privateKey.export({ format: "jwk" }).d;
+    const x = publicKey.export({ format: "jwk" }).x;
+    return {
+        privateKey: Buffer.from(d, "base64url").toString("base64"),
+        publicKey: Buffer.from(x, "base64url").toString("base64"),
+    };
+}

package/package.json

@@ -1,44 +1,59 @@
 {
   "name": "withruntime",
-  "version": "0.5.1",
+  "version": "0.6.1",
+  "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./e2b": {
       "types": "./dist/e2b/index.d.ts",
-      "import": "./dist/e2b/index.js"
+      "import": "./dist/e2b/index.js",
+      "default": "./dist/e2b/index.js"
     },
     "./e2b/code-interpreter": {
       "types": "./dist/e2b/code-interpreter.d.ts",
-      "import": "./dist/e2b/code-interpreter.js"
+      "import": "./dist/e2b/code-interpreter.js",
+      "default": "./dist/e2b/code-interpreter.js"
     },
     "./daytona": {
       "types": "./dist/daytona/index.d.ts",
-      "import": "./dist/daytona/index.js"
+      "import": "./dist/daytona/index.js",
+      "default": "./dist/daytona/index.js"
     },
     "./vercel": {
       "types": "./dist/vercel/index.d.ts",
-      "import": "./dist/vercel/index.js"
+      "import": "./dist/vercel/index.js",
+      "default": "./dist/vercel/index.js"
     },
     "./tools": {
       "types": "./dist/tools/index.d.ts",
-      "import": "./dist/tools/index.js"
+      "import": "./dist/tools/index.js",
+      "default": "./dist/tools/index.js"
     },
     "./ai": {
       "types": "./dist/ai/index.d.ts",
-      "import": "./dist/ai/index.js"
+      "import": "./dist/ai/index.js",
+      "default": "./dist/ai/index.js"
     },
     "./claude-agent-sdk": {
       "types": "./dist/claude-agent-sdk/index.d.ts",
-      "import": "./dist/claude-agent-sdk/index.js"
+      "import": "./dist/claude-agent-sdk/index.js",
+      "default": "./dist/claude-agent-sdk/index.js"
     },
     "./openai-agents": {
       "types": "./dist/openai-agents/index.d.ts",
-      "import": "./dist/openai-agents/index.js"
+      "import": "./dist/openai-agents/index.js",
+      "default": "./dist/openai-agents/index.js"
+    },
+    "./ai-harness": {
+      "types": "./dist/ai-harness/index.d.ts",
+      "import": "./dist/ai-harness/index.js",
+      "default": "./dist/ai-harness/index.js"
     }
   },
   "bin": {
@@ -50,7 +65,8 @@
     "README.md",
     "E2B.md",
     "DAYTONA.md",
-    "VERCEL.md"
+    "VERCEL.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=22"
@@ -60,23 +76,34 @@
     "prepack": "bun run build",
     "check-types": "tsc --noEmit",
     "lint": "eslint",
-    "test": "bun test && bun scripts/test-python.ts && bun scripts/test-go.ts",
+    "test": "bun test && bun scripts/test-python.ts && bun scripts/test-go.ts && bun ../../sdks/java/scripts/check.ts && bun ../../sdks/ruby/scripts/check.ts",
+    "test:java": "bun ../../sdks/java/scripts/check.ts",
+    "test:ruby": "bun ../../sdks/ruby/scripts/check.ts",
     "test:python": "bun scripts/test-python.ts",
     "test:go": "bun scripts/test-go.ts"
   },
   "devDependencies": {
+    "@ai-sdk/harness": "1.0.124",
+    "@anthropic-ai/claude-agent-sdk": "0.3.277",
+    "@anthropic-ai/sdk": "0.128.0",
+    "@google/genai": "2.24.0",
+    "@mastra/core": "1.71.0",
+    "@mistralai/mistralai": "2.7.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@openai/agents": "0.18.0",
+    "@openai/agents-core": "0.18.0",
+    "@openrouter/sdk": "1.3.27",
     "@runtime/eslint-config": "workspace:*",
     "@runtime/typescript-config": "workspace:*",
     "@types/bun": "^1.4.0",
     "@types/node": "^20",
+    "ai": "7.0.87",
     "eslint": "^9",
+    "groq-sdk": "1.6.0",
+    "openai": "7.23.0",
+    "together-ai": "0.55.0",
     "typescript": "^5",
-    "@openai/agents": "0.18.0",
-    "@openai/agents-core": "0.18.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.277",
-    "ai": "7.0.87",
-    "zod": "^4.1.8",
-    "@modelcontextprotocol/sdk": "^1.30.0"
+    "zod": "^4.1.8"
   },
   "publishConfig": {
     "access": "public",
@@ -96,6 +123,7 @@
     "undici": "^7.29.1"
   },
   "peerDependencies": {
+    "@ai-sdk/harness": "^1.0.0",
     "@anthropic-ai/claude-agent-sdk": ">=0.2.0",
     "@openai/agents": ">=0.18.0",
     "@openai/agents-core": ">=0.18.0",
@@ -103,6 +131,9 @@
     "zod": ">=3.25.0"
   },
   "peerDependenciesMeta": {
+    "@ai-sdk/harness": {
+      "optional": true
+    },
     "@anthropic-ai/claude-agent-sdk": {
       "optional": true
     },