withruntime 0.10.0 → 0.11.1

package/dist/e2b/sandbox.js

@@ -1,6 +1,6 @@
 import { clientFor, request, } from "./client.js";
 import { Commands } from "./commands.js";
-import { guard, InvalidArgumentError, NotSupportedError, SandboxError, SandboxNotFoundError, TemplateError, } from "./errors.js";
+import { guard, InvalidArgumentError, NotSupportedError, PublicPreviewNotAllowedError, 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
@@ -9,21 +9,30 @@ 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 const DEFAULT_SHAPE = { vcpu: 2, memoryMiB: 512 };
-/** E2B's default sandbox timeout, 300 s. */
+/** E2B's default sandbox timeout, 300 s. Not sent: a sandbox created with no
+ * timeoutMs has no time limit on Runtime, running while it works and pausing
+ * when idle (0300). Kept for code that imports it. */
 export const DEFAULT_TIMEOUT_MS = 300_000;
 /** Runtime's lease bounds (MAX_TIMEOUT_SECONDS in the API). */
 const MIN_LEASE_SECONDS = 60;
 const MAX_LEASE_SECONDS = 3600;
+/** E2B's longest sandbox timeout, 24 hours (its Pro plan). */
+const LONGEST_TIMEOUT_MS = 86_400_000;
 /** E2B template names that mean "the stock environment": Runtime's default image. */
 const STOCK_TEMPLATES = new Set(["base", "code-interpreter-v1", "code-interpreter"]);
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 let warnedShortLease = false;
+/** E2B's own bound since 2.52.0: refused before anything happens. */
+const MAX_FORK_COUNT = 20;
+function checkForkCount(count) {
+    if (count !== undefined && (!Number.isInteger(count) || count < 1 || count > MAX_FORK_COUNT))
+        throw new InvalidArgumentError(`count must be an integer between 1 and ${MAX_FORK_COUNT}`);
+}
+/** The first lease for `timeoutMs`: up to an hour; `keepUntil` carries a
+ * longer timeout on from there. */
 function leaseSeconds(timeoutMs) {
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
-        throw new InvalidArgumentError(`timeoutMs must be a positive number, not ${timeoutMs}.`);
-    const seconds = Math.ceil(timeoutMs / 1000);
-    if (seconds > MAX_LEASE_SECONDS)
-        throw new NotSupportedError(`A sandbox timeout of ${timeoutMs} ms (over one hour)`, "Runtime leases last up to an hour (3_600_000 ms); call sandbox.setTimeout(...) before it ends to keep going, as often as needed.");
+    checkTimeout(timeoutMs);
+    const seconds = Math.min(Math.ceil(timeoutMs / 1000), MAX_LEASE_SECONDS);
     if (seconds < MIN_LEASE_SECONDS) {
         if (!warnedShortLease && typeof process !== "undefined") {
             warnedShortLease = true;
@@ -33,6 +42,87 @@ function leaseSeconds(timeoutMs) {
     }
     return seconds;
 }
+function checkTimeout(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new InvalidArgumentError(`timeoutMs must be a positive number, not ${timeoutMs}.`);
+    if (timeoutMs > LONGEST_TIMEOUT_MS)
+        throw new InvalidArgumentError(`timeoutMs is at most 24 hours (86_400_000 ms), as on E2B, not ${timeoutMs}.`);
+}
+/* Timeouts over an hour. Runtime's lease reaches at most an hour ahead of
+   now, and E2B's timeout up to a day. While this process runs, the adapter
+   moves the lease on every five minutes, as far as an hour ahead and never
+   past the end asked for. One keeper per sandbox, whichever object asked.
+   If the process ends first, the sandbox ends when its lease does, at most
+   an hour later; it is never kept past the time asked for. */
+const KEEP_EVERY_MS = 5 * 60_000;
+/** Kept under the API's hour, for the clocks and the trip. */
+const KEEP_AHEAD_MS = (MAX_LEASE_SECONDS - 30) * 1000;
+const keepers = new Map();
+let warnedKeeper = false;
+/** Keeps `runtime` until `until` (epoch ms), or stops keeping it when that
+ * is within the hour its lease can already reach. */
+function keepUntil(runtime, until) {
+    const keeper = keepers.get(runtime.id);
+    if (until - Date.now() <= MAX_LEASE_SECONDS * 1000)
+        return stopKeeping(runtime.id);
+    if (keeper) {
+        keeper.until = until;
+        keeper.runtime = runtime;
+        return;
+    }
+    const made = { until, runtime };
+    keepers.set(runtime.id, made);
+    schedule(made);
+}
+function stopKeeping(sandboxId) {
+    const keeper = keepers.get(sandboxId);
+    if (keeper?.timer !== undefined)
+        clearTimeout(keeper.timer);
+    keepers.delete(sandboxId);
+}
+function schedule(keeper) {
+    keeper.timer = setTimeout(() => void renew(keeper), KEEP_EVERY_MS);
+    // Never what keeps a Node or Bun process running.
+    keeper.timer.unref?.();
+}
+async function renew(keeper) {
+    const id = keeper.runtime.id;
+    if (keepers.get(id) !== keeper)
+        return;
+    try {
+        await keeper.runtime.refresh();
+        const current = state(keeper.runtime);
+        if (current === "stopped")
+            return stopKeeping(id);
+        if (current === "running") {
+            if (keeper.runtime.info.endsAt === null)
+                return stopKeeping(id);
+            const end = Date.parse(keeper.runtime.info.expiresAt);
+            const want = Math.min(keeper.until, Date.now() + KEEP_AHEAD_MS);
+            const later = Math.floor((want - end) / 1000);
+            if (later >= 1)
+                await keeper.runtime.extend(later);
+            if (Date.parse(keeper.runtime.info.expiresAt) >= keeper.until - 1000)
+                return stopKeeping(id);
+        }
+    }
+    catch (error) {
+        if (!warnedKeeper && typeof process !== "undefined" && process.emitWarning) {
+            warnedKeeper = true;
+            process.emitWarning(`Could not extend sandbox ${id}'s lease toward its timeout: ${error instanceof Error ? error.message : String(error)}. Trying again in five minutes.`, { code: "RUNTIME_E2B_LEASE" });
+        }
+    }
+    if (keepers.get(id) === keeper)
+        schedule(keeper);
+}
+/** Test hook: renew every kept lease now, as the five-minute timer would. */
+export async function renewLeases() {
+    await Promise.all([...keepers.values()].map((keeper) => renew(keeper)));
+}
+/** Test hook: the end each kept sandbox is kept until. */
+export function keptLeases() {
+    return new Map([...keepers].map(([id, keeper]) => [id, keeper.until]));
+}
 function onLeaseEnd(lifecycle) {
     if (!lifecycle)
         return "stop";
@@ -114,7 +204,8 @@ function infoOf(runtime) {
         ...(info.name ? { name: info.name } : {}),
         metadata: info.labels ?? {},
         startedAt: new Date(info.createdAt),
-        endAt: new Date(info.expiresAt),
+        // With no time limit, where it is paid up to: always ahead, moving on.
+        endAt: new Date(info.endsAt ?? info.expiresAt),
         state: current === "stopped" ? "paused" : current,
         cpuCount: info.vcpu,
         memoryMB: info.memoryMiB,
@@ -215,8 +306,10 @@ export class Sandbox {
         options.signal?.throwIfAborted();
         refuseCreate(opts);
         const client = clientFor(opts);
+        // No timeoutMs, no time limit: it runs while it works (0300).
+        const asked = opts.timeoutMs === undefined ? undefined : Date.now() + opts.timeoutMs;
         const input = {
-            timeoutSeconds: leaseSeconds(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            ...(opts.timeoutMs === undefined ? {} : { timeoutSeconds: leaseSeconds(opts.timeoutMs) }),
             onLeaseEnd: onLeaseEnd(opts.lifecycle),
             // With a lifecycle, E2B resumes a paused sandbox on traffic only when
             // asked (autoResume); Runtime's automatic wake is the same thing (0093).
@@ -237,6 +330,8 @@ export class Sandbox {
             ...opts.runtime?.create,
         };
         const runtime = await guard("sandbox", () => client.sandboxes.create(create, options));
+        if (asked !== undefined)
+            keepUntil(runtime, asked);
         return new this(runtime, client, opts.requestTimeoutMs);
     }
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
@@ -261,6 +356,7 @@ export class Sandbox {
     /** Stops the sandbox. False when it was not found or had already ended. */
     static async kill(sandboxId, opts = {}) {
         const client = clientFor(opts);
+        stopKeeping(sandboxId);
         try {
             const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
             return await stop(runtime, opts);
@@ -272,6 +368,7 @@ export class Sandbox {
         }
     }
     async kill(opts = {}) {
+        stopKeeping(this.sandboxId);
         try {
             return await stop(this.#runtime, opts);
         }
@@ -281,8 +378,10 @@ export class Sandbox {
             throw error;
         }
     }
-    /** 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. A sandbox
+     * created with no timeout has no end to move, and nothing changes. */
     static async setTimeout(sandboxId, timeoutMs, opts = {}) {
         const client = clientFor(opts);
         const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
@@ -330,6 +429,7 @@ export class Sandbox {
     /** Copies of this sandbox, memory and all. While Runtime's forks are
      * switched off this throws NotSupportedError with Runtime's own words. */
     static async fork(sandboxId, opts = {}) {
+        checkForkCount(opts.count);
         const { count: _count, timeoutMs: _timeoutMs, ...connection } = opts;
         const source = await this.connect(sandboxId, connection);
         return source.fork(opts);
@@ -339,6 +439,7 @@ export class Sandbox {
             // A fork's lease is Runtime's to set; one shorter than asked could not be
             // honoured after the forks exist, so this is refused before any are made.
             throw new NotSupportedError("A timeout for forks (fork timeoutMs)", "Fork without it, then call setTimeout(ms) on each fork.");
+        checkForkCount(opts.count);
         const copies = await guard("sandbox", () => this.#runtime.fork({ count: opts.count ?? 1, ...request(opts) }));
         // Copies keep the source's environment on Runtime's side.
         const Kind = this.constructor;
@@ -378,6 +479,10 @@ export class Sandbox {
     getHost(port) {
         if (!Number.isInteger(port) || port < 1 || port > 65_535)
             throw new InvalidArgumentError(`port must be a whole number from 1 to 65535, not ${port}.`);
+        // A trial sandbox's ports are private: a host alone would answer 404 or
+        // 401 to everyone. Say so now, with the address that works.
+        if (this.#runtime.info.funding === "trial")
+            throw new PublicPreviewNotAllowedError(this.sandboxId, port);
         void this.#share(port).catch((error) => {
             if (typeof process !== "undefined" && process.emitWarning)
                 process.emitWarning(`Sharing port ${port} for getHost failed: ${error instanceof Error ? error.message : String(error)}. getPublicHost(${port}) says why.`, { code: "RUNTIME_E2B_GET_HOST" });
@@ -388,6 +493,8 @@ export 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. */
     async getPublicHost(port) {
+        if (this.#runtime.info.funding === "trial")
+            throw new PublicPreviewNotAllowedError(this.sandboxId, port);
         return this.#share(port);
     }
     #share(port) {
@@ -439,18 +546,24 @@ async function resume(runtime, opts) {
     const current = state(runtime);
     if (current === "stopped")
         throw new SandboxNotFoundError(`Sandbox ${runtime.id} has ended.`);
+    const asked = opts.timeoutMs === undefined ? undefined : Date.now() + opts.timeoutMs;
     if (current === "paused") {
         await guard("sandbox", () => runtime.wake({
             ...(opts.timeoutMs === undefined ? {} : { timeoutSeconds: leaseSeconds(opts.timeoutMs) }),
             ...request(opts),
         }));
-        return;
     }
-    if (opts.timeoutMs !== undefined) {
-        const later = Date.now() + opts.timeoutMs - Date.parse(runtime.info.expiresAt);
+    else if (opts.timeoutMs !== undefined) {
+        checkTimeout(opts.timeoutMs);
+        // No time limit: no end to move (0300).
+        if (runtime.info.endsAt === null)
+            return;
+        const later = Math.min(asked, Date.now() + KEEP_AHEAD_MS) - Date.parse(runtime.info.expiresAt);
         if (later > 1000)
             await guard("sandbox", () => runtime.extend(Math.ceil(later / 1000), request(opts)));
     }
+    if (asked !== undefined && asked > (keepers.get(runtime.id)?.until ?? 0))
+        keepUntil(runtime, asked);
 }
 async function stop(runtime, opts) {
     if (state(runtime) === "stopped")
@@ -459,13 +572,18 @@ async function stop(runtime, opts) {
     return true;
 }
 async function extendTo(runtime, timeoutMs, opts) {
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
-        throw new InvalidArgumentError(`timeoutMs must be a positive number, not ${timeoutMs}.`);
-    const later = Date.now() + timeoutMs - Date.parse(runtime.info.expiresAt);
-    if (later < -1000)
-        throw new NotSupportedError("Shortening a sandbox's timeout", "Runtime leases only move later. Call kill() when the work is done.");
+    checkTimeout(timeoutMs);
+    // No time limit: no end to move (0300).
+    if (runtime.info.endsAt === null)
+        return;
+    const asked = Date.now() + timeoutMs;
+    const end = Date.parse(runtime.info.endsAt ?? runtime.info.expiresAt);
+    if (asked - end < -1000)
+        throw new NotSupportedError("Ending a sandbox sooner than its lease (a shorter setTimeout)", "Runtime cannot end a lease early. Call kill() when the work is done.");
+    const later = Math.min(asked, Date.now() + KEEP_AHEAD_MS) - end;
     if (later > 1000)
         await guard("sandbox", () => runtime.extend(Math.ceil(later / 1000), request(opts)));
+    keepUntil(runtime, asked);
 }
 async function pause(runtime, opts) {
     if (opts.keepMemory === false)
@@ -480,51 +598,109 @@ async function pause(runtime, opts) {
 }
 const RUNNING = ["starting", "running", "resuming"];
 const PAUSED = ["pausing", "paused"];
-/** 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 class SandboxPaginator {
     #client;
     #request;
     #filter;
+    #opts;
+    #pageSize;
+    #local;
     #page;
+    #all;
+    #offset;
     #hasNext = true;
     constructor(client, opts) {
         this.#client = client;
         this.#request = request(opts);
+        this.#opts = 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.");
-        if (query.startedAfter !== undefined)
-            throw new NotSupportedError("Listing by start time (startedAfter)", "List them all and filter on getInfo().startedAt.");
-        if (opts.order === "desc")
-            throw new NotSupportedError("Newest-first listing (order: 'desc')", "Runtime lists oldest first; reverse the list yourself.");
-        if (opts.nextToken !== undefined)
-            throw new NotSupportedError("Starting a list from a saved nextToken", "Keep the paginator and call nextItems() again.");
+        if (opts.limit !== undefined && (!Number.isSafeInteger(opts.limit) || opts.limit < 1))
+            throw new InvalidArgumentError(`limit must be a positive whole number, not ${opts.limit}.`);
+        this.#pageSize = opts.limit ?? 100;
+        this.#offset = opts.nextToken === undefined ? 0 : tokenOffset(opts.nextToken);
+        this.#local =
+            query.template !== undefined ||
+                query.startedAfter !== undefined ||
+                opts.order === "desc" ||
+                opts.nextToken !== undefined;
         const states = query.state?.length ? query.state : ["running", "paused"];
         this.#filter = {
             state: states.flatMap((one) => (one === "running" ? [...RUNNING] : [...PAUSED])),
             ...(query.metadata && Object.keys(query.metadata).length ? { labels: query.metadata } : {}),
-            ...(opts.limit ? { limit: Math.min(opts.limit, 100) } : {}),
+            limit: this.#local ? 100 : Math.min(this.#pageSize, 100),
         };
     }
     get hasNext() {
         return this.#hasNext;
     }
+    /** Where the next page starts; `Sandbox.list({ nextToken })` resumes there. */
     get nextToken() {
-        return this.#page?.nextCursor ?? undefined;
+        return this.#hasNext && this.#offset > 0 ? `runtime:${this.#offset}` : undefined;
     }
     async nextItems() {
         this.#request.signal?.throwIfAborted();
         if (!this.#hasNext)
             throw new SandboxError("No more items to fetch.");
+        if (this.#local) {
+            const all = (this.#all ??= await guard("other", () => this.#everyMatch()));
+            const items = all.slice(this.#offset, this.#offset + this.#pageSize);
+            this.#offset += items.length;
+            this.#hasNext = this.#offset < all.length;
+            return items;
+        }
         const previous = this.#page;
         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);
+        const items = (page?.data ?? []).map(infoOf);
+        this.#offset += items.length;
+        return items;
+    }
+    async #everyMatch() {
+        const query = this.#opts.query ?? {};
+        const templates = query.template === undefined
+            ? undefined
+            : await templateIds(this.#client, query.template, this.#request);
+        const after = query.startedAfter?.getTime();
+        const all = [];
+        let page = await this.#client.sandboxes.list(this.#filter, this.#request);
+        while (page) {
+            for (const one of page.data) {
+                const info = infoOf(one);
+                if (templates && !templates.has(info.templateId))
+                    continue;
+                if (after !== undefined && info.startedAt.getTime() < after)
+                    continue;
+                all.push(info);
+            }
+            page = page.hasMore ? await page.next() : null;
+        }
+        const sign = this.#opts.order === "desc" ? -1 : 1;
+        return all.sort((a, b) => sign * (a.startedAt.getTime() - b.startedAt.getTime()));
     }
 }
+function tokenOffset(token) {
+    const match = /^runtime:(\d+)$/.exec(token);
+    if (!match)
+        throw new InvalidArgumentError(`"${token}" is not a nextToken this package gave; pass the paginator's own nextToken.`);
+    return Number(match[1]);
+}
+/** The template ids a template name stands for: "base" for the stock names,
+ * the id itself for a UUID, and every Runtime image of that name. */
+async function templateIds(client, template, options) {
+    if (STOCK_TEMPLATES.has(template))
+        return new Set(["base"]);
+    if (UUID.test(template))
+        return new Set([template]);
+    const page = await client.images.list({ name: template, limit: 100 }, options);
+    return new Set(page.data.map((image) => image.id));
+}
 async function e2bMetrics(runtime, opts) {
     const start = opts.start === undefined ? Date.now() - 15 * 60_000 : new Date(opts.start).getTime();
     const end = opts.end === undefined ? Date.now() : new Date(opts.end).getTime();

package/dist/e2b/users.d.ts

@@ -0,0 +1,30 @@
+import type { FileEntry } from "../types.js";
+import type { RequestOptions } from "../transport.js";
+import type { SandboxContext, Username } from "./commands.js";
+/** The Linux user a call runs as, or undefined for the sandbox's own. Refuses
+ * a user the sandbox does not have, once per user and sandbox. */
+export declare function runAs(ctx: SandboxContext, user: Username | undefined, options: RequestOptions): Promise<string | undefined>;
+/** `bash -c script` as `user`, keeping the environment Runtime gives the
+ * command. Without a `cwd` it starts in the user's home, as E2B's does. */
+export declare function commandAs(user: string, script: string, cwdGiven: boolean): string[];
+/** An interactive login shell as `user`, for a PTY. */
+export declare function shellAs(user: string, cwdGiven: boolean): string[];
+/** E2B's file calls as another Linux user: each one a short script run with
+ * `sudo -u`, since Runtime's file API acts as the sandbox's own user. Output
+ * streams, so a read of any size comes back whole. */
+export declare class FilesAs {
+    #private;
+    private readonly ctx;
+    private readonly user;
+    private readonly options;
+    constructor(ctx: SandboxContext, user: string, options: RequestOptions);
+    read(path: string): Promise<Uint8Array>;
+    write(path: string, bytes: Uint8Array): Promise<void>;
+    list(path: string, depth: number): Promise<FileEntry[]>;
+    stat(path: string): Promise<FileEntry>;
+    exists(path: string): Promise<boolean>;
+    /** False when it was there already. */
+    makeDir(path: string): Promise<boolean>;
+    rename(from: string, to: string): Promise<void>;
+    remove(path: string): Promise<void>;
+}

package/dist/e2b/users.js

@@ -0,0 +1,185 @@
+import { FileNotFoundError, guard, InvalidArgumentError, SandboxError } from "./errors.js";
+/* E2B's `user` option, on Runtime. A sandbox's own user is `runtime`, with
+   passwordless sudo; E2B's default user is called "user". So "user" (or no
+   user) runs as the sandbox's own user, and any other name runs through
+   `sudo -u <name>`. The user must already exist: the adapter never makes one,
+   and a name the sandbox does not know is refused before anything runs. */
+const NAME = /^[a-z_][a-z0-9_.-]{0,31}$/i;
+/** Exit codes the scripts below use to say what went wrong. */
+const MISSING = 44;
+const NOT_DIRECTORY = 45;
+const IS_DIRECTORY = 46;
+const EXISTS = 47;
+/** Base64 text per exec: under the 1 MiB an exec's input may carry. */
+const WRITE_CHUNK = 786_432;
+/** Only the caller's signal: an exec's own `timeoutMs` is the command's. */
+const signalOf = (options) => (options.signal ? { signal: options.signal } : {});
+const checked = new WeakMap();
+/** The Linux user a call runs as, or undefined for the sandbox's own. Refuses
+ * a user the sandbox does not have, once per user and sandbox. */
+export async function runAs(ctx, user, options) {
+    if (user === undefined || user === "user")
+        return undefined;
+    if (typeof user !== "string" || !NAME.test(user))
+        throw new InvalidArgumentError(`"${String(user)}" is not a Linux user name.`);
+    if (user === "root")
+        return user;
+    let users = checked.get(ctx);
+    if (!users)
+        checked.set(ctx, (users = new Map()));
+    let check = users.get(user);
+    if (!check) {
+        check = (async () => {
+            const found = await guard("sandbox", () => ctx.runtime.exec(["id", "-u", "--", user], signalOf(options)));
+            if (found.exitCode !== 0)
+                throw new InvalidArgumentError(`This sandbox has no user "${user}", and Runtime never creates one for you. ` +
+                    `Make it first, as root: sandbox.commands.run("useradd -m ${user}", { user: "root" }). ` +
+                    `"user" is the sandbox's own user and "root" is root.`);
+        })();
+        users.set(user, check);
+        check.catch(() => users.delete(user));
+    }
+    await check;
+    return user;
+}
+/** `bash -c script` as `user`, keeping the environment Runtime gives the
+ * command. Without a `cwd` it starts in the user's home, as E2B's does. */
+export function commandAs(user, script, cwdGiven) {
+    return [
+        "sudo",
+        "-n",
+        "-E",
+        "-H",
+        "-u",
+        user,
+        "--",
+        "/bin/bash",
+        "-c",
+        cwdGiven ? script : `cd ~ 2>/dev/null\n${script}`,
+    ];
+}
+/** An interactive login shell as `user`, for a PTY. */
+export function shellAs(user, cwdGiven) {
+    return commandAs(user, "exec /bin/bash -i -l", cwdGiven);
+}
+/** One `sh -c` script as `user`, with its arguments passed apart, never
+ * pasted into the script. */
+function script(user, text, ...args) {
+    return ["sudo", "-n", "-u", user, "--", "/bin/sh", "-c", text, "sh", ...args];
+}
+/** Each entry `find -printf` prints: eight fields, each ended by NUL. */
+const FIELDS = "%y\\0%s\\0%m\\0%u\\0%g\\0%T@\\0%p\\0%l\\0";
+const TYPES = { f: "file", d: "directory", l: "symlink" };
+function entries(output) {
+    const fields = output.split("\0");
+    const out = [];
+    for (let i = 0; i + 8 <= fields.length; i += 8) {
+        const [kind, size, mode, owner, group, mtime, path, link] = fields.slice(i, i + 8);
+        out.push({
+            name: path.split("/").filter(Boolean).pop() ?? path,
+            path,
+            type: TYPES[kind] ?? "other",
+            size: Number(size) || 0,
+            mode: `0${mode}`,
+            modifiedAt: new Date(Math.round(Number(mtime) * 1000)).toISOString(),
+            owner,
+            group,
+            ...(kind === "l" && link ? { symlinkTarget: link } : {}),
+        });
+    }
+    return out;
+}
+/** E2B's file calls as another Linux user: each one a short script run with
+ * `sudo -u`, since Runtime's file API acts as the sandbox's own user. Output
+ * streams, so a read of any size comes back whole. */
+export class FilesAs {
+    ctx;
+    user;
+    options;
+    constructor(ctx, user, options) {
+        this.ctx = ctx;
+        this.user = user;
+        this.options = options;
+    }
+    async #run(argv, stdin) {
+        const result = await guard("sandbox", () => this.ctx.runtime.exec(argv, {
+            ...(stdin === undefined ? {} : { stdin }),
+            // A callback makes the exec stream, so its output is never cut.
+            onStdout: () => undefined,
+            ...signalOf(this.options),
+        }));
+        if (result.stdoutTruncated)
+            throw new SandboxError("Part of the answer was lost on the way; try again.");
+        return result;
+    }
+    #fail(path, result) {
+        if (result.exitCode === MISSING)
+            throw new FileNotFoundError(`${path} does not exist.`);
+        if (result.exitCode === NOT_DIRECTORY)
+            throw new InvalidArgumentError(`${path} is not a directory.`);
+        if (result.exitCode === IS_DIRECTORY)
+            throw new InvalidArgumentError(`${path} is a directory.`);
+        throw new SandboxError(`As the user "${this.user}": ${result.stderr.trim() || `exit status ${result.exitCode}`}`);
+    }
+    async read(path) {
+        const result = await this.#run(script(this.user, `[ -e "$1" ] || exit ${MISSING}; [ -d "$1" ] && exit ${IS_DIRECTORY}; exec base64 -w 0 -- "$1"`, path));
+        if (result.exitCode !== 0)
+            this.#fail(path, result);
+        return Uint8Array.from(atob(result.stdout.trim()), (c) => c.charCodeAt(0));
+    }
+    async write(path, bytes) {
+        let text = "";
+        for (let i = 0; i < bytes.length; i += 32_768)
+            text += String.fromCharCode(...bytes.subarray(i, i + 32_768));
+        const encoded = btoa(text);
+        let offset = 0;
+        do {
+            const chunk = encoded.slice(offset, offset + WRITE_CHUNK);
+            const result = await this.#run(script(this.user, offset === 0
+                ? `mkdir -p -- "$(dirname -- "$1")" && base64 -d > "$1"`
+                : `base64 -d >> "$1"`, path), chunk);
+            if (result.exitCode !== 0)
+                this.#fail(path, result);
+            offset += WRITE_CHUNK;
+        } while (offset < encoded.length);
+    }
+    async list(path, depth) {
+        const result = await this.#run(script(this.user, `[ -e "$1" ] || exit ${MISSING}; [ -d "$1" ] || exit ${NOT_DIRECTORY}; ` +
+            `exec find "$1" -mindepth 1 -maxdepth "$2" -printf '${FIELDS}'`, path, String(depth)));
+        if (result.exitCode !== 0)
+            this.#fail(path, result);
+        return entries(result.stdout);
+    }
+    async stat(path) {
+        const result = await this.#run(script(this.user, `[ -e "$1" ] || [ -L "$1" ] || exit ${MISSING}; exec find "$1" -maxdepth 0 -printf '${FIELDS}'`, path));
+        if (result.exitCode !== 0)
+            this.#fail(path, result);
+        const [entry] = entries(result.stdout);
+        if (!entry)
+            throw new FileNotFoundError(`${path} does not exist.`);
+        return entry;
+    }
+    async exists(path) {
+        const result = await this.#run(script(this.user, `[ -e "$1" ] || [ -L "$1" ]`, path));
+        return result.exitCode === 0;
+    }
+    /** False when it was there already. */
+    async makeDir(path) {
+        const result = await this.#run(script(this.user, `[ -d "$1" ] && exit ${EXISTS}; mkdir -p -- "$1"`, path));
+        if (result.exitCode === EXISTS)
+            return false;
+        if (result.exitCode !== 0)
+            this.#fail(path, result);
+        return true;
+    }
+    async rename(from, to) {
+        const result = await this.#run(script(this.user, `[ -e "$1" ] || [ -L "$1" ] || exit ${MISSING}; mv -fT -- "$1" "$2"`, from, to));
+        if (result.exitCode !== 0)
+            this.#fail(from, result);
+    }
+    async remove(path) {
+        const result = await this.#run(script(this.user, `rm -rf -- "$1"`, path));
+        if (result.exitCode !== 0)
+            this.#fail(path, result);
+    }
+}

package/dist/errors.d.ts

@@ -6,6 +6,12 @@
  * packages/cloud/src/api/respond.ts) and retrying cannot change them.
  * host_unavailable and busy pass, and are retried. */
 export declare const DELIBERATE: ReadonlySet<string>;
+/** Refusals that guarantee nothing ran: a sandbox running as many commands
+ * as it can (`guest_busy`), and the API's own limits, which answer before any
+ * work starts (`busy`, `rate_limited`). Sending such a call again is always
+ * safe, so the SDK does, with backoff, until the call's deadline (five
+ * minutes when it has none), however many retries it allows otherwise. */
+export declare const NOTHING_RAN: ReadonlySet<string>;
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
  * frees room: the trial's slots, an email domain's trial slots, the account's
  * quota and the region's capacity. `sandboxes.create` waits them out, retrying

package/dist/errors.js

@@ -16,6 +16,12 @@ export const DELIBERATE = new Set([
     "identity_unavailable",
     "env_unavailable",
 ]);
+/** Refusals that guarantee nothing ran: a sandbox running as many commands
+ * as it can (`guest_busy`), and the API's own limits, which answer before any
+ * work starts (`busy`, `rate_limited`). Sending such a call again is always
+ * safe, so the SDK does, with backoff, until the call's deadline (five
+ * minutes when it has none), however many retries it allows otherwise. */
+export const NOTHING_RAN = new Set(["guest_busy", "busy", "rate_limited"]);
 /** Refusals that pass on their own: a host frees room, a trial slot frees. */
 const PASSING = new Set(["no_capacity", "trial_busy"]);
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host

package/dist/identity.js

@@ -1,4 +1,5 @@
 import { RuntimeError } from "./errors.js";
+import { sandboxMarker } from "./transport.js";
 async function requestCredentials() {
     let url = process.env.RUNTIME_ID_TOKEN_REQUEST_URL;
     let token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
@@ -7,7 +8,7 @@ async function requestCredentials() {
         try {
             // Loaded here, so the SDK still loads where there is no file system.
             const { readFile } = await import("node:fs/promises");
-            const env = JSON.parse(await readFile("/run/runtime/environment.json", "utf8"));
+            const env = JSON.parse(await readFile(sandboxMarker.path, "utf8"));
             url = env.RUNTIME_ID_TOKEN_REQUEST_URL;
             token = env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
         }