withruntime 0.9.0 → 0.10.0

package/dist/e2b/commands.js

@@ -10,18 +10,57 @@ export function pidOf(processId) {
     }
     return hash >>> 1 || 1;
 }
-function refuseUser(user) {
+export function refuseUser(user) {
     if (user !== undefined && user !== "user")
         throw new NotSupportedError(`Running as the user "${user}"`, 'Runtime runs commands as its sandbox owner, with passwordless sudo: prefix the command with "sudo" to run it as root.');
 }
-function timeoutFor(timeoutMs) {
+export function timeoutFor(timeoutMs) {
     if (timeoutMs === undefined)
         return DEFAULT_TIMEOUT_MS;
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0)
         throw new InvalidArgumentError("timeoutMs must be a nonnegative whole number.");
     return timeoutMs;
 }
-function timedOut(timeoutMs) {
+/** One budget for lookup and mutation, including retries and queued input. */
+export function commandRequest(opts, defaultTimeoutMs = 60_000) {
+    opts.signal?.throwIfAborted();
+    const timeoutMs = timeoutFor(opts.requestTimeoutMs ?? defaultTimeoutMs);
+    const deadline = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const signal = opts.signal && deadline ? AbortSignal.any([opts.signal, deadline]) : (opts.signal ?? deadline);
+    return { timeoutMs: 0, ...(signal ? { signal } : {}) };
+}
+export async function findProcess(ctx, pid, options) {
+    options.signal?.throwIfAborted();
+    const processes = await guard("sandbox", () => ctx.runtime.processes.list(options));
+    options.signal?.throwIfAborted();
+    const matches = processes.filter((info) => pidOf(info.id) === pid && info.state === "running");
+    if (matches.length > 1)
+        throw new SandboxError(`More than one running command has pid ${pid}; use the native process id instead.`);
+    return matches[0];
+}
+export async function resolveProcess(ctx, pid, options) {
+    const info = await findProcess(ctx, pid, options);
+    if (!info)
+        throw new SandboxError(`No running command with pid ${pid}.`);
+    return guard("sandbox", () => ctx.runtime.processes.get(info.id, options));
+}
+export async function killProcess(ctx, pid, options) {
+    const info = await findProcess(ctx, pid, options);
+    if (!info)
+        return false;
+    try {
+        const process = await guard("sandbox", () => ctx.runtime.processes.get(info.id, options));
+        options.signal?.throwIfAborted();
+        await guard("sandbox", () => process.kill("SIGKILL", options));
+        return true;
+    }
+    catch (error) {
+        if (error instanceof SandboxError && error.statusCode === 404)
+            return false;
+        throw error;
+    }
+}
+export function timedOut(timeoutMs) {
     return new TimeoutError(`Command timed out after ${timeoutMs} ms: this error is likely due to exceeding 'timeoutMs'. ` +
         "Pass a larger 'timeoutMs', or 0 for no limit.");
 }
@@ -42,6 +81,25 @@ function toResult(result) {
         ...(result.truncated ? { truncated: true } : {}),
     };
 }
+/** The subscription deadline includes the opening handshake. */
+export function connectionRequest(opts, defaultTimeoutMs) {
+    const timeoutMs = timeoutFor(opts.timeoutMs);
+    const deadline = timeoutMs > 0 ? performance.now() + timeoutMs : undefined;
+    const connectionTimeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const signal = connectionTimeout && opts.signal
+        ? AbortSignal.any([connectionTimeout, opts.signal])
+        : (connectionTimeout ?? opts.signal);
+    return {
+        timeoutMs,
+        deadline,
+        request: commandRequest({ ...opts, signal }, defaultTimeoutMs),
+        failure: (error) => {
+            if (connectionTimeout?.aborted)
+                throw timedOut(timeoutMs);
+            throw error;
+        },
+    };
+}
 function settle(result, timeoutMs) {
     if (result.timedOut)
         throw timedOut(timeoutMs);
@@ -62,76 +120,69 @@ export class Commands {
         return envs && Object.keys(envs).length ? { env: envs } : {};
     }
     async run(cmd, opts = {}) {
-        opts.signal?.throwIfAborted();
+        const opening = connectionRequest(opts, this.#ctx.requestTimeoutMs);
         refuseUser(opts.user);
-        await this.#ctx.ensureHome(`${cmd}\n${opts.cwd ?? ""}`);
-        const timeoutMs = timeoutFor(opts.timeoutMs);
-        const handle = await this.#start(cmd, opts, timeoutMs);
+        const handle = await (async () => {
+            await this.#ctx.ensureHome(`${cmd}\n${opts.cwd ?? ""}`, opening.request);
+            opening.request.signal?.throwIfAborted();
+            return this.#start(cmd, opts, opening.timeoutMs, opening.request, opening.deadline);
+        })().catch(opening.failure);
         return opts.background ? handle : handle.wait();
     }
-    async #start(cmd, opts, timeoutMs) {
-        opts.signal?.throwIfAborted();
-        const requestDeadline = opts.requestTimeoutMs
-            ? AbortSignal.timeout(opts.requestTimeoutMs)
-            : undefined;
-        const signals = [opts.signal, requestDeadline].filter((signal) => signal !== undefined);
+    async #start(cmd, opts, timeoutMs, request, deadline) {
+        request.signal?.throwIfAborted();
         const process = await guard("sandbox", () => this.#ctx.runtime.spawn(cmd, {
             ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
             ...this.#env(opts.envs),
             ...(opts.stdin ? { stdin: "pipe" } : {}),
-            ...(signals.length ? { signal: AbortSignal.any(signals) } : {}),
+            request,
         }));
         return new CommandHandle(process, {
             stdin: opts.stdin === true,
             timeoutMs,
+            deadline,
+            requestTimeoutMs: this.#ctx.requestTimeoutMs,
             signal: opts.signal,
             ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
             ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
         });
     }
     /** Running commands. */
