withruntime 0.8.4 → 0.10.0

package/dist/e2b/filesystem.d.ts

@@ -14,9 +14,9 @@ export interface EntryInfo extends WriteInfo {
     size: number;
     mode: number;
     permissions: string;
-    /** Runtime's listing does not say who owns a file: always "". */
+    /** File owner when returned by the native guest. */
     owner: string;
-    /** Runtime's listing does not say a file's group: always "". */
+    /** File group when returned by the native guest. */
     group: string;
     modifiedTime?: Date;
     symlinkTarget?: string;
@@ -32,11 +32,14 @@ export interface FilesystemEvent {
     /** Relative to the watched directory. */
     name: string;
     type: FilesystemEventType;
+    entry?: EntryInfo;
 }
 export interface WatchOpts extends FilesystemRequestOpts {
-    /** How long the watch runs; 0 is Runtime's maximum, 24 hours. Default 60000. */
+    /** How long the subscription runs; 0 has no subscription deadline. Default 60000. */
     timeoutMs?: number;
     recursive?: boolean;
+    includeEntry?: boolean;
+    allowNetworkMounts?: boolean;
 }
 export interface E2BWatchHandle {
     stop(): Promise<void>;
@@ -98,9 +101,8 @@ export declare class Filesystem {
     remove(path: string, opts?: FilesystemRequestOpts): Promise<void>;
     exists(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
     getInfo(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
-    /** E2B's watchDir on Runtime's file watch: the same events (CREATE, WRITE,
-     * REMOVE, RENAME, CHMOD) with names relative to the directory, stopped
-     * with `handle.stop()`. `timeoutMs` 0 is Runtime's 24-hour maximum. */
+    /** E2B's watchDir on Runtime's file watch. A local deadline preserves
+     * subsecond subscriptions; 0 runs until stopped or the sandbox ends. */
     watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts & {
         onExit?: (err?: Error) => void | Promise<void>;
     }): Promise<E2BWatchHandle>;

package/dist/e2b/filesystem.js

@@ -1,5 +1,5 @@
 import { request } from "./client.js";
-import { FileNotFoundError, guard, NotSupportedError } from "./errors.js";
+import { FileNotFoundError, guard, InvalidArgumentError, NotSupportedError, TimeoutError, } from "./errors.js";
 export var FileType;
 (function (FileType) {
     FileType["FILE"] = "file";
@@ -42,8 +42,9 @@ function entryInfo(entry) {
         size: entry.size,
         mode,
         permissions: PERMISSIONS[(bits >> 6) & 7] + PERMISSIONS[(bits >> 3) & 7] + PERMISSIONS[bits & 7],
-        owner: "",
-        group: "",
+        owner: entry.owner ?? "",
+        group: entry.group ?? "",
+        ...(entry.symlinkTarget ? { symlinkTarget: entry.symlinkTarget } : {}),
         modifiedTime: new Date(entry.modifiedAt),
     };
 }
@@ -73,8 +74,10 @@ export class Filesystem {
         return this.#ctx.runtime.files;
     }
     async #path(path, opts) {
+        opts.signal?.throwIfAborted();
         refuse(opts);
         await this.#ctx.ensureHome(path);
+        opts.signal?.throwIfAborted();
         return absolute(path);
     }
     async read(path, opts = {}) {
@@ -98,6 +101,7 @@ export class Filesystem {
         return this.#writeOne(pathOrFiles, dataOrOpts, maybeOpts ?? {});
     }
     async writeFiles(files, opts = {}) {
+        opts.signal?.throwIfAborted();
         const written = [];
         for (const file of files)
             written.push(await this.#writeOne(file.path, file.data, opts));
@@ -112,61 +116,156 @@ export class Filesystem {
     /** A directory's entries, hidden ones included; `depth` goes deeper. */
     async list(path, opts = {}) {
         const dir = await this.#path(path, opts);
-        const entries = await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true }));
+        const entries = await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true, ...request(opts) }));
         return entries.map(entryInfo);
     }
     /** Makes a directory and its parents. False when it already existed. */
     async makeDir(path, opts = {}) {
         const dir = await this.#path(path, opts);
-        if (await guard("file", () => this.#files.exists(dir)))
+        if (await guard("file", () => this.#files.exists(dir, request(opts))))
             return false;
-        await guard("file", () => this.#files.mkdir(dir, { parents: true }));
+        await guard("file", () => this.#files.mkdir(dir, { parents: true, ...request(opts) }));
         return true;
     }
     /** Moves a file or directory, replacing a file at the new path, as E2B does. */
     async rename(oldPath, newPath, opts = {}) {
         const from = await this.#path(oldPath, opts);
         const to = await this.#path(newPath, opts);
-        await guard("file", () => this.#files.rename(from, to, { overwrite: true }));
+        await guard("file", () => this.#files.rename(from, to, { overwrite: true, ...request(opts) }));
         return this.getInfo(to, opts);
     }
     /** Removes a file, or a directory with everything in it. */
     async remove(path, opts = {}) {
         const target = await this.#path(path, opts);
-        await guard("file", () => this.#files.remove(target, { recursive: true }));
+        await guard("file", () => this.#files.remove(target, { recursive: true, ...request(opts) }));
     }
     async exists(path, opts = {}) {
         const target = await this.#path(path, opts);
-        return guard("file", () => this.#files.exists(target));
+        return guard("file", () => this.#files.exists(target, request(opts)));
     }
     async getInfo(path, opts = {}) {
         const target = await this.#path(path, opts);
-        const stat = await guard("file", () => this.#files.stat(target));
+        const stat = await guard("file", () => this.#files.stat(target, request(opts)));
         if (!stat.exists)
             throw new FileNotFoundError(`${target} does not exist.`);
         return entryInfo(stat);
     }
-    /** E2B's watchDir on Runtime's file watch: the same events (CREATE, WRITE,
-     * REMOVE, RENAME, CHMOD) with names relative to the directory, stopped
-     * with `handle.stop()`. `timeoutMs` 0 is Runtime's 24-hour maximum. */
+    /** E2B's watchDir on Runtime's file watch. A local deadline preserves
+     * subsecond subscriptions; 0 runs until stopped or the sandbox ends. */
     async watchDir(path, onEvent, opts = {}) {
+        opts.signal?.throwIfAborted();
+        if (opts.allowNetworkMounts)
+            throw new NotSupportedError("Watching network mounts", "Watch a local sandbox directory instead.");
+        const lifetime = opts.timeoutMs ?? 60000;
+        if (!Number.isFinite(lifetime) || lifetime < 0)
+            throw new InvalidArgumentError("timeoutMs must be a nonnegative finite number.");
         const target = await this.#path(path, opts);
         const prefix = target.endsWith("/") ? target : `${target}/`;
-        const lifetime = opts.timeoutMs === 0 ? 86_400_000 : (opts.timeoutMs ?? 60_000);
-        const watch = await guard("file", () => this.#files.watch(target, (event) => onEvent({
-            name: event.path.startsWith(prefix) ? event.path.slice(prefix.length) : event.path,
-            type: event.type,
-        }), {
-            recursive: opts.recursive === true,
-            timeoutMs: Math.max(1_000, Math.min(86_400_000, lifetime)),
-            onExit: (reason) => {
-                if (reason === "stopped")
+        let exited = false;
+        let native;
+        let stopping;
+        let timer;
+        const lifetimeAbort = new AbortController();
+        const signal = opts.signal
+            ? AbortSignal.any([opts.signal, lifetimeAbort.signal])
+            : lifetimeAbort.signal;
+        const exit = async (error) => {
+            if (exited)
+                return;
+            exited = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            try {
+                await opts.onExit?.(error);
+            }
+            catch {
+                /* Upstream treats a throwing terminal callback as handled. */
+            }
+        };
+        const stopRemote = () => {
+            if (!native)
+                return Promise.resolve();
+            return (stopping ??= native.stop());
+        };
+        const close = async (error) => {
+            const callback = exit(error);
+            try {
+                await stopRemote();
+            }
+            finally {
+                await callback;
+            }
+        };
+        const onAbort = () => {
+            const error = opts.signal?.reason instanceof Error
+                ? opts.signal.reason
+                : new Error("The watch was aborted.");
+            void close(error).catch(() => undefined);
+        };
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        if (opts.signal?.aborted)
+            onAbort();
+        if (lifetime > 0) {
+            const deadline = Date.now() + lifetime;
+            const schedule = () => {
+                timer = setTimeout(() => {
+                    if (exited)
+                        return;
+                    if (Date.now() < deadline) {
+                        schedule();
+                        return;
+                    }
+                    const error = new TimeoutError("Filesystem watch timed out.");
+                    // Mark the terminal result before native cancellation can report a
+                    // clean end. The same signal also cancels creation still in flight.
+                    void close(error).catch(() => undefined);
+                    lifetimeAbort.abort(error);
+                }, Math.min(2147483647, Math.max(0, deadline - Date.now())));
+                timer.unref?.();
+            };
+            schedule();
+        }
+        try {
+            const watch = await guard("file", () => this.#files.watch(target, async (event) => {
+                if (exited)
                     return;
-                void opts.onExit?.(reason === "timeout" || reason === "paused"
-                    ? undefined
-                    : new Error(`The watch ended: ${reason}`));
-            },
-        }));
-        return { stop: () => watch.stop() };
+                let entry;
+                if (opts.includeEntry) {
+                    try {
+                        entry = await this.getInfo(event.path, { ...opts, signal });
+                    }
+                    catch (error) {
+                        if (!(error instanceof FileNotFoundError))
+                            throw error;
+                    }
+                }
+                if (!exited)
+                    await onEvent({
+                        name: event.path.startsWith(prefix) ? event.path.slice(prefix.length) : event.path,
+                        type: event.type,
+                        ...(entry ? { entry } : {}),
+                    });
+            }, {
+                recursive: opts.recursive === true,
+                timeoutMs: 0,
+                signal,
+                onExit: (reason) => {
+                    void exit(reason === "timeout" ? new TimeoutError("Filesystem watch timed out.") : undefined);
+                },
+                onNotice: (notice) => {
+                    void close(new Error(`Filesystem events were lost (${notice.k}); rescan the directory and start a new watch.`)).catch(() => undefined);
+                },
+            }));
+            native = watch;
+            if (exited)
+                await stopRemote();
+            void watch.done?.then(() => exit(), (error) => close(error instanceof Error ? error : new Error(String(error))).catch(() => undefined));
+            return { stop: () => close() };
+        }
+        catch (error) {
+            await close(error instanceof Error ? error : new Error(String(error))).catch(() => undefined);
+            throw error;
+        }
     }
 }

package/dist/e2b/index.d.ts

@@ -12,6 +12,7 @@ export { Commands, CommandHandle, pidOf, type CommandStartOpts, type CommandConn
 export { Filesystem, FileType, type EntryInfo, type WriteInfo, type WriteEntry, type FilesystemRequestOpts, type FilesystemReadOpts, type FilesystemWriteOpts, type FilesystemListOpts, FilesystemEventType, type FilesystemEvent, type WatchOpts, type E2BWatchHandle as WatchHandle, } from "./filesystem.js";
 export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, type CommandResult, } from "./errors.js";
 export type { ConnectionOpts, RuntimeOpts } from "./client.js";
+export { Pty, type PtyCreateOpts, type PtyConnectOpts } from "./pty.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
 export default Sandbox;
 /** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */

package/dist/e2b/index.js

@@ -4,6 +4,7 @@ export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, } from ".
 export { Commands, CommandHandle, pidOf, } from "./commands.js";
 export { Filesystem, FileType, FilesystemEventType, } from "./filesystem.js";
 export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, } from "./errors.js";
+export { Pty } from "./pty.js";
 export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
 export default Sandbox;
 /** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */

package/dist/e2b/pty.d.ts

@@ -0,0 +1,24 @@
+import { CommandHandle, type CommandRequestOpts, type SandboxContext, type Username } from "./commands.js";
+export interface PtyCreateOpts extends CommandRequestOpts {
+    cols: number;
+    rows: number;
+    onData: (data: Uint8Array) => void | Promise<void>;
+    timeoutMs?: number;
+    user?: Username;
+    envs?: Record<string, string>;
+    cwd?: string;
+}
+export type PtyConnectOpts = CommandRequestOpts & Pick<PtyCreateOpts, "onData" | "timeoutMs">;
+/** E2B's PTY methods over native terminal processes with lossless output. */
+export declare class Pty {
+    private readonly ctx;
+    constructor(ctx: SandboxContext);
+    create(opts: PtyCreateOpts): Promise<CommandHandle>;
+    connect(pid: number, opts?: PtyConnectOpts): Promise<CommandHandle>;
+    sendInput(pid: number, data: Uint8Array, opts?: CommandRequestOpts): Promise<void>;
+    resize(pid: number, size: {
+        cols: number;
+        rows: number;
+    }, opts?: CommandRequestOpts): Promise<void>;
+    kill(pid: number, opts?: CommandRequestOpts): Promise<boolean>;
+}

package/dist/e2b/pty.js

@@ -0,0 +1,80 @@
+import { CommandHandle, commandRequest, connectionRequest, killProcess, refuseUser, resolveProcess, } from "./commands.js";
+import { guard, InvalidArgumentError, NotSupportedError } from "./errors.js";
+function dimensions(size) {
+    for (const value of [size.cols, size.rows])
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new InvalidArgumentError("PTY rows and columns must be positive whole numbers.");
+    return { cols: size.cols, rows: size.rows };
+}
+/** E2B's PTY methods over native terminal processes with lossless output. */
+export class Pty {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async create(opts) {
+        refuseUser(opts.user);
+        const pty = dimensions(opts);
+        const opening = connectionRequest(opts, this.ctx.requestTimeoutMs);
+        if (typeof opts.onData !== "function")
+            throw new InvalidArgumentError("onData must be a function.");
+        const env = { TERM: "xterm-256color", LANG: "C.UTF-8", LC_ALL: "C.UTF-8", ...opts.envs };
+        const process = await guard("sandbox", async () => {
+            await this.ctx.ensureHome(opts.cwd, opening.request);
+            opening.request.signal?.throwIfAborted();
+            return this.ctx.runtime.spawn(["/bin/bash", "-i", "-l"], {
+                pty,
+                stdin: "pipe",
+                outputEncoding: "base64",
+                env,
+                ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+                request: opening.request,
+            });
+        }).catch(opening.failure);
+        return new CommandHandle(process, {
+            stdin: false,
+            pty: true,
+            onData: opts.onData,
+            timeoutMs: opening.timeoutMs,
+            deadline: opening.deadline,
+            signal: opts.signal,
+            requestTimeoutMs: this.ctx.requestTimeoutMs,
+        });
+    }
+    async connect(pid, opts) {
+        const opening = connectionRequest(opts ?? {}, this.ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.ctx, pid, opening.request).catch(opening.failure);
+        if (!process.info.pty || process.info.outputEncoding !== "base64")
+            throw new NotSupportedError("Connecting to a legacy text-output PTY", "Create the PTY through sandbox.pty.create first.");
+        return new CommandHandle(process, {
+            stdin: false,
+            pty: true,
+            onData: opts?.onData,
+            timeoutMs: opening.timeoutMs,
+            deadline: opening.deadline,
+            cursor: process.info.outputBytes,
+            signal: opts?.signal,
+            requestTimeoutMs: this.ctx.requestTimeoutMs,
+        });
+    }
+    async sendInput(pid, data, opts = {}) {
+        const request = commandRequest(opts, this.ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.ctx, pid, request);
+        if (!process.info.pty)
+            throw new InvalidArgumentError(`The process with pid ${pid} is not a PTY.`);
+        request.signal?.throwIfAborted();
+        await guard("sandbox", () => process.write(data, request));
+    }
+    async resize(pid, size, opts = {}) {
+        const pty = dimensions(size);
+        const request = commandRequest(opts, this.ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.ctx, pid, request);
+        if (!process.info.pty)
+            throw new InvalidArgumentError(`The process with pid ${pid} is not a PTY.`);
+        request.signal?.throwIfAborted();
+        await guard("sandbox", () => process.resize(pty.cols, pty.rows, request));
+    }
+    kill(pid, opts = {}) {
+        return killProcess(this.ctx, pid, commandRequest(opts, this.ctx.requestTimeoutMs));
+    }
+}

package/dist/e2b/sandbox.d.ts

@@ -2,6 +2,7 @@ import type { Runtime } from "../client.js";
 import { type ConnectionOpts, type RuntimeOpts, type RuntimeSandbox } from "./client.js";
 import { Commands } from "./commands.js";
 import { Filesystem } from "./filesystem.js";
+import { Pty } from "./pty.js";
 /** E2B's default machine: 2 vCPU and 512 MiB (docs.e2b.dev/billing, checked
  * 23 September 2026). Pass `runtime: { create: { memoryMiB } }` for another. */
 export declare const DEFAULT_SHAPE: {
@@ -26,7 +27,8 @@ export interface SandboxOpts extends ConnectionOpts {
     template?: string;
     /** Stored as the sandbox's labels (at most 32, values up to 256 characters). */
     metadata?: Record<string, string>;
-    /** Given to every command and code run through this object. */
+    /** The sandbox's own environment: every command, terminal and code run in it
+     * gets these, whoever connects. Values are never shown again. */
     envs?: Record<string, string>;
     /** Default 300 000. Runtime's leases run 60 s to 1 hour; shorter rounds up
      * to 60 s (with a warning), longer is refused. */
@@ -88,17 +90,18 @@ export type SandboxListOpts = SandboxApiOpts & {
 };
 export declare class Sandbox {
     #private;
+    protected readonly requestTimeoutMs: number;
     protected static readonly defaultTemplate: string;
     readonly files: Filesystem;
     readonly commands: Commands;
+    readonly pty: Pty;
     /** Use Sandbox.create or Sandbox.connect. */
-    constructor(runtime: RuntimeSandbox, client: Runtime, envs?: Record<string, string>);
+    constructor(runtime: RuntimeSandbox, client: Runtime, requestTimeoutMs?: number);
     get sandboxId(): string;
     /** The Runtime sandbox underneath: previews, network, desktop, interpreter,
      * processes, terminal and the rest of Runtime's SDK. */
     get runtime(): RuntimeSandbox;
     protected get client(): Runtime;
-    protected get envs(): Record<string, string>;
     /** Creates a sandbox from `template` (default "base", Runtime's stock image)
      * with E2B's default machine, 2 vCPU and 512 MiB, and waits until it runs.
      * Funding is left to Runtime: the free trial while the account has trial
@@ -166,7 +169,6 @@ export declare class Sandbox {
      * its host, `<port>-<id>.<domain>`, once the share has landed. Anyone with
      * the address can reach it; a browser sees a one-time page naming Runtime. */
     getPublicHost(port: number): Promise<string>;
-    get pty(): never;
     get git(): never;
     /** E2B's metrics, from Runtime's measured readings (`sbx.metrics()`): CPU
      * as a percent of the sandbox's vCPUs and resident memory, one entry per

package/dist/e2b/sandbox.js

@@ -2,6 +2,7 @@ import { clientFor, request, } from "./client.js";
 import { Commands } from "./commands.js";
 import { guard, InvalidArgumentError, NotSupportedError, SandboxError, SandboxNotFoundError, TemplateError, } from "./errors.js";
 import { Filesystem } from "./filesystem.js";
+import { Pty } from "./pty.js";
 /* E2B's Sandbox over Runtime's. Every call is one or a few calls of the
    withruntime SDK; nothing here speaks HTTP. What Runtime cannot do the same
    way throws NotSupportedError before anything happens. */
@@ -65,12 +66,13 @@ function refuseCreate(opts) {
 }
 /** Where a template sends the create: the stock image, a Runtime image by
  * name or id, or a Runtime snapshot by id. */
-async function resolveTemplate(client, template) {
+async function resolveTemplate(client, template, options) {
+    options.signal?.throwIfAborted();
     if (STOCK_TEMPLATES.has(template))
         return {};
     if (UUID.test(template)) {
         try {
-            await client.images.get(template);
+            await client.images.get(template, options);
             return { image: template };
         }
         catch (error) {
@@ -79,7 +81,7 @@ async function resolveTemplate(client, template) {
         }
         return { snapshot: template };
     }
-    const page = await client.images.list({ name: template, state: "ready", limit: 1 });
+    const page = await client.images.list({ name: template, state: "ready", limit: 1 }, options);
     const image = page.data[0];
     if (image)
         return { image: image.id };
@@ -131,28 +133,30 @@ function unsupported(feature, alternative) {
 /** Where Runtime serves previews; getHost names a host under it. */
 const PREVIEW_DOMAIN = "runtimehost.com";
 export class Sandbox {
+    requestTimeoutMs;
     static defaultTemplate = "base";
     files;
     commands;
+    pty;
     #client;
     #runtime;
-    #envs;
     #home;
     /** Ports shared as public previews, by port: the one share each asked for. */
     #shares = new Map();
     /** Use Sandbox.create or Sandbox.connect. */
-    constructor(runtime, client, envs = {}) {
+    constructor(runtime, client, requestTimeoutMs = 60_000) {
+        this.requestTimeoutMs = requestTimeoutMs;
         this.#runtime = runtime;
         this.#client = client;
-        this.#envs = envs;
         const ctx = {
-            envs,
-            ensureHome: (text) => this.#ensureHome(text),
+            ensureHome: (text, options) => this.#ensureHome(text, options),
+            requestTimeoutMs: this.requestTimeoutMs,
         };
         // A getter, so the modules see the sandbox as it is after each refresh.
         Object.defineProperty(ctx, "runtime", { get: () => this.#runtime });
         this.files = new Filesystem(ctx);
         this.commands = new Commands(ctx);
+        this.pty = new Pty(ctx);
     }
     get sandboxId() {
         return this.#runtime.id;
@@ -165,27 +169,50 @@ export class Sandbox {
     get client() {
         return this.#client;
     }
-    get envs() {
-        return this.#envs;
-    }
     /** E2B's home is /home/user and Runtime's is /workspace. The first time a
      * path or command names /home/user, it is made a link to /workspace (unless
      * something is already there), so paths written for E2B work. */
-    #ensureHome(text) {
+    #ensureHome(text, options = {}) {
+        const signal = options.signal;
+        signal?.throwIfAborted();
+        const wait = (pending) => {
+            if (!signal)
+                return pending;
+            return new Promise((resolve, reject) => {
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- rejects with the caller's abort reason as is, as the upstream SDK does
+                const abort = () => reject(signal.reason);
+                signal.addEventListener("abort", abort, { once: true });
+                pending.then(() => {
+                    signal.removeEventListener("abort", abort);
+                    resolve();
+                }, (error) => {
+                    signal.removeEventListener("abort", abort);
+                    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- passes the pending call's own failure through unchanged
+                    reject(error);
+                });
+            });
+        };
         if (this.#home || !text?.includes("/home/user"))
-            return this.#home ?? Promise.resolve();
-        this.#home = (async () => {
-            const result = await guard("sandbox", () => this.#runtime.exec("[ -e /home/user ] || sudo ln -s /workspace /home/user"));
+            return wait(this.#home ?? Promise.resolve());
+        const pending = (async () => {
+            const result = await guard("sandbox", () => this.#runtime.exec("[ -e /home/user ] || sudo ln -s /workspace /home/user", { signal }));
             if (result.exitCode !== 0 && typeof process !== "undefined")
                 process.emitWarning(`Could not link /home/user to /workspace: ${result.stderr.trim()}`, {
                     code: "RUNTIME_E2B_HOME",
                 });
         })();
-        return this.#home;
+        this.#home = pending;
+        pending.catch(() => {
+            if (this.#home === pending)
+                this.#home = undefined;
+        });
+        return wait(pending);
     }
     static async create(templateOrOpts, maybeOpts) {
         const opts = (typeof templateOrOpts === "string" ? maybeOpts : templateOrOpts) ?? {};
         const template = (typeof templateOrOpts === "string" ? templateOrOpts : opts.template) ?? this.defaultTemplate;
+        const options = request(opts);
+        options.signal?.throwIfAborted();
         refuseCreate(opts);
         const client = clientFor(opts);
         const input = {
@@ -195,9 +222,13 @@ export class Sandbox {
             // asked (autoResume); Runtime's automatic wake is the same thing (0093).
             ...(opts.lifecycle ? { autoWake: opts.lifecycle.autoResume === true } : {}),
             ...(opts.metadata && Object.keys(opts.metadata).length ? { labels: opts.metadata } : {}),
+            // Runtime keeps them with the sandbox: every command, terminal and
+            // interpreter in it gets them, from this client or any other.
+            ...(opts.envs && Object.keys(opts.envs).length ? { env: opts.envs } : {}),
             ...(opts.allowInternetAccess === false ? { network: { internet: false } } : {}),
         };
-        const source = await guard("other", () => resolveTemplate(client, template));
+        const source = await guard("other", () => resolveTemplate(client, template, options));
+        options.signal?.throwIfAborted();
         const create = {
             // A snapshot carries its own machine; everything else gets E2B's shape.
             ...(source.snapshot ? {} : DEFAULT_SHAPE),
@@ -205,8 +236,8 @@ export class Sandbox {
             ...source,
             ...opts.runtime?.create,
         };
-        const runtime = await guard("sandbox", () => client.sandboxes.create(create, request(opts)));
-        return new this(runtime, client, { ...opts.envs });
+        const runtime = await guard("sandbox", () => client.sandboxes.create(create, options));
+        return new this(runtime, client, opts.requestTimeoutMs);
     }
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
      * `timeoutMs` moves a running sandbox's end later, never earlier. */
@@ -214,7 +245,7 @@ export class Sandbox {
         const client = clientFor(opts);
         const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
         await resume(runtime, opts);
-        return new this(runtime, client);
+        return new this(runtime, client, opts.requestTimeoutMs);
     }
     /** Wakes this sandbox if it is paused. */
     async connect(opts = {}) {
@@ -309,8 +340,9 @@ export class Sandbox {
             // honoured after the forks exist, so this is refused before any are made.
             throw new NotSupportedError("A timeout for forks (fork timeoutMs)", "Fork without it, then call setTimeout(ms) on each fork.");
         const copies = await guard("sandbox", () => this.#runtime.fork({ count: opts.count ?? 1, ...request(opts) }));
+        // Copies keep the source's environment on Runtime's side.
         const Kind = this.constructor;
-        return copies.map((copy) => new Kind(copy, this.#client, { ...this.#envs }));
+        return copies.map((copy) => new Kind(copy, this.#client));
     }
     /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
      * with Sandbox.create(snapshotId). */
@@ -369,9 +401,6 @@ export class Sandbox {
         return share;
     }
     // ---- what Runtime does differently -----------------------------------
-    get pty() {
-        throw new NotSupportedError("E2B's pty module", "Use `await sandbox.runtime.terminal({ cols, rows, onData })` for an interactive terminal, or runtime.spawn(cmd, { pty: {} }).");
-    }
     get git() {
         throw new NotSupportedError("E2B's git module (deprecated by E2B too)", "Run git with sandbox.commands.run('git ...'); git is installed.");
     }
@@ -454,11 +483,13 @@ const PAUSED = ["pausing", "paused"];
 /** E2B's paginator: `while (p.hasNext) items.push(...(await p.nextItems()))`. */
 export class SandboxPaginator {
     #client;
+    #request;
     #filter;
     #page;
     #hasNext = true;
     constructor(client, opts) {
         this.#client = client;
+        this.#request = request(opts);
         const query = opts.query ?? {};
         if (query.template !== undefined && !STOCK_TEMPLATES.has(query.template))
             throw new NotSupportedError("Listing by template", "Filter by metadata instead: give sandboxes a metadata key when you create them.");
@@ -482,10 +513,13 @@ export class SandboxPaginator {
         return this.#page?.nextCursor ?? undefined;
     }
     async nextItems() {
+        this.#request.signal?.throwIfAborted();
         if (!this.#hasNext)
             throw new SandboxError("No more items to fetch.");
         const previous = this.#page;
-        const page = await guard("other", async () => previous ? await previous.next() : await this.#client.sandboxes.list(this.#filter));
+        const page = await guard("other", async () => previous
+            ? await previous.next()
+            : await this.#client.sandboxes.list(this.#filter, this.#request));
         this.#page = page ?? undefined;
         this.#hasNext = Boolean(page?.hasMore);
         return (page?.data ?? []).map(infoOf);

package/dist/errors.d.ts

@@ -1,3 +1,11 @@
+/** Every failure the SDK raises. `code` is stable and machine-readable,
+ * `hint` says what to do next, and `requestId` is what to quote in a report
+ * (runtime.feedback.submit, `runtime feedback`, or support). */
+/** A product switched off on this deployment, or paused on purpose: the API
+ * answers these 503s in fixed words (`serverFault` "off" in
+ * packages/cloud/src/api/respond.ts) and retrying cannot change them.
+ * host_unavailable and busy pass, and are retried. */
+export declare const DELIBERATE: ReadonlySet<string>;
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
  * frees room: the trial's slots, an email domain's trial slots, the account's
  * quota and the region's capacity. `sandboxes.create` waits them out, retrying