withruntime 0.9.0 → 0.11.0

package/dist/e2b/pty.js

@@ -0,0 +1,83 @@
+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)
+            throw new InvalidArgumentError("PTY rows and columns must be positive whole numbers.");
+    return { cols: size.cols, rows: size.rows };
+}
+/** E2B's PTY methods over native terminal processes with lossless output. */
+export class Pty {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async create(opts) {
+        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();
+            const shell = user ? shellAs(user, opts.cwd !== undefined) : ["/bin/bash", "-i", "-l"];
+            return this.ctx.runtime.spawn(shell, {
+                pty,
+                stdin: "pipe",
+                outputEncoding: "base64",
+                env,
+                ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+                request: opening.request,
+            });
+        }).catch(opening.failure);
+        return new CommandHandle(process, {
+            stdin: false,
+            pty: true,
+            onData: opts.onData,
+            timeoutMs: opening.timeoutMs,
+            deadline: opening.deadline,
+            signal: opts.signal,
+            requestTimeoutMs: this.ctx.requestTimeoutMs,
+        });
+    }
+    async connect(pid, opts) {
+        const opening = connectionRequest(opts ?? {}, this.ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.ctx, pid, opening.request).catch(opening.failure);
+        if (!process.info.pty || process.info.outputEncoding !== "base64")
+            throw new NotSupportedError("Connecting to a legacy text-output PTY", "Create the PTY through sandbox.pty.create first.");
+        return new CommandHandle(process, {
+            stdin: false,
+            pty: true,
+            onData: opts?.onData,
+            timeoutMs: opening.timeoutMs,
+            deadline: opening.deadline,
+            cursor: process.info.outputBytes,
+            signal: opts?.signal,
+            requestTimeoutMs: this.ctx.requestTimeoutMs,
+        });
+    }
+    async sendInput(pid, data, opts = {}) {
+        const request = commandRequest(opts, this.ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.ctx, pid, request);
+        if (!process.info.pty)
+            throw new InvalidArgumentError(`The process with pid ${pid} is not a PTY.`);
+        request.signal?.throwIfAborted();
+        await guard("sandbox", () => process.write(data, request));
+    }
+    async resize(pid, size, opts = {}) {
+        const pty = dimensions(size);
+        const request = commandRequest(opts, this.ctx.requestTimeoutMs);
+        const process = await resolveProcess(this.ctx, pid, request);
+        if (!process.info.pty)
+            throw new InvalidArgumentError(`The process with pid ${pid} is not a PTY.`);
+        request.signal?.throwIfAborted();
+        await guard("sandbox", () => process.resize(pty.cols, pty.rows, request));
+    }
+    kill(pid, opts = {}) {
+        return killProcess(this.ctx, pid, commandRequest(opts, this.ctx.requestTimeoutMs));
+    }
+}

package/dist/e2b/sandbox.d.ts

@@ -2,6 +2,7 @@ import type { Runtime } from "../client.js";
 import { type ConnectionOpts, type RuntimeOpts, type RuntimeSandbox } from "./client.js";
 import { Commands } from "./commands.js";
 import { Filesystem } from "./filesystem.js";