-    async list(_opts = {}) {
-        const processes = await guard("sandbox", () => this.#ctx.runtime.processes.list());
+    async list(opts = {}) {
+        const request = commandRequest(opts, this.#ctx.requestTimeoutMs);
+        const processes = await guard("sandbox", () => this.#ctx.runtime.processes.list(request));
         return processes.filter((info) => info.state === "running").map(describe);
     }
-    async #find(pid) {
-        const processes = await guard("sandbox", () => this.#ctx.runtime.processes.list());
-        return processes.find((info) => pidOf(info.id) === pid && info.state === "running");
-    }
-    async #process(pid) {
-        const info = await this.#find(pid);
-        if (!info)
-            throw new SandboxError(`No running command with pid ${pid}.`);
-        return guard("sandbox", () => this.#ctx.runtime.processes.get(info.id));
-    }
     /** Kills a command with SIGKILL, as E2B does. False when there is none. */
-    async kill(pid, _opts = {}) {
-        const info = await this.#find(pid);
-        if (!info)
-            return false;
-        const process = await guard("sandbox", () => this.#ctx.runtime.processes.get(info.id));
-        await guard("sandbox", () => process.kill("SIGKILL"));
-        return true;
+    async kill(pid, opts = {}) {
+        return killProcess(this.#ctx, pid, commandRequest(opts, this.#ctx.requestTimeoutMs));
     }
     /** Sends input to a command started with `stdin: true`. */
-    async sendStdin(pid, data, _opts = {}) {
-        const process = await this.#process(pid);
+    async sendStdin(pid, data, opts = {}) {
+        const request = commandRequest(opts, this.#ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.#ctx, pid, request);
         if (!process.info.stdinOpen)
             throw new InvalidArgumentError(`The command with pid ${pid} was not started with stdin: true, so its input is closed.`);
-        await guard("sandbox", () => process.write(data));
+        request.signal?.throwIfAborted();
+        await guard("sandbox", () => process.write(data, request));
     }
-    async closeStdin(pid, _opts = {}) {
-        const process = await this.#process(pid);
-        await guard("sandbox", () => process.write("", { eof: true }));
+    async closeStdin(pid, opts = {}) {
+        const request = commandRequest(opts, this.#ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.#ctx, pid, request);
+        request.signal?.throwIfAborted();
+        await guard("sandbox", () => process.write("", { ...request, eof: true }));
     }
     /** Attaches to a running command; output from now on reaches the handle. */
     async connect(pid, opts = {}) {
-        const process = await this.#process(pid);
+        const opening = connectionRequest(opts, this.#ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.#ctx, pid, opening.request).catch(opening.failure);
         return new CommandHandle(process, {
             stdin: process.info.stdinOpen,
-            timeoutMs: timeoutFor(opts.timeoutMs),
+            timeoutMs: opening.timeoutMs,
+            deadline: opening.deadline,
             signal: opts.signal,
             cursor: process.info.outputBytes,
+            requestTimeoutMs: this.#ctx.requestTimeoutMs,
             ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
             ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
         });
@@ -146,6 +197,28 @@ function describe(info) {
         cwd: info.cwd,
     };
 }
+/** Reader cancellation also releases a callback whose promise never settles. */
+async function deliver(signal, callback) {
+    signal.throwIfAborted();
+    let cancelled;
+    const aborted = new Promise((_, 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
+        cancelled = () => reject(signal.reason);
+        signal.addEventListener("abort", cancelled, { once: true });
+    });
+    try {
+        await Promise.race([
+            Promise.resolve().then(() => {
+                signal.throwIfAborted();
+                return callback();
+            }),
+            aborted,
+        ]);
+    }
+    finally {
+        signal.removeEventListener("abort", cancelled);
+    }
+}
 /** A command started in the background: E2B's CommandHandle over a Runtime
  * process. Output streams into `stdout`/`stderr` and the callbacks as it
  * arrives. */
@@ -154,6 +227,7 @@ export class CommandHandle {
     #process;
     #stdin;
     #timeoutMs;
+    #requestTimeoutMs;
     #abort = new AbortController();
     #done;
     #stdout = "";
@@ -168,13 +242,16 @@ export class CommandHandle {
         this.pid = pidOf(process.id);
         this.#stdin = options.stdin;
         this.#timeoutMs = options.timeoutMs;
+        this.#requestTimeoutMs = options.requestTimeoutMs;
         // E2B's timeout limits the subscription. It never asks us to kill the
         // process: the sandbox lease still bounds the workload after disconnect.
         if (options.timeoutMs > 0) {
             this.#deadline = setTimeout(() => {
                 this.#failure = timedOut(options.timeoutMs);
                 this.#abort.abort();
-            }, options.timeoutMs);
+            }, options.deadline === undefined
+                ? options.timeoutMs
+                : Math.max(0, options.deadline - performance.now()));
             this.#deadline.unref?.();
         }
         this.#done = this.#follow(options);
@@ -184,19 +261,28 @@ export class CommandHandle {
             ? AbortSignal.any([options.signal, this.#abort.signal])
             : this.#abort.signal;
         try {
-            for await (const event of this.#process.output({
+            const outputOptions = {
                 ...(options.cursor ? { cursor: options.cursor } : {}),
                 signal,
-            })) {
-                if (this.#disconnected || signal.aborted)
+            };
+            const output = options.pty
+                ? this.#process.outputBytes(outputOptions)
+                : this.#process.output(outputOptions);
+            for await (const event of output) {
+                if (this.#disconnected)
                     break;
-                if (event.type === "stdout") {
+                signal.throwIfAborted();
+                if ((event.type === "stdout" || event.type === "stderr") &&
+                    event.data instanceof Uint8Array) {
+                    await deliver(signal, () => options.onData?.(event.data));
+                }
+                else if (event.type === "stdout" && typeof event.data === "string") {
                     this.#stdout += event.data;
-                    await options.onStdout?.(event.data);
+                    await deliver(signal, () => options.onStdout?.(event.data));
                 }
-                else if (event.type === "stderr") {
+                else if (event.type === "stderr" && typeof event.data === "string") {
                     this.#stderr += event.data;
-                    await options.onStderr?.(event.data);
+                    await deliver(signal, () => options.onStderr?.(event.data));
                 }
                 else if (event.type === "truncated") {
                     this.#truncated = true;
@@ -267,7 +353,7 @@ export class CommandHandle {
         if (this.#exit)
             return false;
         try {
-            await guard("sandbox", () => this.#process.kill("SIGKILL"));
+            await guard("sandbox", () => this.#process.kill("SIGKILL", commandRequest({}, this.#requestTimeoutMs)));
             return true;
         }
         catch (error) {
@@ -276,14 +362,16 @@ export class CommandHandle {
             throw error;
         }
     }
-    async sendStdin(data, _opts = {}) {
+    async sendStdin(data, opts = {}) {
+        const request = commandRequest(opts, this.#requestTimeoutMs);
         if (!this.#stdin)
             throw new InvalidArgumentError("The command was not started with stdin: true, so its input is closed.");
-        await guard("sandbox", () => this.#process.write(data));
+        await guard("sandbox", () => this.#process.write(data, request));
     }
-    async closeStdin(_opts = {}) {
+    async closeStdin(opts = {}) {
+        const request = commandRequest(opts, this.#requestTimeoutMs);
         if (!this.#stdin)
             throw new InvalidArgumentError("The command was not started with stdin: true.");
-        await guard("sandbox", () => this.#process.write("", { eof: true }));
+        await guard("sandbox", () => this.#process.write("", { ...request, eof: true }));
     }
 }

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: {
@@ -93,6 +94,7 @@ export declare class Sandbox {
     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, requestTimeoutMs?: number);
     get sandboxId(): string;
@@ -167,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 };
@@ -135,6 +137,7 @@ export class Sandbox {
     static defaultTemplate = "base";
     files;
     commands;
+    pty;
     #client;
     #runtime;
     #home;
@@ -146,12 +149,14 @@ export class Sandbox {
         this.#runtime = runtime;
         this.#client = client;
         const ctx = {
-            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;
@@ -167,21 +172,47 @@ export class Sandbox {
     /** 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 = {
@@ -196,7 +227,8 @@ export class Sandbox {
             ...(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),
@@ -204,7 +236,7 @@ export class Sandbox {
             ...source,
             ...opts.runtime?.create,
         };
-        const runtime = await guard("sandbox", () => client.sandboxes.create(create, request(opts)));
+        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
@@ -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/file-source.d.ts

@@ -0,0 +1,16 @@
+export type StreamUploadSource = string | Blob | AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>;
+export type UploadScope = {
+    signal?: AbortSignal;
+    check(): void;
+    wait<T>(pending: Promise<T>): Promise<T>;
+};
+export type PreparedFileSource = {
+    size: number;
+    sha256: string;
+    chunkAt(offset: number, length: number): Promise<Uint8Array>;
+    close(): Promise<void>;
+};
+/** ARCHITECTURE.md section 10, Folders over HTTP: unknown-length inputs use
+ * bounded private disk staging; known files and Blobs remain repeatable inputs.
+ * Size and digest are established before the remote upload can begin. */
+export declare function prepareFileSource(input: StreamUploadSource, scope: UploadScope): Promise<PreparedFileSource>;