withruntime 0.10.0 → 0.11.1

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
@@ -11,10 +13,13 @@ import { Snapshot } from "./snapshot.js";
  * 2026). Runtime gives 2 vCPU and 4096 MiB. */
 export const DEFAULT_VCPUS = 2;
 export const MEMORY_MIB_PER_VCPU = 2048;
-/** Vercel's default timeout, 5 minutes. */
+/** Vercel's default timeout, 5 minutes. Not sent: a sandbox created with no
+ * timeout has no time limit on Runtime, running while it works and pausing
+ * when idle (0300). Kept for code that imports it. */
 export const DEFAULT_TIMEOUT_MS = 300_000;
 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,13 +32,14 @@ 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)
@@ -140,6 +146,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. */
@@ -149,6 +161,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,
@@ -213,9 +236,15 @@ 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 time limit of a sandbox found by
+     * name. 0 for one with no time limit, which runs while it works. */
     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);
@@ -229,7 +258,8 @@ export class Sandbox {
     }
     // ---- create, get, list ------------------------------------------------
     /** Creates a sandbox and waits until it runs. Vercel's defaults: 2 vCPUs,
-     * 2048 MiB per vCPU, a 5-minute timeout, persistent. Funding is left to
+     * 2048 MiB per vCPU, persistent. With no `timeout` it has no time limit: it
+     * runs while it works and pauses when idle. A `timeout` is kept as given. Funding is left to
      * Runtime: the free trial while the account has trial time, then prepaid
      * credit, exactly as withruntime's own create. */
     static async create(params = {}) {
@@ -242,7 +272,8 @@ export class Sandbox {
         const source = await guard(() => resolveImage(client, params));
         const input = {
             ...(source.snapshot ? {} : { vcpu: vcpus, memoryMiB: vcpus * MEMORY_MIB_PER_VCPU }),
-            timeoutSeconds: leaseSeconds(params.timeout ?? DEFAULT_TIMEOUT_MS),
+            // No timeout, no time limit: it runs while it works (0300).
+            ...(params.timeout === undefined ? {} : { timeoutSeconds: leaseSeconds(params.timeout) }),
             onLeaseEnd: persistent ? "pause" : "stop",
             ...(params.name ? { name: params.name } : {}),
             ...(params.tags && Object.keys(params.tags).length ? { labels: params.tags } : {}),
@@ -251,11 +282,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 },
+        });
         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);
         }
@@ -367,13 +405,16 @@ 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 = {}) {
         params.signal?.throwIfAborted();
-        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.");
         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) } : {}),
@@ -393,10 +434,15 @@ export class Sandbox {
         const state = this.#rt.state;
         if (state === "paused" || state === "pausing")
             await this.#wake(opts);
+        await guard(() => this.#keeper.check(), this.name);
         return this.#rt;
     }
+    /** 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
@@ -583,6 +629,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. */
@@ -593,18 +641,34 @@ 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 time limit moves at
+     * once as far as it may (an hour ahead of now); past that it is extended
+     * while this object lives. A sandbox with no time limit has no end to
+     * move, and nothing changes. */
     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)), opts);
+        await this.#withResume(async (runtime) => {
+            if (runtime.info.endsAt === null)
+                return;
+            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) {
+        if (runtime.info.endsAt === null)
+            return;
+        const seconds = extensionSeconds(Date.parse(runtime.info.endsAt ?? 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 = {}) {
@@ -615,7 +679,8 @@ export class Sandbox {
     }
     /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
      * `networkPolicy` and `snapshotExpiration`. Anything else is refused before
-     * anything changes. */
+     * anything changes. A `timeout` on a sandbox with no time limit changes
+     * nothing: it runs while it works. */
     async update(params, opts = {}) {
         opts.signal?.throwIfAborted();
         const allowed = new Set(["timeout", "ports", "networkPolicy", "snapshotExpiration"]);
@@ -629,12 +694,19 @@ export class Sandbox {
         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, opts);
+        // A sandbox with no time limit has none to change (0300).
+        if (params.timeout !== undefined && this.#rt.info.endsAt !== null) {
+            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.
+            const end = this.#rt.info.endsAt ?? this.#rt.info.expiresAt;
+            if (this.#sessionStart + timeout < Date.parse(end) - 1000)
+                throw new NotSupportedError("A timeout that ends earlier than the current lease", `The lease runs to ${end}; 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 (rules !== undefined)
             await this.#withResume((runtime) => runtime.network.set(rules, signalOf(opts)), opts);
@@ -700,26 +772,68 @@ export class Sandbox {
         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.");
@@ -731,12 +845,6 @@ 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) {
@@ -791,6 +899,70 @@ 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, signal) {

package/dist/wait.d.ts

@@ -0,0 +1,12 @@
+import type { RequestOptions } from "./transport.js";
+/** A wait that an abort ends at once, rejecting with the signal's reason. */
+export declare function pause(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function abortError(signal: AbortSignal): Error;
+/**
+ * Calls `attempt` until it stops answering one of `codes` (something is
+ * still installing), within one budget: the caller's `timeoutMs`, else ten
+ * minutes. Each try gets what is left of it; a wait between tries ends at once
+ * on abort, and no try starts once the budget cannot cover the wait the API
+ * asked for: the installing error is thrown instead.
+ */
+export declare function whileInstalling<T>(codes: readonly string[], options: RequestOptions | undefined, attempt: (options: RequestOptions) => Promise<T>): Promise<T>;

package/dist/wait.js

@@ -0,0 +1,47 @@
+/** A wait that an abort ends at once, rejecting with the signal's reason. */
+export function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(abortError(signal));
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        function stop() {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        }
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}
+export function abortError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+}
+/** How long a start waits for a first install (Chromium, the desktop) when
+ * the caller sets no deadline. */
+const INSTALL_WAIT_MS = 600_000;
+/**
+ * Calls `attempt` until it stops answering one of `codes` (something is
+ * still installing), within one budget: the caller's `timeoutMs`, else ten
+ * minutes. Each try gets what is left of it; a wait between tries ends at once
+ * on abort, and no try starts once the budget cannot cover the wait the API
+ * asked for: the installing error is thrown instead.
+ */
+export async function whileInstalling(codes, options, attempt) {
+    const deadline = performance.now() + (options?.timeoutMs || INSTALL_WAIT_MS);
+    for (;;) {
+        if (options?.signal?.aborted)
+            throw abortError(options.signal);
+        const left = Math.max(1, Math.ceil(deadline - performance.now()));
+        try {
+            return await attempt(options?.timeoutMs ? { ...options, timeoutMs: left } : { ...options });
+        }
+        catch (error) {
+            const code = error.code;
+            const wait = error.retryAfterMs ?? 10_000;
+            if (!code || !codes.includes(code) || performance.now() + wait > deadline)
+                throw error;
+            await pause(wait, options?.signal);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",