withruntime 0.9.0 → 0.11.0

package/dist/e2b/commands.js

@@ -1,5 +1,9 @@
-import { CommandExitError, guard, InvalidArgumentError, NotSupportedError, SandboxError, TimeoutError, translate, } from "./errors.js";
+import { CommandExitError, guard, InvalidArgumentError, SandboxError, TimeoutError, translate, } from "./errors.js";
+import { commandAs, runAs } from "./users.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
+/** How long a command may run on Runtime: a day, E2B's longest sandbox. E2B's
+ * own `timeoutMs` bounds only the connection, so the process gets this. */
+const PROCESS_LIFETIME_MS = 86_400_000;
 /** E2B's pids are numbers; Runtime's process ids are strings. The number is a
  * 31-bit FNV-1a hash of the id, so every client derives the same one. */
 export function pidOf(processId) {
@@ -10,18 +14,53 @@ export function pidOf(processId) {
     }
     return hash >>> 1 || 1;
 }
-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,116 @@ export class Commands {
         return envs && Object.keys(envs).length ? { env: envs } : {};
     }
     async run(cmd, opts = {}) {
-        opts.signal?.throwIfAborted();
-        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 opening = connectionRequest(opts, this.#ctx.requestTimeoutMs);
+        const handle = await (async () => {
+            const user = await runAs(this.#ctx, opts.user, opening.request);
+            await this.#ctx.ensureHome(`${cmd}\n${opts.cwd ?? ""}`, opening.request);
+            opening.request.signal?.throwIfAborted();
+            const command = user ? commandAs(user, cmd, opts.cwd !== undefined) : cmd;
+            // A command waited on here is read from its first byte by the request
+            // that starts it, so Runtime holds a fast writer back rather than
+            // dropping what it printed before the first read: the result is whole.
+            return opts.background || opts.stdin
+                ? this.#start(command, opts, opening.timeoutMs, opening.request, opening.deadline)
+                : this.#stream(command, 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 #stream(cmd, opts, timeoutMs, request, deadline) {
+        const abort = new AbortController();
+        const signal = opts.signal ? AbortSignal.any([opts.signal, abort.signal]) : abort.signal;
+        const stopOpening = () => abort.abort(request.signal?.reason);
+        request.signal?.addEventListener("abort", stopOpening, { once: true });
+        const stream = this.#ctx.runtime.execStream(cmd, {
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            ...this.#env(opts.envs),
+            timeoutMs: PROCESS_LIFETIME_MS,
+            signal,
+        });
+        const events = stream[Symbol.asyncIterator]();
+        try {
+            const first = await guard("sandbox", () => events.next());
+            if (first.done || first.value.type !== "start")
+                throw new SandboxError("The command's output began without a start.");
+            const runtime = this.#ctx.runtime;
+            const processId = first.value.processId;
+            return new CommandHandle({
+                started: true,
+                id: processId,
+                events,
+                abort,
+                process: () => runtime.processes.get(processId, commandRequest({}, this.#ctx.requestTimeoutMs)),
+            }, {
+                stdin: false,
+                timeoutMs,
+                deadline,
+                requestTimeoutMs: this.#ctx.requestTimeoutMs,
+                ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+                ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+            });
+        }
+        catch (error) {
+            abort.abort();
+            throw error;
+        }
+        finally {
+            request.signal?.removeEventListener("abort", stopOpening);
+        }
+    }
+    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,15 +244,39 @@ 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. */
 export class CommandHandle {
     pid;
+    #source;
     #process;
     #stdin;
     #timeoutMs;
-    #abort = new AbortController();
+    #requestTimeoutMs;
+    #abort;
     #done;
     #stdout = "";
     #stderr = "";
@@ -163,18 +285,22 @@ export class CommandHandle {
     #failure;
     #disconnected = false;
     #deadline;
-    constructor(process, options) {
-        this.#process = process;
-        this.pid = pidOf(process.id);
+    constructor(source, options) {
+        this.#source = source;
+        this.#abort = "started" in source ? source.abort : new AbortController();
+        this.pid = pidOf(source.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);
@@ -183,26 +309,39 @@ export class CommandHandle {
         const signal = options.signal
             ? AbortSignal.any([options.signal, this.#abort.signal])
             : this.#abort.signal;
+        const source = this.#source;
         try {
-            for await (const event of this.#process.output({
+            const outputOptions = {
                 ...(options.cursor ? { cursor: options.cursor } : {}),
                 signal,
-            })) {
-                if (this.#disconnected || signal.aborted)
+            };
+            const output = "started" in source
+                ? { [Symbol.asyncIterator]: () => source.events }
+                : options.pty
+                    ? source.outputBytes(outputOptions)
+                    : source.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;
                 }
                 else if (event.type === "exit") {
-                    this.#exit = { exitCode: event.exitCode, timedOut: event.timedOut };
+                    const exit = event;
+                    this.#exit = { exitCode: exit.exitCode, timedOut: exit.timedOut };
                 }
             }
         }
@@ -262,12 +401,22 @@ export class CommandHandle {
         this.#abort.abort();
         await Promise.resolve();
     }
+    /** The Runtime process, fetched once when a started stream needs it. */
+    #runtimeProcess() {
+        const source = this.#source;
+        if (!("started" in source))
+            return Promise.resolve(source);
+        this.#process ??= guard("sandbox", source.process);
+        this.#process.catch(() => (this.#process = undefined));
+        return this.#process;
+    }
     /** Kills the command with SIGKILL. False when it had already ended. */
     async kill() {
         if (this.#exit)
             return false;
         try {
-            await guard("sandbox", () => this.#process.kill("SIGKILL"));
+            const process = await this.#runtimeProcess();
+            await guard("sandbox", () => process.kill("SIGKILL", commandRequest({}, this.#requestTimeoutMs)));
             return true;
         }
         catch (error) {
@@ -276,14 +425,18 @@ 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));
+        const process = await this.#runtimeProcess();
+        await guard("sandbox", () => 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 }));
+        const process = await this.#runtimeProcess();
+        await guard("sandbox", () => process.write("", { ...request, eof: true }));
     }
 }

package/dist/e2b/errors.d.ts

@@ -46,6 +46,13 @@ export declare class NotSupportedError extends SandboxError {
     readonly alternative: string;
     constructor(feature: string, alternative: string, message?: string);
 }
+/** Runtime's addition, for `getHost` and `getPublicHost`: a free-trial
+ * sandbox shares a port only privately, so a request needs the port's token,
+ * and a host name alone cannot carry one. The message says what works. A
+ * NotSupportedError, so code that catches those catches this too. */
+export declare class PublicPreviewNotAllowedError extends NotSupportedError {
+    constructor(sandboxId: string, port: number | undefined, message?: string);
+}
 /** What `commands.run` resolves with, as in E2B. */
 export interface CommandResult {
     exitCode: number;

package/dist/e2b/errors.js

@@ -72,6 +72,23 @@ export class NotSupportedError extends SandboxError {
         this.code = "not_supported";
     }
 }
+/** Runtime's addition, for `getHost` and `getPublicHost`: a free-trial
+ * sandbox shares a port only privately, so a request needs the port's token,
+ * and a host name alone cannot carry one. The message says what works. A
+ * NotSupportedError, so code that catches those catches this too. */
+export class PublicPreviewNotAllowedError extends NotSupportedError {
+    constructor(sandboxId, port, message) {
+        const where = port === undefined ? "<port>" : String(port);
+        const alternative = `For an address that works on the trial, use (await sandbox.runtime.previews.create(${where})).urlWithToken: ` +
+            "it carries the token, in a browser, fetch or curl. For other paths on it, send the token as the " +
+            "x-runtime-preview-token header or the runtime_preview_token query parameter. A public host needs a paid " +
+            "sandbox, which is the account owner's decision.";
+        super("A public address on a free-trial sandbox", alternative, message ??
+            `Sandbox ${sandboxId} runs on the free trial, where a shared port is private: every request needs the ` +
+                `port's token, and a host name alone cannot carry one. ${alternative}`);
+        this.code = "public_preview_not_allowed";
+    }
+}
 /** Thrown by `commands.run` and `CommandHandle.wait` when the command exits
  * with a code other than 0. It carries the result, as in E2B. */
 export class CommandExitError extends SandboxError {
@@ -113,6 +130,9 @@ export function translate(error, subject = "other") {
         // A product switched off on purpose (forks, previews): Runtime's own words
         // say what is off and what to use meanwhile.
         out = new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", message);
+    else if (error.code === "public_preview_not_allowed")
+        // A 403 that is about the sandbox's funding, not the key.
+        out = new PublicPreviewNotAllowedError("", undefined, message);
     else if (error.status === 401 || error.status === 403)
         out = new AuthenticationError(message);
     else if (error.code === "file_not_found" || (error.status === 404 && subject === "file"))

package/dist/e2b/filesystem.d.ts

@@ -51,7 +51,8 @@ export type WriteEntry = {
 export interface FilesystemRequestOpts {
     requestTimeoutMs?: number;
     signal?: AbortSignal;
-    /** Only the default user; see CommandStartOpts.user. */
+    /** "user" (the default) acts as the sandbox's own user through Runtime's
+     * file API; any other existing user, `root` included, through `sudo -u`. */
     user?: Username;
 }
 export interface FilesystemReadOpts extends FilesystemRequestOpts {

package/dist/e2b/filesystem.js

@@ -1,5 +1,6 @@
 import { request } from "./client.js";
 import { FileNotFoundError, guard, InvalidArgumentError, NotSupportedError, TimeoutError, } from "./errors.js";
+import { FilesAs, runAs } from "./users.js";
 export var FileType;
 (function (FileType) {
     FileType["FILE"] = "file";
@@ -20,8 +21,6 @@ function absolute(path) {
     return path.startsWith("/") ? path : `${HOME}/${path.replace(/^\.\//, "")}`;
 }
 function refuse(opts) {
-    if (opts.user !== undefined && opts.user !== "user")
-        throw new NotSupportedError(`File access as the user "${opts.user}"`, "Runtime's file calls act as the sandbox owner; use commands.run('sudo ...') for root-owned paths.");
     if (opts.metadata && Object.keys(opts.metadata).length)
         throw new NotSupportedError("File metadata (user.e2b.* extended attributes)", "Keep the metadata beside the file, for example in a JSON file.");
 }
@@ -80,12 +79,25 @@ export class Filesystem {
         opts.signal?.throwIfAborted();
         return absolute(path);
     }
+    /** The calls as another Linux user, or undefined for the sandbox's own. */
+    async #as(opts) {
+        if (opts.user === undefined || opts.user === "user")
+            return undefined;
+        const options = request(opts);
+        const user = await runAs(this.#ctx, opts.user, options);
+        return user ? new FilesAs(this.#ctx, user, options) : undefined;
+    }
     async read(path, opts = {}) {
         const file = await this.#path(path, opts);
+        const as = await this.#as(opts);
         // A real stream, any size, never the whole file held first.
-        if (opts.format === "stream")
+        if (opts.format === "stream" && !as)
             return guard("file", () => this.#files.readStream(file, request(opts)));
-        const bytes = await guard("file", () => this.#files.read(file, request(opts)));
+        const bytes = as
+            ? await as.read(file)
+            : await guard("file", () => this.#files.read(file, request(opts)));
+        if (opts.format === "stream")
+            return new Blob([bytes]).stream();
         switch (opts.format) {
             case "bytes":
                 return bytes;
@@ -109,19 +121,29 @@ export class Filesystem {
     }
     async #writeOne(path, data, opts) {
         const file = await this.#path(path, opts);
+        const as = await this.#as(opts);
         const bytes = await bytesOf(data);
-        await guard("file", () => this.#files.write(file, bytes, request(opts)));
+        if (as)
+            await as.write(file, bytes);
+        else
+            await guard("file", () => this.#files.write(file, bytes, request(opts)));
         return { name: basename(file), type: FileType.FILE, path: file };
     }
     /** A directory's entries, hidden ones included; `depth` goes deeper. */
     async list(path, opts = {}) {
         const dir = await this.#path(path, opts);
+        const as = await this.#as(opts);
+        if (as)
+            return (await as.list(dir, opts.depth ?? 1)).map(entryInfo);
         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);
+        const as = await this.#as(opts);
+        if (as)
+            return as.makeDir(dir);
         if (await guard("file", () => this.#files.exists(dir, request(opts))))
             return false;
         await guard("file", () => this.#files.mkdir(dir, { parents: true, ...request(opts) }));
@@ -131,20 +153,33 @@ export class Filesystem {
     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, ...request(opts) }));
+        const as = await this.#as(opts);
+        if (as)
+            await as.rename(from, to);
+        else
+            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);
+        const as = await this.#as(opts);
+        if (as)
+            return as.remove(target);
         await guard("file", () => this.#files.remove(target, { recursive: true, ...request(opts) }));
     }
     async exists(path, opts = {}) {
         const target = await this.#path(path, opts);
+        const as = await this.#as(opts);
+        if (as)
+            return as.exists(target);
         return guard("file", () => this.#files.exists(target, request(opts)));
     }
     async getInfo(path, opts = {}) {
         const target = await this.#path(path, opts);
+        const as = await this.#as(opts);
+        if (as)
+            return entryInfo(await as.stat(target));
         const stat = await guard("file", () => this.#files.stat(target, request(opts)));
         if (!stat.exists)
             throw new FileNotFoundError(`${target} does not exist.`);
@@ -154,6 +189,8 @@ export class Filesystem {
      * subsecond subscriptions; 0 runs until stopped or the sandbox ends. */
     async watchDir(path, onEvent, opts = {}) {
         opts.signal?.throwIfAborted();
+        if (opts.user !== undefined && opts.user !== "user")
+            throw new NotSupportedError(`Watching a directory as the user "${opts.user}"`, "Watch it as the sandbox's own user (leave user out); Runtime's watch reports changes made by anyone.");
         if (opts.allowNetworkMounts)
             throw new NotSupportedError("Watching network mounts", "Watch a local sandbox directory instead.");
         const lifetime = opts.timeoutMs ?? 60000;

package/dist/e2b/index.d.ts

@@ -10,8 +10,9 @@ import { Sandbox } from "./sandbox.js";
 export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, type SandboxOpts, type SandboxConnectOpts, type SandboxApiOpts, type SandboxInfo, type SandboxListOpts, type SandboxState, type SandboxLifecycle, type SandboxOnTimeout, type SnapshotInfo, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, type CommandStartOpts, type CommandConnectOpts, type CommandRequestOpts, type ProcessInfo, type Username, } from "./commands.js";
 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 { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, type CommandResult, } from "./errors.js";
+export type { ConnectionOpts, HttpVersion, 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

@@ -3,7 +3,8 @@ import { Sandbox } from "./sandbox.js";
 export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, } from "./sandbox.js";
 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 { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, } 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>;
+}