withruntime 0.10.0 → 0.11.0

package/dist/e2b/client.d.ts

@@ -3,6 +3,8 @@ import { Runtime } from "../client.js";
 export type RuntimeSandbox = Awaited<ReturnType<Runtime["sandboxes"]["create"]>>;
 /** What `Sandbox.create` sends to Runtime. */
 export type RuntimeCreate = NonNullable<Parameters<Runtime["sandboxes"]["create"]>[0]>;
+/** E2B's HTTP version for its API and sandboxes (e2b 2.52.0). */
+export type HttpVersion = "1.1" | "2";
 /** E2B's connection options, as far as they mean anything on Runtime. */
 export interface ConnectionOpts {
     /** A Runtime key. Default: RUNTIME_API_KEY, then E2B_API_KEY if it holds a
@@ -18,6 +20,9 @@ export interface ConnectionOpts {
     retries?: number;
     /** Accepted and ignored: Runtime's SDK does not take a logger. */
     logger?: unknown;
+    /** Checked as E2B checks it (and E2B_HTTP_VERSION), then left to Runtime's
+     * SDK, which picks its own transport. */
+    httpVersion?: HttpVersion;
     /** E2B endpoints. Refused: this package only talks to Runtime. */
     domain?: string;
     apiUrl?: string;

package/dist/e2b/client.js

@@ -1,5 +1,5 @@
 import { Runtime } from "../client.js";
-import { AuthenticationError, NotSupportedError } from "./errors.js";
+import { AuthenticationError, InvalidArgumentError, NotSupportedError } from "./errors.js";
 const env = (name) => typeof process === "undefined" ? undefined : process.env[name];
 const isE2BKey = (key) => key.startsWith("e2b_");
 /** Refuses the E2B-only connection options: they point at E2B, and quietly
@@ -18,6 +18,10 @@ export function refuseE2BConnection(opts = {}) {
                 ? "Set HTTPS_PROXY in the environment instead; Runtime's SDK reads it."
                 : "Remove it: this package talks only to Runtime (RUNTIME_API_URL overrides the API origin).");
     }
+    // E2B refuses any other version, from the option or the environment.
+    const version = opts.httpVersion ?? (env("E2B_HTTP_VERSION") || undefined);
+    if (version !== undefined && version !== "1.1" && version !== "2")
+        throw new InvalidArgumentError(`${opts.httpVersion === undefined ? "E2B_HTTP_VERSION" : "httpVersion"} must be '1.1' or '2', got '${version}'`);
     if (opts.debug)
         throw new NotSupportedError("E2B's debug mode (a local envd)", "Remove debug: true; there is no local Runtime guest to connect to.");
 }

package/dist/e2b/commands.d.ts

@@ -1,5 +1,5 @@
 import type { Process } from "../sandbox.js";
-import type { ProcessInfo as RuntimeProcessInfo } from "../types.js";
+import type { OutputEvent, ProcessInfo as RuntimeProcessInfo } from "../types.js";
 import type { RequestOptions } from "../transport.js";
 import type { RuntimeSandbox } from "./client.js";
 import { TimeoutError, type CommandResult } from "./errors.js";
@@ -12,9 +12,9 @@ export interface CommandRequestOpts {
 export interface CommandStartOpts extends CommandRequestOpts {
     background?: boolean;
     cwd?: string;
-    /** Only the default user. Runtime runs commands as `runtime`, the sandbox's
-     * owner, with passwordless sudo; E2B's `root` is refused rather than
-     * silently run as someone else. */
+    /** "user" (the default) is the sandbox's own user, `runtime`; any other
+     * user that exists in the sandbox, `root` included, runs it through
+     * `sudo -u`. An unknown user is refused, never created. */
     user?: Username;
     envs?: Record<string, string>;
     onStdout?: (data: string) => void | Promise<void>;
@@ -47,7 +47,6 @@ export interface SandboxContext {
 /** 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 declare function pidOf(processId: string): number;
-export declare function refuseUser(user: Username | undefined): void;
 export declare function timeoutFor(timeoutMs: number | undefined): number;
 /** One budget for lookup and mutation, including retries and queued input. */
 export declare function commandRequest(opts: CommandRequestOpts, defaultTimeoutMs?: number): RequestOptions;
@@ -88,13 +87,23 @@ export declare class Commands {
     /** Attaches to a running command; output from now on reaches the handle. */
     connect(pid: number, opts?: CommandConnectOpts): Promise<CommandHandle>;
 }
+/** A command whose output this handle reads from the request that started
+ * it: its process id, the rest of its events, the controller that ends the
+ * read, and the Runtime process, fetched only when something needs it. */
+export interface StartedStream {
+    started: true;
+    id: string;
+    events: AsyncIterator<OutputEvent>;
+    abort: AbortController;
+    process: () => Promise<Process>;
+}
 /** 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 declare class CommandHandle {
     #private;
     readonly pid: number;
-    constructor(process: Process, options: {
+    constructor(source: Process | StartedStream, options: {
         stdin: boolean;
         timeoutMs: number;
         cursor?: number;

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,10 +14,6 @@ export function pidOf(processId) {
     }
     return hash >>> 1 || 1;
 }
-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.');
-}
 export function timeoutFor(timeoutMs) {
     if (timeoutMs === undefined)
         return DEFAULT_TIMEOUT_MS;
@@ -121,14 +121,61 @@ export class Commands {
     }
     async run(cmd, opts = {}) {
         const opening = connectionRequest(opts, this.#ctx.requestTimeoutMs);
-        refuseUser(opts.user);
         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();
-            return this.#start(cmd, opts, opening.timeoutMs, opening.request, opening.deadline);
+            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 #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, {
@@ -224,11 +271,12 @@ async function deliver(signal, callback) {
  * arrives. */
 export class CommandHandle {
     pid;
+    #source;
     #process;
     #stdin;
     #timeoutMs;
     #requestTimeoutMs;
-    #abort = new AbortController();
+    #abort;
     #done;
     #stdout = "";
     #stderr = "";
@@ -237,9 +285,10 @@ 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;
@@ -260,14 +309,17 @@ export class CommandHandle {
         const signal = options.signal
             ? AbortSignal.any([options.signal, this.#abort.signal])
             : this.#abort.signal;
+        const source = this.#source;
         try {
             const outputOptions = {
                 ...(options.cursor ? { cursor: options.cursor } : {}),
                 signal,
             };
-            const output = options.pty
-                ? this.#process.outputBytes(outputOptions)
-                : this.#process.output(outputOptions);
+            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;
@@ -288,7 +340,8 @@ export class CommandHandle {
                     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 };
                 }
             }
         }
@@ -348,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", commandRequest({}, this.#requestTimeoutMs)));
+            const process = await this.#runtimeProcess();
+            await guard("sandbox", () => process.kill("SIGKILL", commandRequest({}, this.#requestTimeoutMs)));
             return true;
         }
         catch (error) {
@@ -366,12 +429,14 @@ export class CommandHandle {
         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, request));
+        const process = await this.#runtimeProcess();
+        await guard("sandbox", () => process.write(data, request));
     }
     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("", { ...request, 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,8 @@ 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;

package/dist/e2b/index.js

@@ -3,7 +3,7 @@ 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;

package/dist/e2b/pty.js

@@ -1,5 +1,6 @@
-import { CommandHandle, commandRequest, connectionRequest, killProcess, refuseUser, resolveProcess, } from "./commands.js";
+import { CommandHandle, commandRequest, connectionRequest, killProcess, resolveProcess, } from "./commands.js";
 import { guard, InvalidArgumentError, NotSupportedError } from "./errors.js";
+import { runAs, shellAs } from "./users.js";
 function dimensions(size) {
     for (const value of [size.cols, size.rows])
         if (!Number.isSafeInteger(value) || value <= 0)
@@ -13,16 +14,18 @@ export class Pty {
         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 () => {
+            // Another user's terminal is a login shell of theirs, through sudo -u.
+            const user = await runAs(this.ctx, opts.user, opening.request);
             await this.ctx.ensureHome(opts.cwd, opening.request);
             opening.request.signal?.throwIfAborted();
-            return this.ctx.runtime.spawn(["/bin/bash", "-i", "-l"], {
+            const shell = user ? shellAs(user, opts.cwd !== undefined) : ["/bin/bash", "-i", "-l"];
+            return this.ctx.runtime.spawn(shell, {
                 pty,
                 stdin: "pipe",
                 outputEncoding: "base64",

package/dist/e2b/sandbox.d.ts

@@ -30,8 +30,9 @@ export interface SandboxOpts extends ConnectionOpts {
     /** 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. */
+    /** Default 300 000, at most 24 hours. Runtime's leases run 60 s to 1 hour:
+     * shorter rounds up to 60 s (with a warning); longer gets an hour, moved on
+     * while this process runs, up to the time asked for. */
     timeoutMs?: number;
     /** Accepted and ignored, as E2B ignores it. */
     secure?: boolean;
@@ -88,6 +89,10 @@ export type SandboxListOpts = SandboxApiOpts & {
     limit?: number;
     nextToken?: string;
 };
+/** Test hook: renew every kept lease now, as the five-minute timer would. */
+export declare function renewLeases(): Promise<void>;
+/** Test hook: the end each kept sandbox is kept until. */
+export declare function keptLeases(): Map<string, number>;
 export declare class Sandbox {
     #private;
     protected readonly requestTimeoutMs: number;
@@ -118,8 +123,9 @@ export declare class Sandbox {
     /** Stops the sandbox. False when it was not found or had already ended. */
     static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>;
     kill(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
-    /** Sets the sandbox to end `timeoutMs` from now. Runtime leases only move
-     * later: a shorter timeout than the one it has is refused. */
+    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours; past an
+     * hour the lease is moved on while this process runs. Runtime cannot end a
+     * lease early, so an end sooner than the lease's is refused. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise<void>;
     setTimeout(timeoutMs: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>;
     static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>;
@@ -183,11 +189,15 @@ export declare class Sandbox {
     getMcpUrl(): never;
     getMcpToken(): Promise<never>;
 }
-/** E2B's paginator: `while (p.hasNext) items.push(...(await p.nextItems()))`. */
+/** E2B's paginator: `while (p.hasNext) items.push(...(await p.nextItems()))`.
+ * Runtime filters by state and metadata itself. A template, `startedAfter`,
+ * newest-first order or a saved `nextToken` are done here: every match is
+ * read once, then served a page at a time. */
 export declare class SandboxPaginator {
     #private;
     constructor(client: Runtime, opts: SandboxListOpts);
     get hasNext(): boolean;
+    /** Where the next page starts; `Sandbox.list({ nextToken })` resumes there. */
     get nextToken(): string | undefined;
     nextItems(): Promise<SandboxInfo[]>;
 }