+import { Pty } from "./pty.js";
 /** E2B's default machine: 2 vCPU and 512 MiB (docs.e2b.dev/billing, checked
  * 23 September 2026). Pass `runtime: { create: { memoryMiB } }` for another. */
 export declare const DEFAULT_SHAPE: {
@@ -29,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;
@@ -87,12 +89,17 @@ 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;
     protected static readonly defaultTemplate: string;
     readonly files: Filesystem;
     readonly commands: Commands;
+    readonly pty: Pty;
     /** Use Sandbox.create or Sandbox.connect. */
     constructor(runtime: RuntimeSandbox, client: Runtime, requestTimeoutMs?: number);
     get sandboxId(): string;
@@ -116,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>;
@@ -167,7 +175,6 @@ export declare class Sandbox {
      * its host, `<port>-<id>.<domain>`, once the share has landed. Anyone with
      * the address can reach it; a browser sees a one-time page naming Runtime. */
     getPublicHost(port: number): Promise<string>;
-    get pty(): never;
     get git(): never;
     /** E2B's metrics, from Runtime's measured readings (`sbx.metrics()`): CPU
      * as a percent of the sandbox's vCPUs and resident memory, one entry per
@@ -182,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[]>;
 }

package/dist/e2b/sandbox.js

@@ -1,7 +1,8 @@
 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
    withruntime SDK; nothing here speaks HTTP. What Runtime cannot do the same
    way throws NotSupportedError before anything happens. */
@@ -13,16 +14,23 @@ 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;
@@ -32,6 +40,85 @@ 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") {
+            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";
@@ -65,12 +152,13 @@ function refuseCreate(opts) {
 }
 /** Where a template sends the create: the stock image, a Runtime image by
  * name or id, or a Runtime snapshot by id. */
-async function resolveTemplate(client, template) {
+async function resolveTemplate(client, template, options) {
+    options.signal?.throwIfAborted();
     if (STOCK_TEMPLATES.has(template))
         return {};
     if (UUID.test(template)) {
         try {
-            await client.images.get(template);
+            await client.images.get(template, options);
             return { image: template };
         }
         catch (error) {
@@ -79,7 +167,7 @@ async function resolveTemplate(client, template) {
         }
         return { snapshot: template };
     }
-    const page = await client.images.list({ name: template, state: "ready", limit: 1 });
+    const page = await client.images.list({ name: template, state: "ready", limit: 1 }, options);
     const image = page.data[0];
     if (image)
         return { image: image.id };
@@ -135,6 +223,7 @@ export class Sandbox {
     static defaultTemplate = "base";
     files;
     commands;
+    pty;
     #client;
     #runtime;
     #home;
@@ -146,12 +235,14 @@ export class Sandbox {
         this.#runtime = runtime;
         this.#client = client;
         const ctx = {
-            ensureHome: (text) => this.#ensureHome(text),
+            ensureHome: (text, options) => this.#ensureHome(text, options),
+            requestTimeoutMs: this.requestTimeoutMs,
         };
         // A getter, so the modules see the sandbox as it is after each refresh.
         Object.defineProperty(ctx, "runtime", { get: () => this.#runtime });
         this.files = new Filesystem(ctx);
         this.commands = new Commands(ctx);
+        this.pty = new Pty(ctx);
     }
     get sandboxId() {
         return this.#runtime.id;
@@ -167,23 +258,50 @@ export class Sandbox {
     /** E2B's home is /home/user and Runtime's is /workspace. The first time a
      * path or command names /home/user, it is made a link to /workspace (unless
      * something is already there), so paths written for E2B work. */
-    #ensureHome(text) {
+    #ensureHome(text, options = {}) {
+        const signal = options.signal;
+        signal?.throwIfAborted();
+        const wait = (pending) => {
+            if (!signal)
+                return pending;
+            return new Promise((resolve, reject) => {
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- rejects with the caller's abort reason as is, as the upstream SDK does
+                const abort = () => reject(signal.reason);
+                signal.addEventListener("abort", abort, { once: true });
+                pending.then(() => {
+                    signal.removeEventListener("abort", abort);
+                    resolve();
+                }, (error) => {
+                    signal.removeEventListener("abort", abort);
+                    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- passes the pending call's own failure through unchanged
+                    reject(error);
+                });
+            });
+        };
         if (this.#home || !text?.includes("/home/user"))
-            return this.#home ?? Promise.resolve();
-        this.#home = (async () => {
-            const result = await guard("sandbox", () => this.#runtime.exec("[ -e /home/user ] || sudo ln -s /workspace /home/user"));
+            return wait(this.#home ?? Promise.resolve());
+        const pending = (async () => {
+            const result = await guard("sandbox", () => this.#runtime.exec("[ -e /home/user ] || sudo ln -s /workspace /home/user", { signal }));
             if (result.exitCode !== 0 && typeof process !== "undefined")
                 process.emitWarning(`Could not link /home/user to /workspace: ${result.stderr.trim()}`, {
                     code: "RUNTIME_E2B_HOME",
                 });
         })();
-        return this.#home;
+        this.#home = pending;
+        pending.catch(() => {
+            if (this.#home === pending)
+                this.#home = undefined;
+        });
+        return wait(pending);
     }
     static async create(templateOrOpts, maybeOpts) {
         const opts = (typeof templateOrOpts === "string" ? maybeOpts : templateOrOpts) ?? {};
         const template = (typeof templateOrOpts === "string" ? templateOrOpts : opts.template) ?? this.defaultTemplate;
+        const options = request(opts);
+        options.signal?.throwIfAborted();
         refuseCreate(opts);
         const client = clientFor(opts);
+        const asked = Date.now() + (opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
         const input = {
             timeoutSeconds: leaseSeconds(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
             onLeaseEnd: onLeaseEnd(opts.lifecycle),
@@ -196,7 +314,8 @@ export class Sandbox {
             ...(opts.envs && Object.keys(opts.envs).length ? { env: opts.envs } : {}),
             ...(opts.allowInternetAccess === false ? { network: { internet: false } } : {}),
         };
-        const source = await guard("other", () => resolveTemplate(client, template));
+        const source = await guard("other", () => resolveTemplate(client, template, options));
+        options.signal?.throwIfAborted();
         const create = {
             // A snapshot carries its own machine; everything else gets E2B's shape.
             ...(source.snapshot ? {} : DEFAULT_SHAPE),
@@ -204,7 +323,8 @@ export class Sandbox {
             ...source,
             ...opts.runtime?.create,
         };
-        const runtime = await guard("sandbox", () => client.sandboxes.create(create, request(opts)));
+        const runtime = await guard("sandbox", () => client.sandboxes.create(create, options));
+        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
@@ -229,6 +349,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);
@@ -240,6 +361,7 @@ export class Sandbox {
         }
     }
     async kill(opts = {}) {
+        stopKeeping(this.sandboxId);
         try {
             return await stop(this.#runtime, opts);
         }
@@ -249,8 +371,9 @@ 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. */
     static async setTimeout(sandboxId, timeoutMs, opts = {}) {
         const client = clientFor(opts);
         const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
@@ -298,6 +421,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);
@@ -307,6 +431,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;
@@ -346,6 +471,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" });
@@ -356,6 +485,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) {
@@ -369,9 +500,6 @@ export class Sandbox {
         return share;
     }
     // ---- what Runtime does differently -----------------------------------
-    get pty() {
-        throw new NotSupportedError("E2B's pty module", "Use `await sandbox.runtime.terminal({ cols, rows, onData })` for an interactive terminal, or runtime.spawn(cmd, { pty: {} }).");
-    }
     get git() {
         throw new NotSupportedError("E2B's git module (deprecated by E2B too)", "Run git with sandbox.commands.run('git ...'); git is installed.");
     }
@@ -410,18 +538,21 @@ 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);
+        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")
@@ -430,13 +561,15 @@ 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);
+    const asked = Date.now() + timeoutMs;
+    const end = Date.parse(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)
@@ -451,46 +584,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));
+        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();