withruntime 0.11.1 → 0.12.0

package/dist/e2b/sandbox.js

@@ -1,4 +1,4 @@
-import { clientFor, request, } from "./client.js";
+import { clientFor, keySource, request, } from "./client.js";
 import { Commands } from "./commands.js";
 import { guard, InvalidArgumentError, NotSupportedError, PublicPreviewNotAllowedError, SandboxError, SandboxNotFoundError, TemplateError, } from "./errors.js";
 import { Filesystem } from "./filesystem.js";
@@ -9,18 +9,26 @@ 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. 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. */
+/** E2B's default sandbox timeout, 300 s. A sandbox created without timeoutMs
+ * gets it, and is paused when it runs out rather than killed, since nobody
+ * asked for it to end: nothing in it is lost, and the next call wakes it. On
+ * a pilot account the server keeps every sandbox running instead (0254). */
 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). */
+/** Runtime's time limit bounds (MIN_TIMEOUT_SECONDS and MAX_TIMEOUT_SECONDS
+ * in the API): a minute to 24 hours, E2B's longest (its Pro plan). The server
+ * keeps the deadline: nothing in this process has to stay running for it. */
+const MIN_TIMEOUT_SECONDS = 60;
 const LONGEST_TIMEOUT_MS = 86_400_000;
+/** Makes E2B's home lead to Runtime's unless the image has its own, and
+ * prints "same" when /home/user is then /workspace. */
+const HOME_LINK = "[ -e /home/user ] || sudo ln -s /workspace /home/user || exit 1; if [ /home/user -ef /workspace ]; then echo same; fi";
+/** The label that keeps the template a sandbox was made from, so getInfo
+ * and list name it whichever client asks; it is not shown in `metadata`. */
+export const TEMPLATE_LABEL = "e2b-template";
 /** 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;
+const SNAPSHOT_MODES = ["full", "filesystem"];
 let warnedShortLease = false;
 /** E2B's own bound since 2.52.0: refused before anything happens. */
 const MAX_FORK_COUNT = 20;
