withruntime 0.9.0 → 0.11.0

package/dist/vercel/sandbox.js

@@ -1,8 +1,10 @@
+import { extensionSeconds, LeaseKeeper, LEASE_MAX_SECONDS } from "../compat/lease.js";
 import { RuntimeError } from "../errors.js";
 import { clientFor, signalOf, } from "./client.js";
 import { Command, CommandFinished, exitCodeOf } from "./command.js";
 import { APIError, guard, NotSupportedError, translate } from "./errors.js";
 import { FileSystem } from "./filesystem.js";
+import { rootOrThrow, SandboxUser, SandboxUserAlreadyExistsError, validateName, } from "./sandbox-user.js";
 import { Snapshot } from "./snapshot.js";
 /* Vercel Sandbox'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
@@ -14,7 +16,8 @@ export const MEMORY_MIB_PER_VCPU = 2048;
 /** Vercel's default timeout, 5 minutes. */
 export const DEFAULT_TIMEOUT_MS = 300_000;
 const MIN_LEASE_SECONDS = 60;
-const MAX_LEASE_SECONDS = 3600;
+/** Extend a long timeout's lease when less than this is left. */
+const LEASE_MARGIN_MS = 600_000;
 /** Commands without a timeout run until the sandbox ends: Runtime's longest. */
 const LONGEST_MS = 86_400_000;
 /** Vercel's working directory; `/workspace` on Runtime. */
