withruntime 0.5.0 → 0.6.0

package/dist/products/volumes.js

@@ -1,8 +1,10 @@
 import { Page } from "../page.js";
+const enc = encodeURIComponent;
 /** Persistent disks: create once, attach when creating a sandbox with
- * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Backed up off their host
+ * daily unless that is turned off; restore one with `create({ fromBackup })`. */
 export function volumes(t) {
-    const get = (id, options) => t.json({ method: "GET", path: `/v1/volumes/${encodeURIComponent(id)}`, ...options });
+    const get = (id, options) => t.json({ method: "GET", path: `/v1/volumes/${enc(id)}`, ...options });
     const list = async (query = {}, options) => {
         const page = await t.json({
             method: "GET",
@@ -12,16 +14,62 @@ export function volumes(t) {
         });
         return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
     };
+    const backups = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/volume-backups",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => backups({ ...query, cursor }, options));
+    };
     return {
-        /** Create and wait (up to 10 s) until it is ready. */
+        /** Create and wait (up to 10 s) until it is ready. With `fromBackup`, a
+         * restore; it is ready once the backup is downloaded and checked. */
         create: (input, options) => t.json({ method: "POST", path: "/v1/volumes", body: input, wait: 10, ...options }),
         get,
         list,
         delete: (id, options) => t.json({
             method: "POST",
-            path: `/v1/volumes/${encodeURIComponent(id)}:delete`,
+            path: `/v1/volumes/${enc(id)}:delete`,
             body: {},
             ...options,
         }),
+        /** Back a volume up now, off its host, and wait (up to a minute, or
+         * `wait` seconds) for it to be ready. */
+        backup: (id, input = {}, options = {}) => {
+            const { wait = 60, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}:backup`,
+                body: input,
+                wait,
+                ...rest,
+            });
+        },
+        /** Daily backups on or off, and how many days each is kept. */
+        setBackupPolicy: (id, input, options) => t.json({
+            method: "POST",
+            path: `/v1/volumes/${enc(id)}:backup-policy`,
+            body: input,
+            ...options,
+        }),
+        /** Backups, newest first; `{ volumeId }` for one volume's. */
+        backups,
+        getBackup: (id, options) => t.json({ method: "GET", path: `/v1/volume-backups/${enc(id)}`, ...options }),
+        deleteBackup: (id, options) => t.json({
+            method: "POST",
+            path: `/v1/volume-backups/${enc(id)}:delete`,
+            body: {},
+            ...options,
+        }),
+        /** A new volume from a backup: `create({ fromBackup: id })`. */
+        restore: (backupId, input = {}, options) => t.json({
+            method: "POST",
+            path: "/v1/volumes",
+            body: { ...input, fromBackup: backupId },
+            wait: 10,
+            ...options,
+        }),
     };
 }

package/dist/products/watch.d.ts

@@ -0,0 +1,91 @@
+import type { RequestOptions, Transport } from "../transport.js";
+export type FileEventType = "create" | "write" | "remove" | "rename" | "chmod";
+export type FileEvent = {
+    type: FileEventType;
+    /** Absolute path in the sandbox. */
+    path: string;
+    isDir: boolean;
+    /** rename: where it was. */
+    oldPath?: string;
+    /** write: how many writes were folded into this one event. */
+    count?: number;
+};
+export type WatchNotice = {
+    k: "overflow";
+    dropped: number | null;
+    reason: "kernel" | "rate";
+} | {
+    k: "limit";
+    watches: number;
+} | {
+    k: "lost";
+    bytes: number;
+};
+export type WatchOptions = Omit<RequestOptions, "timeoutMs"> & {
+    recursive?: boolean;
+    /** Only these event types; all five by default. */
+    events?: FileEventType[];
+    /** Globs relative to the path: only matching paths are reported. */
+    include?: string[];
+    /** Globs relative to the path. An excluded directory is not watched at all. */
+    exclude?: string[];
+    /** Events are gathered this long and delivered together. Default 100. */
+    batchMs?: number;
+    /** The watch ends by itself after running this long. Default 1 hour. */
+    timeoutMs?: number;
+    maxWatches?: number;
+    /** A batch at a time, rather than one call per event. */
+    onBatch?: (events: FileEvent[]) => void | Promise<void>;
+    /** Events were lost (a flood past the rate cap, the kernel's queue, or a
+     * reader that fell more than 1 MiB behind): rescan what you care about. */
+    onNotice?: (notice: WatchNotice) => void;
+    /** The watch stopped: "stopped", "timeout", "root-removed", or "paused"
+     * (the sandbox paused; call `resume()` once it runs again: nothing is lost). */
+    onExit?: (reason: string) => void;
+};
+export type WatchInfo = {
+    id: string;
+    path: string;
+    processId: string;
+    state: string;
+    startedAt: number;
+};
+/** A running watch. Events arrive through the callbacks until `stop()`. */
+export declare class WatchHandle {
+    #private;
+    private readonly t;
+    private readonly base;
+    readonly id: string;
+    readonly path: string;
+    private readonly options;
+    private readonly onEvent?;
+    cursor: number;
+    constructor(t: Transport, base: string, id: string, path: string, cursor: number, options: WatchOptions, onEvent?: ((event: FileEvent) => void | Promise<void>) | undefined);
+    /** Settles when the watch stops delivering (stopped, ended or paused). */
+    get done(): Promise<void>;
+    /** Start delivering again from where it left off, after a pause. */
+    resume(): void;
+    /** Stop the watch in the sandbox, and stop delivering. */
+    stop(options?: RequestOptions): Promise<void>;
+    /** @internal */
+    begin(): this;
+}
+/** `sbx.files.watch(path, onEvent, options)`: E2B's `watchDir`, with
+ * filters, batches, and a watch that survives a pause without losing events. */
+export declare function watchDirectory(t: Transport, sandboxId: string, path: string, onEvent?: (event: FileEvent) => void | Promise<void>, options?: WatchOptions): Promise<WatchHandle>;
+export declare function sandboxWatches(t: Transport, sandboxId: string): {
+    list: (options?: RequestOptions) => Promise<WatchInfo[]>;
+    /** Events after a cursor, without a stream: for polling. */
+    read: (id: string, cursor?: number, input?: {
+        waitMs?: number;
+    }, options?: RequestOptions) => Promise<{
+        events: FileEvent[];
+        notices: Record<string, unknown>[];
+        nextCursor: number;
+        lostBytes: number;
+        ended: boolean;
+    }>;
+    stop: (id: string, options?: RequestOptions) => Promise<{
+        stopped: boolean;
+    }>;
+};

package/dist/products/watch.js

@@ -0,0 +1,135 @@
+/** A running watch. Events arrive through the callbacks until `stop()`. */
+export class WatchHandle {
+    t;
+    base;
+    id;
+    path;
+    options;
+    onEvent;
+    cursor;
+    #stopped = false;
+    #following;
+    #abort = new AbortController();
+    constructor(t, base, id, path, cursor, options, onEvent) {
+        this.t = t;
+        this.base = base;
+        this.id = id;
+        this.path = path;
+        this.options = options;
+        this.onEvent = onEvent;
+        this.cursor = cursor;
+    }
+    /** Settles when the watch stops delivering (stopped, ended or paused). */
+    get done() {
+        return this.#following ?? Promise.resolve();
+    }
+    /** Start delivering again from where it left off, after a pause. */
+    resume() {
+        if (this.#stopped)
+            throw new Error("This watch was stopped");
+        this.#abort = new AbortController();
+        this.begin();
+    }
+    /** Stop the watch in the sandbox, and stop delivering. */
+    async stop(options) {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#abort.abort();
+        await this.t
+            .json({ method: "DELETE", path: `${this.base}/${encodeURIComponent(this.id)}`, ...options })
+            .catch(() => undefined);
+        await this.#following?.catch(() => undefined);
+        this.options.onExit?.("stopped");
+    }
+    async #follow() {
+        for (;;) {
+            let next = "exit";
+            try {
+                for await (const event of this.t.events({
+                    method: "GET",
+                    path: `${this.base}/${encodeURIComponent(this.id)}/events`,
+                    query: { cursor: this.cursor, follow: true },
+                    signal: this.#abort.signal,
+                    timeoutMs: 150_000,
+                })) {
+                    this.cursor = event.cursor ?? this.cursor;
+                    if (event.k === "events") {
+                        if (this.options.onBatch)
+                            await this.options.onBatch(event.events);
+                        if (this.onEvent)
+                            for (const item of event.events)
+                                await this.onEvent(item);
+                    }
+                    else if (event.k === "continue")
+                        next = "continue";
+                    else if (event.k === "end" || event.k === "paused") {
+                        if (!this.#stopped)
+                            this.options.onExit?.(event.k === "paused" ? "paused" : event.reason);
+                        return;
+                    }
+                    else if (event.k === "failure")
+                        throw new Error(`${event.code}: ${event.message}`);
+                    else
+                        this.options.onNotice?.(event);
+                }
+            }
+            catch (error) {
+                if (this.#stopped || this.#abort.signal.aborted)
+                    return;
+                throw error;
+            }
+            if (next !== "continue" || this.#stopped)
+                return;
+        }
+    }
+    /** @internal */
+    begin() {
+        this.#following = this.#follow();
+        // An error surfaces through `done`; nothing is left unhandled meanwhile.
+        this.#following.catch(() => undefined);
+        return this;
+    }
+}
+/** `sbx.files.watch(path, onEvent, options)`: E2B's `watchDir`, with
+ * filters, batches, and a watch that survives a pause without losing events. */
+export function watchDirectory(t, sandboxId, path, onEvent, options = {}) {
+    const base = `/v1/sandboxes/${encodeURIComponent(sandboxId)}/files/watches`;
+    const { recursive, events, include, exclude, batchMs, timeoutMs, maxWatches, idempotencyKey, signal, } = options;
+    return t
+        .json({
+        method: "POST",
+        path: base,
+        body: {
+            path,
+            ...(recursive !== undefined ? { recursive } : {}),
+            ...(events ? { events } : {}),
+            ...(include ? { include } : {}),
+            ...(exclude ? { exclude } : {}),
+            ...(batchMs !== undefined ? { batchMs } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(maxWatches !== undefined ? { maxWatches } : {}),
+        },
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+        ...(signal ? { signal } : {}),
+    })
+        .then((watch) => new WatchHandle(t, base, watch.id, watch.path, watch.cursor ?? 0, options, onEvent).begin());
+}
+export function sandboxWatches(t, sandboxId) {
+    const base = `/v1/sandboxes/${encodeURIComponent(sandboxId)}/files/watches`;
+    return {
+        list: async (options) => (await t.json({ method: "GET", path: base, ...options })).data,
+        /** Events after a cursor, without a stream: for polling. */
+        read: (id, cursor = 0, input = {}, options) => t.json({
+            method: "GET",
+            path: `${base}/${encodeURIComponent(id)}/events`,
+            query: { cursor, ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}) },
+            ...options,
+        }),
+        stop: (id, options) => t.json({
+            method: "DELETE",
+            path: `${base}/${encodeURIComponent(id)}`,
+            ...options,
+        }),
+    };
+}

package/dist/sandbox.d.ts

@@ -1,4 +1,5 @@
 import { Page } from "./page.js";
+import { type FileEvent, type WatchHandle, type WatchOptions } from "./products/watch.js";
 import type { RequestOptions, Transport } from "./transport.js";
 import type { CommandResult, ExecOptions, FileEntry, OutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
 import { type SandboxExtensions } from "./products/index.js";
@@ -175,12 +176,41 @@ export declare class Files {
     private readonly t;
     private readonly sandboxId;
     constructor(t: Transport, sandboxId: string);
+    /** 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: string, onEvent?: (event: FileEvent) => void | Promise<void>, options?: WatchOptions): Promise<WatchHandle>;
+    /** The watches running in the sandbox, and polling reads by cursor. */
+    get watches(): {
+        list: (options?: RequestOptions) => Promise<import("./products/watch.js").WatchInfo[]>;
+        read: (id: string, cursor?: number, input?: {
+            waitMs?: number;
+        }, options?: RequestOptions) => Promise<{
+            events: FileEvent[];
+            notices: Record<string, unknown>[];
+            nextCursor: number;
+            lostBytes: number;
+            ended: boolean;
+        }>;
+        stop: (id: string, options?: RequestOptions) => Promise<{
+            stopped: boolean;
+        }>;
+    };
     /** A file's bytes, any size. */
     read(path: string, options?: RequestOptions): Promise<Uint8Array>;
     readText(path: string, options?: RequestOptions): Promise<string>;
     /** Writes a file of any size, atomically, making parent directories. Large
-     * ones go in parallel 1 MiB chunks checked against their SHA-256. */
-    write(path: string, data: string | Uint8Array, options?: RequestOptions): Promise<{
+     * ones go in parallel 1 MiB chunks checked against their SHA-256. `mode`
+     * sets its permissions (0o755 for a program); 0o644 when left out. */
+    write(path: string, data: string | Uint8Array, writeOptions?: RequestOptions & {
+        mode?: number;
+    }): Promise<{
         path: string;
         size: number;
     }>;

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/ssh.js

@@ -265,9 +265,21 @@ export async function portForwardCommand(argv, out, connect, me) {
     const sbx = await resolveSandbox(await connect(), target);
     const tunnel = await sbx.tunnel();
     const forwards = [];
+    /* A connection the sandbox refused is closed at once, which a browser or
+       curl reports only as an empty reply, so say why here, once per reason. */
+    const said = new Set();
+    const refused = (remote) => (error) => {
+        const line = `Port ${remote}: ${error.message}${error.hint ? ` ${error.hint}` : ""}`;
+        if (said.has(line))
+            return;
+        said.add(line);
+        out.error(out.json
+            ? JSON.stringify({ port: remote, error: { code: error.code, message: error.message } })
+            : line);
+    };
     try {
         for (const { local, remote } of ports)
-            forwards.push(await tunnel.forward(remote, { localPort: local, host: address }));
+            forwards.push(await tunnel.forward(remote, { localPort: local, host: address, onError: refused(remote) }));
     }
     catch (error) {
         tunnel.close();

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";
 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.0";
+export const VERSION = "0.6.0";
 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/tunnel.d.ts

@@ -1,3 +1,4 @@
+import { RuntimeError } from "./errors.js";
 /** One TCP connection (or SSH login) inside a tunnel. Set the handlers before
  * data can arrive, which is as soon as the promise that gave you this resolves. */
 export declare class TunnelStream {
@@ -49,10 +50,12 @@ export declare class Tunnel {
      * (the text of an OpenSSH `.pub` file). Speak SSH over the stream. */
     ssh(publicKey: string): Promise<TunnelStream>;
     /** Listens on a local port and carries each connection to `port` in the
-     * sandbox. Node and Bun only. */
+     * sandbox. Node and Bun only. A connection the sandbox cannot open, such as
+     * one to a port nothing listens on, is closed at once; `onError` says why. */
     forward(port: number, options?: {
         localPort?: number;
         host?: string;
+        onError?: (error: RuntimeError) => void;
     }): Promise<PortForward>;
     /** Closes the tunnel and every connection in it. */
     close(): void;

package/dist/tunnel.js

@@ -160,7 +160,8 @@ export class Tunnel {
         return this.#open(`ssh ${publicKey.trim()}`);
     }
     /** Listens on a local port and carries each connection to `port` in the
-     * sandbox. Node and Bun only. */
+     * sandbox. Node and Bun only. A connection the sandbox cannot open, such as
+     * one to a port nothing listens on, is closed at once; `onError` says why. */
     async forward(port, options = {}) {
         const net = await import("node:net");
         const host = options.host ?? "127.0.0.1";
@@ -183,7 +184,11 @@ export class Tunnel {
                 socket.on("end", () => stream.end());
                 socket.on("close", () => stream.close());
                 socket.resume();
-            }, () => socket.destroy());
+            }, (error) => {
+                socket.destroy();
+                if (error instanceof RuntimeError)
+                    options.onError?.(error);
+            });
         });
         await new Promise((resolve, reject) => {
             server.once("error", reject);
@@ -217,7 +222,7 @@ export class Tunnel {
                         message: `Nothing is listening on port ${port} in the sandbox.`,
                         code: "port_closed",
                         status: 0,
-                        hint: "Start the server first, and let it listen on 127.0.0.1, ::1 or every address.",
+                        hint: "Start the server with spawn (`runtime sandbox spawn <id> -- <command>`, sbx.spawn()), which keeps it running: a process started by exec ends with its command. Let it listen on 127.0.0.1, ::1 or every address.",
                     })
                     : error.message === "reserved"
                         ? new RuntimeError({

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;
+};