@@ -28,17 +36,17 @@ 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) {
+/** Runtime's time limit for `timeoutMs`, in whole seconds: at least a
+ * minute (with a warning once), at most 24 hours. */
+function timeoutSeconds(timeoutMs) {
     checkTimeout(timeoutMs);
-    const seconds = Math.min(Math.ceil(timeoutMs / 1000), MAX_LEASE_SECONDS);
-    if (seconds < MIN_LEASE_SECONDS) {
+    const seconds = Math.ceil(timeoutMs / 1000);
+    if (seconds < MIN_TIMEOUT_SECONDS) {
         if (!warnedShortLease && typeof process !== "undefined") {
             warnedShortLease = true;
-            process.emitWarning(`timeoutMs ${timeoutMs} is under Runtime's shortest lease; the sandbox gets 60 s. Call kill() when done.`, { code: "RUNTIME_E2B_SHORT_TIMEOUT" });
+            process.emitWarning(`timeoutMs ${timeoutMs} is under Runtime's shortest time limit; the sandbox gets 60 s. Call kill() when done.`, { code: "RUNTIME_E2B_SHORT_TIMEOUT" });
         }
-        return MIN_LEASE_SECONDS;
+        return MIN_TIMEOUT_SECONDS;
     }
     return seconds;
 }
@@ -48,89 +56,37 @@ function checkTimeout(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) {
+/** What the server does when the time limit runs out. E2B kills: a caller
+ * that asked for an end (a timeoutMs, or onTimeout "kill") gets a delete, as
+ * E2B's kill destroys the sandbox. One that asked for nothing gets E2B's
+ * 300 s default as a pause, which keeps everything, since a sandbox nobody
+ * asked to end is never ended. */
+function onTimeout(lifecycle, timeoutAsked) {
     if (!lifecycle)
-        return "stop";
+        return timeoutAsked ? "delete" : "pause";
     const action = typeof lifecycle.onTimeout === "string" ? lifecycle.onTimeout : lifecycle.onTimeout.action;
-    if (typeof lifecycle.onTimeout === "object" && lifecycle.onTimeout.keepMemory === false)
-        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
-    return action === "pause" ? "pause" : "stop";
+    // As E2B 2.55 checks: mode (or keepMemory) belongs to a pause alone.
+    const pauseOpts = (typeof lifecycle.onTimeout === "string" ? {} : lifecycle.onTimeout);
+    if (("mode" in pauseOpts || "keepMemory" in pauseOpts) && action !== "pause")
+        throw new InvalidArgumentError("onTimeout.mode is only allowed when action is 'pause'.");
+    if (snapshotMemory("onTimeout.mode", pauseOpts.mode, pauseOpts.keepMemory) === false)
+        throw filesOnlyPause();
+    return action === "pause" ? "pause" : "delete";
+}
+/** E2B 2.55's reading of `mode`, or the deprecated `keepMemory`: whether
+ * memory is kept, or undefined when neither was given. Both at once, or a
+ * mode E2B does not know, is E2B's InvalidArgumentError. */
+function snapshotMemory(field, mode, keepMemory) {
+    if (mode != null && keepMemory != null)
+        throw new InvalidArgumentError(`Pass either ${field} or the deprecated keepMemory, not both.`);
+    if (mode == null)
+        return keepMemory ?? undefined;
+    if (!SNAPSHOT_MODES.includes(mode))
+        throw new InvalidArgumentError(`${field} must be one of: ${SNAPSHOT_MODES.join(", ")} (got ${JSON.stringify(mode)}).`);
+    return mode === "full";
 }
+const filesOnlyPause = () => new NotSupportedError("A files-only pause (mode: 'filesystem', or keepMemory: false)", "Runtime's pause keeps memory and files; leave mode out or pass mode: 'full'. " +
+    "For a copy of the files alone, use createSnapshot({ mode: 'filesystem' }).");
 function refuseCreate(opts) {
     const refusals = [
         [
@@ -154,8 +110,16 @@ function refuseCreate(opts) {
         if (opts[field] !== undefined)
             throw new NotSupportedError(feature, alternative);
 }
+/** The Runtime image name an E2B template name stands for: E2B's
+ * `team/name:tag` without the team, since a Runtime account's images are its
+ * own. `name`, `name:tag` and `name@version` are Runtime image names too. */
+export function imageNameFor(template) {
+    const slash = template.lastIndexOf("/");
+    return slash < 0 ? template : template.slice(slash + 1);
+}
 /** Where a template sends the create: the stock image, a Runtime image by
- * name or id, or a Runtime snapshot by id. */
+ * name (with its tag or version) or id, or a Runtime snapshot by id. A name
+ * is resolved by the create itself, in the same request. */
 async function resolveTemplate(client, template, options) {
     options.signal?.throwIfAborted();
     if (STOCK_TEMPLATES.has(template))
@@ -171,16 +135,36 @@ async function resolveTemplate(client, template, options) {
         }
         return { snapshot: template };
     }
-    const page = await client.images.list({ name: template, state: "ready", limit: 1 }, options);
-    const image = page.data[0];
-    if (image)
-        return { image: image.id };
-    const error = new TemplateError(`No Runtime image is named "${template}". E2B templates do not run on Runtime; build the same ` +
+    return { image: imageNameFor(template) };
+}
+/** The labels a create sends: E2B's metadata, and the template it was made
+ * from, while there is room for it among Runtime's 32 labels. */
+function labelsFor(metadata, template) {
+    const labels = { ...metadata };
+    if (!STOCK_TEMPLATES.has(template) && Object.keys(labels).length < 32 && template.length <= 256)
+        labels[TEMPLATE_LABEL] = template;
+    return Object.keys(labels).length ? { labels } : {};
+}
+/** " in the account …", for an error a key of another account explains: the
+ * account's name and where its key came from. Nothing when the lookup fails. */
+async function accountOf(client, opts) {
+    const me = await client.me({ timeoutMs: 5_000 }).catch(() => undefined);
+    if (!me)
+        return undefined;
+    const source = opts.runtime?.client ? "" : ` (key: ${keySource(opts.apiKey)})`;
+    return ` in the account "${me.orgName || me.orgId}"${source}`;
+}
+/** The create's refusal of a template no Runtime image answers to, as E2B's
+ * TemplateError, saying how to build it. */
+function templateMissing(template, cause, account) {
+    const name = imageNameFor(template).replace(/[:@].*$/, "");
+    const error = new TemplateError(`No Runtime image is named "${imageNameFor(template)}"${account ?? ""}. E2B templates do not run on Runtime; build the same ` +
         `environment as a Runtime image with that name and this call starts from it: ` +
-        `\`npx withruntime image build --dockerfile e2b.Dockerfile --name ${template}\`, or ` +
-        `runtime.images.build({ name: "${template}", dockerfile }).`);
+        `\`npx withruntime images build --dockerfile e2b.Dockerfile --name ${name}\`, or ` +
+        `runtime.images.build({ name: "${name}", dockerfile }).`);
     error.code = "template_not_found";
-    throw error;
+    error.cause = cause;
+    return error;
 }
 function state(runtime) {
     const current = runtime.state;
@@ -190,28 +174,57 @@ function state(runtime) {
         return "stopped";
     return "running";
 }
-function infoOf(runtime) {
+/** Whether a paused sandbox is, to code written for E2B, still running:
+ * Runtime paused it itself for being idle (E2B never does) and the next
+ * call wakes it, so every E2B call on it works as on a running one. */
+function idleAsleep(runtime) {
     const info = runtime.info;
-    const templateId = typeof info.image === "string"
-        ? info.image
-        : typeof info.snapshot === "string"
-            ? info.snapshot
-            : "base";
+    return state(runtime) === "paused" && info.stopReason === "idle" && info.autoWake !== false;
+}
+/** The sandbox's state as E2B would say it. */
+function e2bState(runtime) {
     const current = state(runtime);
+    if (current === "running" || idleAsleep(runtime))
+        return "running";
+    return "paused";
+}
+/** E2B's endAt: when the sandbox ends by itself. One that never will (no
+ * time limit, as a persistent or a pilot's sandbox) reads 24 hours ahead, the
+ * furthest an E2B sandbox's end may be, so code that waits until the end, or
+ * extends near it, behaves as for the longest E2B sandbox: a JavaScript timer
+ * set past 24.8 days would fire at once. (5 October 2026: it read where the
+ * sandbox was paid up to, minutes ahead, so a pilot's looked about to end.) */
+function endOf(runtime) {
+    const { endsAt, expiresAt } = runtime.info;
+    if (endsAt)
+        return new Date(endsAt);
+    if (endsAt === null && e2bState(runtime) === "running")
+        return new Date(Date.now() + LONGEST_TIMEOUT_MS);
+    return new Date(expiresAt);
+}
+function infoOf(runtime) {
+    const info = runtime.info;
+    const { [TEMPLATE_LABEL]: template, ...metadata } = info.labels ?? {};
+    const templateId = template ??
+        (typeof info.image === "string"
+            ? info.image
+            : typeof info.snapshot === "string"
+                ? info.snapshot
+                : "base");
+    const action = info.onTimeout ?? info.onLeaseEnd;
     return {
         sandboxId: info.id,
         templateId,
         ...(info.name ? { name: info.name } : {}),
-        metadata: info.labels ?? {},
+        metadata,
         startedAt: new Date(info.createdAt),
-        // 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,
+        endAt: endOf(runtime),
+        state: e2bState(runtime),
         cpuCount: info.vcpu,
         memoryMB: info.memoryMiB,
         envdVersion: "runtime",
         lifecycle: {
-            onTimeout: info.onLeaseEnd === "stop" ? "kill" : "pause",
+            onTimeout: action === "pause" ? "pause" : "kill",
             autoResume: info.autoWake === true,
         },
     };
@@ -231,6 +244,8 @@ export class Sandbox {
     pty;
     #client;
     #runtime;
+    #killed = false;
+    /** The /home/user link, once asked for: whether /home/user leads to /workspace. */
     #home;
     /** Ports shared as public previews, by port: the one share each asked for. */
     #shares = new Map();
@@ -241,6 +256,7 @@ export class Sandbox {
         this.#client = client;
         const ctx = {
             ensureHome: (text, options) => this.#ensureHome(text, options),
+            homeIsWorkspace: () => (this.#home ?? this.#linkHome()).catch(() => false),
             requestTimeoutMs: this.requestTimeoutMs,
         };
         // A getter, so the modules see the sandbox as it is after each refresh.
@@ -283,21 +299,32 @@ export class Sandbox {
                 });
             });
         };
+        const done = (home) => wait(home.then(() => undefined));
         if (this.#home || !text?.includes("/home/user"))
-            return wait(this.#home ?? Promise.resolve());
+            return done(this.#home ?? Promise.resolve(false));
+        return done(this.#linkHome(signal));
+    }
+    /** Links /home/user to /workspace unless something is already there, and
+     * says whether /home/user then leads to /workspace: an image may have its
+     * own /home/user, and E2B's paths are shown only where they are true. */
+    #linkHome(signal) {
         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",
-                });
+            const result = await guard("sandbox", () => this.#runtime.exec(HOME_LINK, { signal }));
+            if (result.exitCode !== 0) {
+                if (typeof process !== "undefined")
+                    process.emitWarning(`Could not link /home/user to /workspace: ${result.stderr.trim()}`, {
+                        code: "RUNTIME_E2B_HOME",
+                    });
+                return false;
+            }
+            return result.stdout.trim() === "same";
         })();
         this.#home = pending;
         pending.catch(() => {
             if (this.#home === pending)
                 this.#home = undefined;
         });
-        return wait(pending);
+        return pending;
     }
     static async create(templateOrOpts, maybeOpts) {
         const opts = (typeof templateOrOpts === "string" ? maybeOpts : templateOrOpts) ?? {};
@@ -306,15 +333,15 @@ 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;
+        // The server keeps the deadline, up to 24 hours (0381). Without one asked
+        // for, E2B's 300 s ends in a pause, never a delete.
         const input = {
-            ...(opts.timeoutMs === undefined ? {} : { timeoutSeconds: leaseSeconds(opts.timeoutMs) }),
-            onLeaseEnd: onLeaseEnd(opts.lifecycle),
+            timeoutSeconds: timeoutSeconds(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            onLeaseEnd: onTimeout(opts.lifecycle, opts.timeoutMs !== undefined),
             // With a lifecycle, E2B resumes a paused sandbox on traffic only when
             // asked (autoResume); Runtime's automatic wake is the same thing (0093).
             ...(opts.lifecycle ? { autoWake: opts.lifecycle.autoResume === true } : {}),
-            ...(opts.metadata && Object.keys(opts.metadata).length ? { labels: opts.metadata } : {}),
+            ...labelsFor(opts.metadata, template),
             // Runtime keeps them with the sandbox: every command, terminal and
             // interpreter in it gets them, from this client or any other.
             ...(opts.envs && Object.keys(opts.envs).length ? { env: opts.envs } : {}),
@@ -329,9 +356,11 @@ export class Sandbox {
             ...source,
             ...opts.runtime?.create,
         };
-        const runtime = await guard("sandbox", () => client.sandboxes.create(create, options));
-        if (asked !== undefined)
-            keepUntil(runtime, asked);
+        const runtime = await guard("sandbox", () => client.sandboxes.create(create, options)).catch(async (error) => {
+            if (error.code === "image_not_found")
+                throw templateMissing(template, error, await accountOf(client, opts));
+            throw error;
+        });
         return new this(runtime, client, opts.requestTimeoutMs);
     }
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
@@ -353,13 +382,17 @@ export class Sandbox {
         return new SandboxPaginator(clientFor(opts), opts);
     }
     // ---- lifecycle --------------------------------------------------------
-    /** Stops the sandbox. False when it was not found or had already ended. */
+    /** Deletes the sandbox for good, as E2B's kill destroys it: its disk,
+     * memory and shared ports go. False when it was not found or was already
+     * deleted. */
     static async kill(sandboxId, opts = {}) {
         const client = clientFor(opts);
-        stopKeeping(sandboxId);
         try {
+            // Read first: a delete answers the same however often it is sent, and
+            // E2B says false for one already gone.
             const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
-            return await stop(runtime, opts);
+            await guard("sandbox", () => runtime.delete(request(opts)));
+            return true;
         }
         catch (error) {
             if (error instanceof SandboxNotFoundError)
@@ -368,9 +401,12 @@ export class Sandbox {
         }
     }
     async kill(opts = {}) {
-        stopKeeping(this.sandboxId);
+        if (this.#killed)
+            return false;
         try {
-            return await stop(this.#runtime, opts);
+            await guard("sandbox", () => this.#runtime.delete(request(opts)));
+            this.#killed = true;
+            return true;
         }
         catch (error) {
             if (error instanceof SandboxNotFoundError)
@@ -378,10 +414,11 @@ export class Sandbox {
             throw error;
         }
     }
-    /** 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. */
+    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours, as E2B
+     * does; the server keeps the deadline. Runtime cannot bring an end
+     * sooner, so that is refused. A sandbox with no time limit (one on a pilot
+     * account, kept running by the server) 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)));
@@ -399,6 +436,9 @@ export class Sandbox {
         await guard("sandbox", () => this.#runtime.refresh(request(opts)));
         return infoOf(this.#runtime);
     }
+    /** Whether the sandbox answers calls, as E2B's health check says: true
+     * while it runs, and while Runtime has paused it for being idle, since the
+     * next call wakes it. False once paused on request, ended or deleted. */
     async isRunning(opts = {}) {
         try {
             await guard("sandbox", () => this.#runtime.refresh(request(opts)));
@@ -408,7 +448,7 @@ export class Sandbox {
                 return false;
             throw error;
         }
-        return this.#runtime.state === "running";
+        return this.#runtime.state === "running" || idleAsleep(this.#runtime);
     }
     /** Pauses the sandbox, keeping memory and files. False when it was paused. */
     static async pause(sandboxId, opts = {}) {
@@ -445,10 +485,17 @@ export class Sandbox {
         const Kind = this.constructor;
         return copies.map((copy) => new Kind(copy, this.#client));
     }
-    /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
-     * with Sandbox.create(snapshotId). */
+    /** Keeps the sandbox's whole machine as a Runtime snapshot, or with
+     * `mode: "filesystem"` its disk alone, from which a sandbox boots afresh;
+     * start from it with Sandbox.create(snapshotId). */
     async createSnapshot(opts = {}) {
-        const snapshot = await guard("sandbox", () => this.#runtime.snapshot({ ...(opts.name ? { name: opts.name } : {}), ...request(opts) }));
+        const memory = snapshotMemory("mode", opts.mode);
+        const mode = memory === undefined ? undefined : memory ? "memory" : "disk";
+        const snapshot = await guard("sandbox", () => this.#runtime.snapshot({
+            ...(opts.name ? { name: opts.name } : {}),
+            ...(mode ? { mode } : {}),
+            ...request(opts),
+        }));
         return { snapshotId: snapshot.id, names: snapshot.name ? [snapshot.name] : [] };
     }
     static async createSnapshot(sandboxId, opts = {}) {
@@ -479,7 +526,7 @@ 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
+        // A sandbox without credit shares ports privately: 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);
@@ -546,48 +593,42 @@ 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) }),
+            ...(opts.timeoutMs === undefined ? {} : { timeoutSeconds: timeoutSeconds(opts.timeoutMs) }),
             ...request(opts),
         }));
     }
     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);
+        // A running one's end moves later, never sooner, as E2B's connect.
+        const later = secondsLater(runtime, opts.timeoutMs);
+        if (later > 1)
+            await guard("sandbox", () => runtime.extend(Math.ceil(later), request(opts)));
+    }
 }
-async function stop(runtime, opts) {
-    if (state(runtime) === "stopped")
-        return false;
-    await guard("sandbox", () => runtime.stop({ wait: false, ...request(opts) }));
-    return true;
+/** How many seconds past its current end `now + timeoutMs` is; 0 for a
+ * sandbox with no time limit, which has no end to move. A second either way
+ * is the clocks and the trip, not a new end. */
+function secondsLater(runtime, timeoutMs) {
+    if (runtime.info.endsAt === null)
+        return 0;
+    const end = Date.parse(runtime.info.endsAt ?? runtime.info.expiresAt);
+    return (Date.now() + timeoutMs - end) / 1000;
 }
 async function extendTo(runtime, timeoutMs, opts) {
     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);
+    const later = secondsLater(runtime, timeoutMs);
+    if (later < -1)
+        throw new NotSupportedError("Ending a sandbox sooner than its time limit (a shorter setTimeout)", "Runtime cannot bring a time limit forward. Call kill() when the work is done.");
+    if (later > 1)
+        await guard("sandbox", () => runtime.extend(Math.ceil(later), request(opts)));
 }
 async function pause(runtime, opts) {
-    if (opts.keepMemory === false)
-        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
+    if (snapshotMemory("mode", opts.mode, opts.keepMemory) === false)
+        throw filesOnlyPause();
     const current = state(runtime);
     if (current === "paused")
         return false;
@@ -609,6 +650,10 @@ export class SandboxPaginator {
     #opts;
     #pageSize;
     #local;
+    /** One E2B state asked for alone: Runtime's states are read together and
+     * sorted here, since a sandbox Runtime paused for being idle is running
+     * to E2B. */
+    #only;
     #page;
     #all;
     #offset;
@@ -627,9 +672,10 @@ export class SandboxPaginator {
                 query.startedAfter !== undefined ||
                 opts.order === "desc" ||
                 opts.nextToken !== undefined;
-        const states = query.state?.length ? query.state : ["running", "paused"];
+        const asked = new Set(query.state?.length ? query.state : ["running", "paused"]);
+        this.#only = asked.size === 1 ? [...asked][0] : undefined;
         this.#filter = {
-            state: states.flatMap((one) => (one === "running" ? [...RUNNING] : [...PAUSED])),
+            state: [...RUNNING, ...PAUSED],
             ...(query.metadata && Object.keys(query.metadata).length ? { labels: query.metadata } : {}),
             limit: this.#local ? 100 : Math.min(this.#pageSize, 100),
         };
@@ -658,21 +704,28 @@ export class SandboxPaginator {
             : await this.#client.sandboxes.list(this.#filter, this.#request));
         this.#page = page ?? undefined;
         this.#hasNext = Boolean(page?.hasMore);
-        const items = (page?.data ?? []).map(infoOf);
+        const items = (page?.data ?? []).map(infoOf).filter((info) => this.#wanted(info));
         this.#offset += items.length;
         return items;
     }
+    #wanted(info) {
+        return this.#only === undefined || info.state === this.#only;
+    }
     async #everyMatch() {
         const query = this.#opts.query ?? {};
         const templates = query.template === undefined
             ? undefined
-            : await templateIds(this.#client, query.template, this.#request);
+            : STOCK_TEMPLATES.has(query.template)
+                ? new Set(["base", ...STOCK_TEMPLATES])
+                : new Set([query.template]);
         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 (!this.#wanted(info))
+                    continue;
                 if (templates && !templates.has(info.templateId))
                     continue;
                 if (after !== undefined && info.startedAt.getTime() < after)
@@ -691,16 +744,6 @@ function tokenOffset(token) {
         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();