@@ -27,15 +30,20 @@ const LEGACY_RUNTIMES = new Set(["node22", "node24", "node26", "python3.13"]);
 /** Vercel regions in the United States, where Runtime runs. */
 const US_REGIONS = new Set(["iad1", "sfo1", "cle1", "pdx1"]);
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function leaseSeconds(timeoutMs) {
+function checkTimeout(timeoutMs) {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
         throw new RangeError(`timeout must be a positive number of milliseconds, 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.extendTimeout(ms) before it ends to keep going, as often as needed.");
-    return Math.max(seconds, MIN_LEASE_SECONDS);
+    return Math.max(timeoutMs, MIN_LEASE_SECONDS * 1000);
+}
+/** The first lease for a timeout: all of it, or the hour a lease may run. */
+function leaseSeconds(timeoutMs) {
+    return Math.min(Math.ceil(checkTimeout(timeoutMs) / 1000), LEASE_MAX_SECONDS);
 }
 function refuseCreate(params) {
+    if (params.keepLastSnapshots !== undefined)
+        throw new NotSupportedError("Snapshot count and eviction policies (keepLastSnapshots)", "Omit it; manage saved snapshots explicitly with Snapshot.list and snapshot.delete.");
+    if (params.ports !== undefined)
+        validatePorts(params.ports);
     if (params.mounts && Object.keys(params.mounts).length)
         throw new NotSupportedError("Vercel Drives (mounts)", "Use a Runtime volume: withruntime: { create: { volumes: [{ volumeId, path }] } } (runtime.volumes creates one).");
     if (params.networkId !== undefined)
@@ -45,6 +53,11 @@ function refuseCreate(params) {
     if (params.failoverRegions?.length)
         throw new NotSupportedError("Failover regions (failoverRegions)", "Remove it: Runtime runs in one US region.");
 }
+function validatePorts(ports) {
+    if (!Array.isArray(ports) ||
+        ports.some((port) => !Number.isSafeInteger(port) || port < 1 || port > 65_535))
+        throw new RangeError("ports must contain only integers from 1 to 65535.");
+}
 /** Vercel's network policy as Runtime's rules. Header injection and
  * forwarding rules have no Runtime counterpart and are refused. */
 export function networkRules(policy) {
@@ -131,6 +144,12 @@ export class Sandbox {
     #persistent;
     #routes = new Map();
     #onResume;
+    #keeper;
+    /** Epoch ms the current session started, as the timeout counts from it. */
+    #sessionStart;
+    /** Vercel's timeout, when this object was given one or extended it. */
+    #timeoutMs;
+    #defaultUser;
     #linked;
     #deleted = false;
     /** Use Sandbox.create, Sandbox.get or Sandbox.getOrCreate. */
@@ -140,6 +159,17 @@ export class Sandbox {
         this.#env = { ...resolved.params.env };
         this.#persistent = resolved.params.persistent ?? resolved.runtime.info.onLeaseEnd !== "stop";
         this.#onResume = resolved.params.onResume;
+        const timeout = resolved.params.timeout;
+        this.#timeoutMs = timeout === undefined ? undefined : checkTimeout(timeout);
+        this.#sessionStart =
+            timeout === undefined
+                ? Date.parse(this.#rt.info.expiresAt) - this.#rt.info.timeoutSeconds * 1000
+                : Date.now();
+        this.#keeper = new LeaseKeeper({
+            sandbox: () => this.#rt,
+            until: () => this.#until(),
+            marginMs: () => Math.min(LEASE_MARGIN_MS, this.timeout / 2),
+        });
         this.fs = new FileSystem({
             name: this.name,
             files: async () => (await this.#live()).files,
@@ -204,9 +234,14 @@ export class Sandbox {
     get status() {
         return statusOf(this.#rt.state);
     }
-    /** Milliseconds. */
+    /** Milliseconds from the start of the session: the timeout given at
+     * create, with every extension, or the lease of a sandbox found by name. */
     get timeout() {
-        return this.#rt.info.timeoutSeconds * 1000;
+        return this.#timeoutMs ?? this.#rt.info.timeoutSeconds * 1000;
+    }
+    /** Epoch ms the session should end: its start plus the timeout. */
+    #until() {
+        return this.#sessionStart + this.timeout;
     }
     get expiresAt() {
         return new Date(this.#rt.info.expiresAt);
@@ -227,6 +262,8 @@ export class Sandbox {
         refuseCreate(params);
         const client = clientFor(params);
         const persistent = params.persistent ?? true;
+        if (params.snapshotExpiration !== undefined && persistent)
+            retentionDays(params.snapshotExpiration);
         const vcpus = params.resources?.vcpus ?? DEFAULT_VCPUS;
         const source = await guard(() => resolveImage(client, params));
         const input = {
@@ -240,11 +277,18 @@ export class Sandbox {
             ...params.withruntime?.create,
         };
         const runtime = await guard(() => client.sandboxes.create(input, signalOf(params)));
-        const sandbox = new Sandbox({ runtime, client, params: { ...params, persistent } });
+        const sandbox = new Sandbox({
+            runtime,
+            client,
+            params: { ...params, persistent, timeout: params.timeout ?? DEFAULT_TIMEOUT_MS },
+        });
         try {
             await sandbox.#setUp(params);
+            // Starts renewing at once when the timeout runs past the first lease.
+            await sandbox.#keeper.check();
         }
         catch (error) {
+            sandbox.#keeper.end();
             await runtime.stop({ wait: false }).catch(() => undefined);
             throw translate(error, sandbox.name);
         }
@@ -300,15 +344,16 @@ export class Sandbox {
     /** A sandbox by name (or Runtime id), woken if it is paused unless
      * `resume: false`. */
     static async get(params) {
+        params.signal?.throwIfAborted();
         const client = clientFor(params);
-        const runtime = await guard(() => find(client, params.name), params.name);
+        const runtime = await guard(() => find(client, params.name, params), params.name);
         const sandbox = new Sandbox({
             runtime,
             client,
             params: params.onResume ? { onResume: params.onResume } : {},
         });
         if (params.resume !== false)
-            await sandbox.#live();
+            await sandbox.#live(params);
         return sandbox;
     }
     /** The named sandbox, or a new one with that name when there is none. */
@@ -329,9 +374,22 @@ export class Sandbox {
     /** A new sandbox copied from a running one, memory and all (a Runtime
      * fork). `sourceSandbox` is its name. */
     static async fork(params) {
-        const unsupported = ["resources", "ports", "timeout", "networkPolicy", "image", "tags", "env"].find((field) => params[field] !== undefined);
+        const unsupported = [
+            "resources",
+            "ports",
+            "timeout",
+            "networkPolicy",
+            "image",
+            "tags",
+            "env",
+            "persistent",
+            "snapshotExpiration",
+            "keepLastSnapshots",
+            "onResume",
+            "runtime",
+        ].find((field) => params[field] !== undefined);
         if (unsupported)
-            throw new NotSupportedError(`Overriding ${unsupported} on a fork`, "Fork without it; the copy keeps the source's machine, lease and rules.");
+            throw new NotSupportedError(`Overriding ${unsupported} on a fork`, "Omit the override to use Runtime's existing fork behavior.");
         refuseCreate(params);
         const source = await Sandbox.get({ ...params, name: params.sourceSandbox });
         const copy = await guard(() => source.#rt.fork({ ...(params.name ? { name: params.name } : {}), ...signalOf(params) }), params.sourceSandbox);
@@ -342,22 +400,27 @@ export class Sandbox {
         });
     }
     /** Running and stopped (paused) sandboxes, oldest first, with Vercel's
-     * paginator: `for await (const s of await Sandbox.list())`. */
+     * paginator: `for await (const s of await Sandbox.list())`. A name prefix,
+     * creation-time bounds (`since`, `until`, epoch ms), `sortBy` and
+     * `sortOrder`, and a `cursor` from an earlier page are applied here, over
+     * every sandbox the key sees. */
     static async list(params = {}) {
-        for (const field of ["since", "until", "cursor", "sortBy", "sortOrder", "namePrefix"])
-            if (params[field] !== undefined)
-                throw new NotSupportedError(`Listing sandboxes by ${field}`, "List them all (oldest first) and filter the result yourself.");
+        params.signal?.throwIfAborted();
         const client = clientFor(params);
+        const local = ["namePrefix", "sortBy", "sortOrder", "cursor", "since", "until"].some((field) => params[field] !== undefined);
+        if (local)
+            return listHere(client, params);
         const page = await guard(() => client.sandboxes.list({
             ...(params.tags ? { labels: params.tags } : {}),
             ...(params.limit ? { limit: Math.min(params.limit, 100) } : {}),
-        }));
-        return paginate(page);
+        }, signalOf(params)));
+        return paginate(page, params.signal);
     }
     // ---- commands ---------------------------------------------------------
     /** Wakes the sandbox if it was paused (a stopped persistent sandbox, in
      * Vercel's words), as Vercel resumes one on the next call. */
-    async #live() {
+    async #live(opts = {}) {
+        opts.signal?.throwIfAborted();
         if (this.#deleted)
             throw new APIError(new Response(null, { status: 410 }), {
                 message: `Sandbox ${this.name} was deleted.`,
@@ -365,35 +428,48 @@ export class Sandbox {
             });
         const state = this.#rt.state;
         if (state === "paused" || state === "pausing")
-            await this.#wake();
+            await this.#wake(opts);
+        await guard(() => this.#keeper.check(), this.name);
         return this.#rt;
     }
-    async #wake() {
-        await guard(() => this.#rt.wake({}), this.name);
+    /** A woken sandbox starts a new session, whose timeout counts from now,
+     * as Vercel's resumed sessions do. */
+    async #wake(opts = {}) {
+        await guard(() => this.#rt.wake(signalOf(opts)), this.name);
+        if (this.#timeoutMs !== undefined)
+            this.#sessionStart = Date.now();
         await this.#onResume?.(this);
     }
     /** Runs `work` on the live sandbox; if the lease paused it meanwhile, wakes
      * it and runs `work` once more. */
-    async #withResume(work) {
-        const runtime = await this.#live();
+    async #withResume(work, opts = {}) {
+        opts.signal?.throwIfAborted();
+        const runtime = await this.#live(opts);
         try {
             return await work(runtime);
         }
         catch (error) {
             if (!(error instanceof RuntimeError && error.code === "sandbox_paused"))
                 throw translate(error, this.name);
-            await guard(() => runtime.refresh(), this.name);
-            await this.#wake();
+            await guard(() => runtime.refresh(signalOf(opts)), this.name);
+            await this.#wake(opts);
             return guard(() => work(this.#rt), this.name);
         }
     }
-    async #linkHome(text) {
+    async #linkHome(text, opts = {}) {
+        opts.signal?.throwIfAborted();
         if (this.#linked || !text.includes(HOME))
             return this.#linked;
         this.#linked = (async () => {
-            await this.#rt.exec(HOME_LINK).catch(() => undefined);
+            await this.#rt.exec(HOME_LINK, signalOf(opts)).catch(() => opts.signal?.throwIfAborted());
         })();
-        return this.#linked;
+        try {
+            await this.#linked;
+        }
+        catch (error) {
+            this.#linked = undefined;
+            throw error;
+        }
     }
     async runCommand(commandOrParams, args, opts = {}) {
         const params = typeof commandOrParams === "string"
@@ -406,18 +482,19 @@ export class Sandbox {
         ];
         const cwd = params.cwd === undefined ? RUNTIME_HOME : toRuntimePath(params.cwd);
         const env = { ...this.#env, ...params.env };
-        await this.#live();
-        await this.#linkHome(`${argv.join(" ")}\n${params.cwd ?? ""}\n${Object.values(env).join("\n")}`);
+        await this.#live(params);
+        await this.#linkHome(`${argv.join(" ")}\n${params.cwd ?? ""}\n${Object.values(env).join("\n")}`, params);
         const timeoutMs = params.timeoutMs ?? LONGEST_MS;
         const common = {
             cwd,
             ...(Object.keys(env).length ? { env } : {}),
             timeoutMs,
+            ...signalOf(params),
         };
         const startedAt = Date.now();
         const vercelCwd = params.cwd === undefined ? HOME : toVercelPath(params.cwd);
         if (params.detached) {
-            const process = await this.#withResume((runtime) => runtime.spawn(argv, common));
+            const process = await this.#withResume((runtime) => runtime.spawn(argv, common), params);
             const command = new Command({
                 id: process.id,
                 cwd: vercelCwd,
@@ -438,8 +515,7 @@ export class Sandbox {
             ...common,
             onStdout: record("stdout", params.stdout),
             onStderr: record("stderr", params.stderr),
-            ...signalOf(params),
-        }));
+        }), params);
         return new CommandFinished({
             id: result.processId ?? `cmd_${startedAt}`,
             cwd: vercelCwd,
@@ -449,8 +525,8 @@ export class Sandbox {
         }, exitCodeOf(result.exitCode, result.timedOut), result.durationMs ?? Date.now() - startedAt);
     }
     /** A command started earlier, by its cmdId. */
-    async getCommand(cmdId, _opts = {}) {
-        const process = await this.#withResume((runtime) => runtime.processes.get(cmdId));
+    async getCommand(cmdId, opts = {}) {
+        const process = await this.#withResume((runtime) => runtime.processes.get(cmdId, signalOf(opts)), opts);
         return new Command({
             id: process.id,
             cwd: process.info.cwd,
@@ -460,9 +536,9 @@ export class Sandbox {
         });
     }
     // ---- files ------------------------------------------------------------
-    async mkDir(path, _opts = {}) {
+    async mkDir(path, opts = {}) {
         const target = toRuntimePath(path);
-        await this.#withResume((runtime) => runtime.files.mkdir(target, { parents: true }));
+        await this.#withResume((runtime) => runtime.files.mkdir(target, { parents: true, ...signalOf(opts) }), opts);
     }
     /** The file's bytes as a Node stream, or null when there is no file. */
     async readFile(file, opts = {}) {
@@ -476,7 +552,7 @@ export class Sandbox {
     async readFileToBuffer(file, opts = {}) {
         const target = toRuntimePath(file.path, file.cwd);
         try {
-            return Buffer.from(await this.#withResume((runtime) => runtime.files.read(target, signalOf(opts))));
+            return Buffer.from(await this.#withResume((runtime) => runtime.files.read(target, signalOf(opts)), opts));
         }
         catch (error) {
             if (error instanceof APIError && error.response.status === 404)
@@ -489,39 +565,42 @@ export class Sandbox {
         const buffer = await this.readFileToBuffer(src, opts);
         if (buffer === null)
             return null;
+        opts.signal?.throwIfAborted();
         const { mkdir, writeFile } = await import("node:fs/promises");
         const paths = await import("node:path");
         const target = paths.resolve(dst.cwd ?? process.cwd(), dst.path);
+        opts.signal?.throwIfAborted();
         if (opts.mkdirRecursive)
             await mkdir(paths.dirname(target), { recursive: true });
-        await writeFile(target, buffer);
+        await writeFile(target, buffer, signalOf(opts));
         return target;
     }
     /** Writes files, making their directories. Relative paths land in the
      * working directory; `mode` sets permissions. */
-    async writeFiles(files, _opts = {}) {
+    async writeFiles(files, opts = {}) {
         const modes = [];
         await this.#withResume(async (runtime) => {
             for (const file of files) {
                 const target = toRuntimePath(file.path);
-                await runtime.files.write(target, file.content);
+                await runtime.files.write(target, file.content, signalOf(opts));
                 if (file.mode !== undefined)
                     modes.push(file.mode.toString(8), target);
             }
             if (!modes.length)
                 return;
             const script = 'while [ "$#" -gt 0 ]; do chmod "$1" "$2" || exit 1; shift 2; done';
-            const result = await runtime.exec(["sh", "-c", script, "sh", ...modes]);
+            const result = await runtime.exec(["sh", "-c", script, "sh", ...modes], signalOf(opts));
             if (result.exitCode !== 0)
                 throw new APIError(new Response(null, { status: 400 }), {
                     message: `Setting file modes failed: ${result.stderr.trim()}`,
                     sandboxName: this.name,
                 });
-        });
+        }, opts);
     }
     // ---- ports ------------------------------------------------------------
-    async #share(port) {
-        const preview = await guard(() => this.#rt.previews.create(port, { visibility: "public" }), this.name);
+    async #share(port, opts = {}) {
+        opts.signal?.throwIfAborted();
+        const preview = await guard(() => this.#rt.previews.create(port, { visibility: "public" }, signalOf(opts)), this.name);
         this.#routes.set(port, preview.url.replace(/\/$/, ""));
     }
     /** The public address of a port listed in `ports`, such as
@@ -545,6 +624,8 @@ export class Sandbox {
             else
                 await guard(() => this.#rt.stop(signalOf(opts)), this.name);
         }
+        if (!this.#persistent)
+            this.#keeper.end();
         return { name: this.name, status: this.status };
     }
     /** Ends the sandbox for good. */
@@ -555,87 +636,191 @@ export class Sandbox {
         if (this.#rt.state !== "stopped")
             await guard(() => this.#rt.stop({ wait: false, ...signalOf(opts) }), this.name);
         this.#deleted = true;
+        this.#keeper.end();
     }
     async [Symbol.asyncDispose]() {
         if (this.#deleted)
             return;
         await this.stop().catch(() => undefined);
     }
-    /** Moves the end `duration` milliseconds later (at most an hour ahead of
-     * now on Runtime). */
+    /** Moves the end `duration` milliseconds later. The lease moves at once
+     * as far as it may (an hour ahead of now); past that it is extended while
+     * this object lives. */
     async extendTimeout(duration, opts = {}) {
         if (!Number.isFinite(duration) || duration <= 0)
             throw new RangeError(`duration must be a positive number of milliseconds, not ${duration}.`);
-        await this.#withResume((runtime) => runtime.extend(Math.ceil(duration / 1000), signalOf(opts)));
+        await this.#withResume(async (runtime) => {
+            this.#timeoutMs = this.timeout + duration;
+            await this.#leaseToTimeout(runtime, opts);
+        }, opts);
+    }
+    /** Extends the lease now toward the timeout, an hour ahead at most. */
+    async #leaseToTimeout(runtime, opts) {
+        const seconds = extensionSeconds(Date.parse(runtime.info.expiresAt), this.#until(), Date.now(), Infinity);
+        if (seconds >= 1)
+            await runtime.extend(seconds, signalOf(opts));
     }
     /** Replaces the network rules; returns the policy given. */
-    async updateNetworkPolicy(networkPolicy, _opts = {}) {
+    async updateNetworkPolicy(networkPolicy, opts = {}) {
+        opts.signal?.throwIfAborted();
         const rules = networkRules(networkPolicy);
-        await this.#withResume((runtime) => runtime.network.set(rules));
+        await this.#withResume((runtime) => runtime.network.set(rules, signalOf(opts)), opts);
         return networkPolicy;
     }
     /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
      * `networkPolicy` and `snapshotExpiration`. Anything else is refused before
      * anything changes. */
-    async update(params, _opts = {}) {
+    async update(params, opts = {}) {
+        opts.signal?.throwIfAborted();
         const allowed = new Set(["timeout", "ports", "networkPolicy", "snapshotExpiration"]);
         const other = Object.keys(params).find((key) => params[key] !== undefined && !allowed.has(key));
         if (other)
             throw new NotSupportedError(`Changing ${other} on an existing sandbox`, "Create a new sandbox with it (Runtime cannot change a sandbox's machine, persistence, tags or region after creation).");
+        const rules = params.networkPolicy === undefined ? undefined : networkRules(params.networkPolicy);
+        const retention = params.snapshotExpiration === undefined
+            ? undefined
+            : retentionDays(params.snapshotExpiration);
+        if (params.ports !== undefined)
+            validatePorts(params.ports);
+        const wanted = params.ports === undefined ? undefined : new Set(params.ports);
         if (params.timeout !== undefined) {
-            const current = this.timeout;
-            if (params.timeout < current)
-                throw new NotSupportedError("Shortening a sandbox's timeout", "Runtime leases only move later. Call stop() when the work is done.");
-            if (params.timeout > current)
-                await this.extendTimeout(params.timeout - current);
+            const timeout = checkTimeout(params.timeout);
+            // A shorter timeout is kept when the lease has not reached it yet: the
+            // lease then stops being extended there. Runtime cannot end a lease
+            // earlier than it was given.
+            if (this.#sessionStart + timeout < Date.parse(this.#rt.info.expiresAt) - 1000)
+                throw new NotSupportedError("A timeout that ends earlier than the current lease", `The lease runs to ${this.#rt.info.expiresAt}; call stop() when the work is done, or pass a timeout that ends after it.`);
+            const longer = timeout > this.timeout;
+            this.#timeoutMs = timeout;
+            if (longer)
+                await this.#withResume((runtime) => this.#leaseToTimeout(runtime, opts), opts);
         }
-        if (params.networkPolicy !== undefined)
-            await this.updateNetworkPolicy(params.networkPolicy);
-        if (params.snapshotExpiration !== undefined)
-            await guard(() => this.#rt.setRetention(retentionDays(params.snapshotExpiration)), this.name);
-        if (params.ports !== undefined) {
-            const wanted = new Set(params.ports);
+        if (rules !== undefined)
+            await this.#withResume((runtime) => runtime.network.set(rules, signalOf(opts)), opts);
+        if (retention !== undefined)
+            await guard(() => this.#rt.setRetention(retention, signalOf(opts)), this.name);
+        if (wanted !== undefined) {
             for (const port of [...this.#routes.keys()])
                 if (!wanted.has(port)) {
-                    await guard(() => this.#rt.previews.delete(port), this.name);
+                    await guard(() => this.#rt.previews.delete(port, signalOf(opts)), this.name);
                     this.#routes.delete(port);
                 }
             for (const port of wanted)
                 if (!this.#routes.has(port))
-                    await this.#share(port);
+                    await this.#share(port, opts);
         }
     }
-    /** Keeps the sandbox's whole machine as a Runtime snapshot (files, memory
-     * and running processes), then stops the sandbox, as Vercel does. Start
+    /** Keeps the sandbox's filesystem as a disk-only snapshot, then stops
+     * the source. Restoring it starts fresh processes, as Vercel does. Start
      * from it with `Sandbox.create({ source: { type: "snapshot", snapshotId } })`. */
     async snapshot(opts = {}) {
+        opts.signal?.throwIfAborted();
+        const retention = opts.expiration === undefined ? undefined : retentionDays(opts.expiration);
         const taken = await this.#withResume((runtime) => runtime.snapshot({
-            ...(opts.expiration !== undefined ? { retentionDays: retentionDays(opts.expiration) } : {}),
-        }));
-        await guard(() => this.#rt.stop({ wait: false }), this.name);
+            mode: "disk",
+            ...(retention !== undefined ? { retentionDays: retention } : {}),
+            ...signalOf(opts),
+        }), opts);
+        try {
+            await guard(() => this.#rt.stop(signalOf(opts)), this.name);
+            if (this.#rt.state !== "stopped")
+                await guard(() => this.#rt.waitFor("stopped", signalOf(opts)), this.name);
+        }
+        catch (error) {
+            const recovery = { snapshotId: taken.id, sourceSandboxId: this.#rt.id };
+            if (error instanceof APIError) {
+                const json = error.json;
+                error.json = {
+                    ...json,
+                    error: {
+                        ...json?.error,
+                        details: { ...(json?.error?.details ?? {}), ...recovery },
+                    },
+                };
+            }
+            else if (error instanceof Error && Object.isExtensible(error)) {
+                Object.assign(error, recovery);
+            }
+            throw error;
+        }
+        if (this.#rt.state !== "stopped") {
+            const code = "snapshot_source_stop_timeout";
+            const message = `Snapshot ${taken.id} was saved, but sandbox ${this.name} did not finish stopping.`;
+            const error = new APIError(new Response(null, { status: 409 }), {
+                message,
+                sandboxName: this.name,
+                json: {
+                    error: { code, message, details: { snapshotId: taken.id, sourceSandboxId: this.#rt.id } },
+                },
+            });
+            error.code = code;
+            throw error;
+        }
         return new Snapshot(taken, this.#client);
     }
     // ---- what Runtime does differently -----------------------------------
+    /** Refused: Vercel hands back a token scoped to this one shell, and
+     * Runtime's terminal opens with the account key, which must not leave the
+     * server. */
     openInteractive() {
         return Promise.reject(new NotSupportedError("Vercel's interactive shell (openInteractive)", "Use `await sandbox.withruntime.terminal({ cols, rows, onData })`, or `npx withruntime sandbox shell <id>`."));
     }
-    getDefaultUser() {
-        return Promise.resolve({ username: "runtime", group: "runtime" });
-    }
-    createUser() {
-        return usersRefused();
-    }
-    asUser() {
-        throw usersError();
-    }
-    createGroup() {
-        return usersRefused();
+    /** The user commands run as, `runtime`, and its group. */
+    getDefaultUser(_opts = {}) {
+        this.#defaultUser ??= Promise.resolve({ username: "runtime", group: "runtime" });
+        return this.#defaultUser;
+    }
+    /** Makes a Linux user with its own home, as Vercel does: `useradd -m`,
+     * then the home given to the user and the sandbox's group, mode 770. */
+    async createUser(username, opts = {}) {
+        validateName(username, "username");
+        const { group } = await this.getDefaultUser(opts);
+        const signal = opts.signal;
+        const useradd = await this.runCommand({
+            cmd: "useradd",
+            args: ["-m", "-s", "/bin/bash", username],
+            sudo: true,
+            ...(signal ? { signal } : {}),
+        });
+        if (useradd.exitCode !== 0) {
+            if (useradd.exitCode === 9)
+                throw new SandboxUserAlreadyExistsError(username);
+            throw new Error(`Failed to create user "${username}": ${await useradd.stderr()}`);
+        }
+        const home = `/home/${username}`;
+        await rootOrThrow(this, "chown", [`${username}:${group}`, home], signal, () => `Failed to set ownership on ${home}`);
+        await rootOrThrow(this, "chmod", ["770", home], signal, () => `Failed to set permissions on ${home}`);
+        return new SandboxUser({ sandbox: this, username });
+    }
+    /** A handle for an existing user, such as `root`. */
+    asUser(username) {
+        validateName(username, "username");
+        return new SandboxUser({ sandbox: this, username });
+    }
+    /** Makes a group and its shared directory, `/shared/<group>`, setgid 2770. */
+    async createGroup(groupname, opts = {}) {
+        validateName(groupname, "group name");
+        const { username } = await this.getDefaultUser(opts);
+        const sharedDir = `/shared/${groupname}`;
+        const steps = [
+            ["groupadd", [groupname], `Failed to create group "${groupname}"`],
+            ["mkdir", ["-p", sharedDir], `Failed to create shared directory ${sharedDir}`],
+            ["chown", [`${username}:${groupname}`, sharedDir], `Failed to set ownership on ${sharedDir}`],
+            ["chmod", ["2770", sharedDir], `Failed to set permissions on ${sharedDir}`],
+        ];
+        for (const [cmd, args, what] of steps)
+            await rootOrThrow(this, cmd, args, opts.signal, () => what);
+        return { groupname, sharedDir };
     }
-    addUserToGroup() {
-        return usersRefused();
+    async addUserToGroup(username, groupname, opts = {}) {
+        validateName(username, "username");
+        validateName(groupname, "group name");
+        await rootOrThrow(this, "usermod", ["-aG", groupname, username], opts.signal, () => `Failed to add "${username}" to group "${groupname}"`);
     }
-    removeUserFromGroup() {
-        return usersRefused();
+    async removeUserFromGroup(username, groupname, opts = {}) {
+        validateName(username, "username");
+        validateName(groupname, "group name");
+        await rootOrThrow(this, "gpasswd", ["-d", username, groupname], opts.signal, () => `Failed to remove "${username}" from group "${groupname}"`);
     }
     currentSession() {
         throw new NotSupportedError("Vercel sessions (currentSession)", "A Runtime sandbox is its own session: call the methods on the sandbox.");
@@ -647,15 +832,11 @@ export class Sandbox {
         return Promise.reject(new NotSupportedError("Listing a sandbox's snapshots from the sandbox", "Use Snapshot.list({ name }) or runtime.snapshots.list({ sandboxId })."));
     }
 }
-function usersError() {
-    return new NotSupportedError("Extra Linux users and groups (createUser, asUser, groups)", "Commands run as the sandbox owner with passwordless sudo; run `sudo useradd ...` and `sudo -u <user> ...` with runCommand.");
-}
-function usersRefused() {
-    return Promise.reject(usersError());
-}
 /** Milliseconds as whole days for Runtime's retention: 1 to 365, and 0 (no
  * expiration) as 365. */
 export function retentionDays(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        throw new RangeError(`Snapshot expiration must be a nonnegative finite number of milliseconds, not ${ms}.`);
     if (ms === 0)
         return 365;
     return Math.min(365, Math.max(1, Math.ceil(ms / 86_400_000)));
@@ -671,11 +852,13 @@ async function pipe(command, params) {
 }
 /** The newest live sandbox with this name, or the sandbox with this Runtime
  * id. A 404 when there is none. */
-async function find(client, name) {
+async function find(client, name, opts = {}) {
+    opts.signal?.throwIfAborted();
     if (UUID.test(name))
-        return client.sandboxes.get(name);
-    const page = await client.sandboxes.list({ name });
+        return client.sandboxes.get(name, signalOf(opts));
+    const page = await client.sandboxes.list({ name }, signalOf(opts));
     const all = await page.toArray(1000);
+    opts.signal?.throwIfAborted();
     const found = all.filter((one) => one.state !== "stopped").at(-1);
     if (!found)
         throw new RuntimeError({
@@ -703,24 +886,95 @@ function itemOf(runtime) {
         tags: { ...info.labels },
     };
 }
+const CURSOR = /^rt\.([0-9]+)$/;
+/** Sandbox.list with a name prefix, time bounds, sorting or a cursor:
+ * applied here over every sandbox the key sees, since Runtime's list filters
+ * only by labels and name. The cursor is this adapter's own, an offset into
+ * the same query. */
+async function listHere(client, params) {
+    let offset = 0;
+    if (params.cursor !== undefined) {
+        const match = CURSOR.exec(params.cursor);
+        if (!match)
+            throw new RangeError(`The cursor "${params.cursor}" was not made by Sandbox.list here; pass pagination.next from an earlier page of the same query.`);
+        offset = Number(match[1]);
+    }
+    if (params.sortBy !== undefined &&
+        !["createdAt", "name", "statusUpdatedAt"].includes(params.sortBy))
+        throw new RangeError("sortBy must be createdAt, name or statusUpdatedAt.");
+    if (params.sortOrder !== undefined && !["asc", "desc"].includes(params.sortOrder))
+        throw new RangeError("sortOrder must be asc or desc.");
+    const page = await guard(() => client.sandboxes.list(params.tags ? { labels: params.tags } : {}, signalOf(params)));
+    const all = (await guard(() => page.toArray(10_000))).map(itemOf);
+    params.signal?.throwIfAborted();
+    const time = (value) => value === undefined ? undefined : value instanceof Date ? value.getTime() : value;
+    const since = time(params.since);
+    const until = time(params.until);
+    const items = all.filter((one) => (params.namePrefix === undefined || one.name.startsWith(params.namePrefix)) &&
+        (since === undefined || one.createdAt >= since) &&
+        (until === undefined || one.createdAt <= until));
+    const by = params.sortBy ?? "createdAt";
+    const key = (one) => by === "name" ? one.name : by === "statusUpdatedAt" ? one.updatedAt : one.createdAt;
+    const direction = params.sortOrder === "desc" ? -1 : 1;
+    items.sort((a, b) => {
+        const [x, y] = [key(a), key(b)];
+        return (x < y ? -1 : x > y ? 1 : 0) * direction;
+    });
+    const size = Math.max(1, Math.min(params.limit ?? 50, 100));
+    const pageAt = (from) => {
+        const sandboxes = items.slice(from, from + size);
+        return {
+            sandboxes,
+            pagination: {
+                count: sandboxes.length,
+                next: from + size < items.length ? `rt.${from + size}` : null,
+            },
+        };
+    };
+    return Object.assign(pageAt(offset), {
+        async *pages() {
+            for (let from = offset; from === offset || from < items.length; from += size) {
+                params.signal?.throwIfAborted();
+                yield pageAt(from);
+            }
+        },
+        async *[Symbol.asyncIterator]() {
+            for (const item of items.slice(offset)) {
+                params.signal?.throwIfAborted();
+                yield item;
+            }
+        },
+        async toArray() {
+            params.signal?.throwIfAborted();
+            return items.slice(offset);
+        },
+    });
+}
 /** Vercel's paginator over a Runtime page: the first page's fields, async
  * iteration over every item, `pages()` and `toArray()`. */
-function paginate(first) {
+function paginate(first, signal) {
     const toPage = (page) => ({
         sandboxes: page.data.map(itemOf),
         pagination: { count: page.data.length, next: page.nextCursor },
     });
     return Object.assign(toPage(first), {
         async *pages() {
-            for await (const page of first.pages())
+            for await (const page of first.pages()) {
+                signal?.throwIfAborted();
                 yield toPage(page);
+            }
         },
         async *[Symbol.asyncIterator]() {
-            for await (const item of first)
+            for await (const item of first) {
+                signal?.throwIfAborted();
                 yield itemOf(item);
+            }
         },
         async toArray() {
-            return (await first.toArray()).map(itemOf);
+            signal?.throwIfAborted();
+            const items = await first.toArray();
+            signal?.throwIfAborted();
+            return items.map(itemOf);
         },
     });
 }