withruntime 0.11.0 → 0.11.1

package/dist/transport.js

@@ -1,6 +1,6 @@
-import { ConnectionError, DELIBERATE, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
+import { ConnectionError, DELIBERATE, errorFor, NOTHING_RAN, RuntimeError, WAITS_FOR_ROOM, } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.11.0";
+export const VERSION = "0.11.1";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -8,10 +8,11 @@ export const DEFAULT_BASE_URL = "https://api.withruntime.com";
  * because the hop never leaves the machine: it goes from the program to the
  * guest's own proxy and over the sandbox's private channel to its host. */
 export const SANDBOX_BASE_URL = "http://runtime.internal";
-/** Every Runtime sandbox has this file; guest-net.py keeps it current. */
-const SANDBOX_MARKER = "/run/runtime/environment.json";
+/** Every Runtime sandbox has this file; guest-net.py keeps it current. Tests
+ * move it, so the machine running them does not decide what they see. */
+export const sandboxMarker = { path: "/run/runtime/environment.json" };
 /** True in a Runtime sandbox. Node and Bun only; a browser is never one. */
-export function inRuntimeSandbox(marker = SANDBOX_MARKER) {
+export function inRuntimeSandbox(marker = sandboxMarker.path) {
     try {
         const host = globalThis.process;
         return host?.getBuiltinModule?.("node:fs")?.existsSync?.(marker) === true;
@@ -34,6 +35,18 @@ export function reachable(origin, inSandbox = inRuntimeSandbox) {
 function processEnv() {
     return (globalThis.process?.env ?? {});
 }
+/** How long an answer that ran nothing (NOTHING_RAN) is retried for a call
+ * that has no deadline of its own. */
+const NOTHING_RAN_MS = 300_000;
+/** How long one attempt waits for its answer to start. The API starts every
+ * answer within 120 s: Caddy answers 503 itself past that, and a longer call
+ * gets its 200 at 90 s and then its JSON (runtime-late-answer). An attempt
+ * with no answer by then is talking to a server that is gone, such as a
+ * controller that died with the call in flight while its address moved to
+ * the new leader: a client that only waits sends nothing the new leader could
+ * refuse, so it waited out the whole deadline and failed (the leader drill on
+ * vin-5, 4 October 2026). It is sent again under the same key. */
+export const ANSWER_START_MS = 125_000;
 export function apiOrigin(value) {
     const url = new URL(value);
     // runtime.internal is reserved and never resolves outside a sandbox, so a
@@ -141,14 +154,23 @@ function slots(maximum) {
         },
     };
 }
+/** Connections a client holds at once by default: under the 64 one address
+ * may hold to the API (api.md, "Limits"), with room for a second client. */
+export const DEFAULT_MAX_CONNECTIONS = 48;
+/** Connections a client keeps for answers read whole, however many streams
+ * are open: a stream's reader that makes a call (an output callback writing a
+ * file) never waits behind streams, its own included. */
+const KEPT_FOR_CALLS = 8;
 /** One connection pool, one retry policy, one error shape for every product.
  * Node's and Bun's fetch keep connections alive, so a client reused across
  * calls pays TLS once. Over HTTP/1.1 every call in flight holds its own
- * connection, so a hundred calls at once would open a hundred, past what one
- * address may hold at the edge (64). Answers read whole are therefore held to
- * `maxConnections` at once and the rest queue here, reusing those
- * connections; streams and terminals are long-lived and do not wait behind
- * them. */
+ * connection, and one address may hold 64 to the API before it has used a
+ * valid key: past that the API's edge holds new ones back until one closes.
+ * So a client holds at most `maxConnections` at once,
+ * answers and streams together, and the rest queue here, first come first
+ * served, and wait rather than fail. Streams (a command's output, a download,
+ * a watch) take at most `maxConnections` less KEPT_FOR_CALLS of them. A
+ * terminal or tunnel's WebSocket is not counted. */
 export class Transport {
     baseUrl;
     #apiKey;
@@ -157,9 +179,11 @@ export class Transport {
     /** Whether calls go through envFetch, so a failure can name its proxy. */
     #routed;
     #timeoutMs;
+    #answerStartMs;
     #maxRetries;
     #client;
     #slots;
+    #streams;
     /** What `sandboxes.create` waits for room by default. */
     waitForCapacityMs;
     constructor(options) {
@@ -175,9 +199,12 @@ export class Transport {
         this.#fetch = options.fetch ?? envFetch;
         this.#routed = options.fetch === undefined;
         this.#timeoutMs = options.timeoutMs ?? 300_000;
+        this.#answerStartMs = options.answerStartMs ?? ANSWER_START_MS;
         this.#maxRetries = options.maxRetries ?? 4;
         this.#client = options.client ?? `sdk-js/${VERSION}`;
-        this.#slots = slots(Math.max(1, options.maxConnections ?? 32));
+        const most = Math.max(1, options.maxConnections ?? DEFAULT_MAX_CONNECTIONS);
+        this.#slots = slots(most);
+        this.#streams = slots(Math.max(1, most - KEPT_FOR_CALLS));
         this.waitForCapacityMs = Math.max(0, options.waitForCapacityMs ?? 120_000);
     }
     /** The key, found once on first use when it was not given. */
@@ -225,6 +252,7 @@ export class Transport {
         return {
             ...call,
             timeoutMs: 0,
+            ...(timeoutMs === 0 ? {} : { deadlineAt: performance.now() + timeoutMs + roomMs }),
             ...(signal ? { signal } : {}),
             ...(call.method !== "GET"
                 ? { idempotencyKey: call.idempotencyKey ?? crypto.randomUUID() }
@@ -251,7 +279,17 @@ export class Transport {
             cause,
         });
     }
-    async #send(call, consume) {
+    /** Sleeps between tries. A call holding a connection slot (`gate`) lends
+     * it out while it sleeps, since a sleep holds no connection, and takes a
+     * slot again before it sends: a thousand creates waiting out a full region
+     * or a 429 would otherwise keep every other call of this client, the stop
+     * that frees room included, queued behind them. */
+    async #rest(ms, signal, gate) {
+        gate?.lend();
+        await sleep(ms, signal);
+        await gate?.take();
+    }
+    async #send(call, consume, gate) {
         let apiKey;
         try {
             call.signal?.throwIfAborted();
@@ -271,6 +309,9 @@ export class Transport {
         const body = call.bytes ?? (call.body === undefined ? undefined : JSON.stringify(call.body));
         const retry = call.retry ?? true;
         let attempt = 0;
+        // An answer that ran nothing is sent again until the call's deadline.
+        const idleUntil = call.deadlineAt ?? performance.now() + NOTHING_RAN_MS;
+        let idleAttempt = 0;
         for (;;) {
             let response;
             let inCallback = false;
@@ -282,13 +323,20 @@ export class Transport {
                 // The API never redirects, so a redirect is refused here exactly as
                 // "error" refused it: thrown, retried, then a connection_error.
                 signal?.throwIfAborted();
-                response = await send(url, {
-                    method: call.method,
-                    headers: this.#headers(call, key, apiKey),
-                    redirect: "manual",
-                    signal,
-                    ...(body === undefined ? {} : { body: body }),
-                });
+                const started = new AbortController();
+                const unanswered = setTimeout(() => started.abort(new DOMException("No answer started.", "TimeoutError")), this.#answerStartMs);
+                try {
+                    response = await send(url, {
+                        method: call.method,
+                        headers: this.#headers(call, key, apiKey),
+                        redirect: "manual",
+                        signal: signal ? AbortSignal.any([signal, started.signal]) : started.signal,
+                        ...(body === undefined ? {} : { body: body }),
+                    });
+                }
+                finally {
+                    clearTimeout(unanswered);
+                }
                 if (response.type === "opaqueredirect" ||
                     (response.status >= 300 && response.status < 400)) {
                     await response.body?.cancel().catch(() => { });
@@ -350,7 +398,23 @@ export class Transport {
                     inCallback = true;
                     call.onCapacityWait?.(error, pause);
                     inCallback = false;
-                    await sleep(pause, signal);
+                    await this.#rest(pause, signal, gate);
+                    continue;
+                }
+                // Nothing ran: safe to send again for any call, past maxRetries,
+                // with growing waits, until the deadline; then this refusal stands.
+                // A late answer's failure came after the work began, so only a
+                // guest's own refusal (`guest_busy`, before anything is journaled)
+                // still says nothing ran.
+                if ([429, 503].includes(status) &&
+                    NOTHING_RAN.has(error.code) &&
+                    (!late || error.code === "guest_busy")) {
+                    const header = Number(response.headers.get("retry-after"));
+                    const base = error.retryAfterMs ?? (Number.isFinite(header) && header > 0 ? header * 1000 : 250);
+                    const pause = Math.min(30_000, base * 2 ** Math.min(idleAttempt++, 3)) * (0.9 + Math.random() * 0.2);
+                    if (pause >= idleUntil - performance.now())
+                        throw error;
+                    await this.#rest(pause, signal, gate);
                     continue;
                 }
                 const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
@@ -359,7 +423,7 @@ export class Transport {
                 const header = Number(response.headers.get("retry-after"));
                 const wait = error.retryAfterMs ??
                     (Number.isFinite(header) && header > 0 ? header * 1000 : backoff(attempt));
-                await sleep(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal);
+                await this.#rest(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal, gate);
             }
             catch (cause) {
                 // Deliberate API refusals and unusable proxy settings cannot be
@@ -373,25 +437,42 @@ export class Transport {
                     throw cause;
                 if (signal?.aborted || !retry || attempt >= this.#maxRetries)
                     throw this.#connectionError(call, cause);
-                await sleep(backoff(attempt), signal).catch((cause) => {
-                    throw this.#connectionError(call, cause);
+                await this.#rest(backoff(attempt), signal, gate).catch((cause) => {
+                    throw cause instanceof RuntimeError ? cause : this.#connectionError(call, cause);
                 });
             }
             attempt++;
         }
     }
+    /** A hold on `kinds` of slot, taken in order and given back together. */
+    #gate(call, kinds) {
+        let held = 0;
+        const lend = () => {
+            while (held > 0)
+                kinds[--held].give();
+        };
+        return {
+            take: async () => {
+                try {
+                    for (; held < kinds.length; held++)
+                        await kinds[held].take(call.signal);
+                }
+                catch (cause) {
+                    lend();
+                    throw this.#connectionError(call, cause);
+                }
+            },
+            lend,
+        };
+    }
     async #queued(call, consume) {
+        const gate = this.#gate(call, [this.#slots]);
+        await gate.take();
         try {
-            await this.#slots.take(call.signal);
-        }
-        catch (cause) {
-            throw this.#connectionError(call, cause);
-        }
-        try {
-            return await this.#send(call, consume);
+            return await this.#send(call, consume, gate);
         }
         finally {
-            this.#slots.give();
+            gate.lend();
         }
     }
     async json(call) {
@@ -426,11 +507,12 @@ export class Transport {
      * errors with `download_incomplete` if it ends short of the length the API
      * promised; it is never retried part way. */
     async fileStream(call) {
-        const response = await this.send(call);
+        const { response, release } = await this.#opened(this.#prepare(call));
         const expected = promisedLength(response.headers);
         const body = response.body ?? new ReadableStream({ start: (c) => c.close() });
         let got = 0;
-        return body.pipeThrough(new TransformStream({
+        const reader = body
+            .pipeThrough(new TransformStream({
             transform(chunk, controller) {
                 got += chunk.byteLength;
                 if (expected !== undefined && got > expected)
@@ -442,13 +524,65 @@ export class Transport {
                 if (expected !== undefined && got !== expected)
                     controller.error(incompleteDownload(got, expected));
             },
-        }));
+        }))
+            .getReader();
+        // The connection is given back when the body ends, fails or is cancelled.
+        return new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { value, done } = await reader.read();
+                    if (done) {
+                        release();
+                        controller.close();
+                    }
+                    else
+                        controller.enqueue(value);
+                }
+                catch (error) {
+                    release();
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) {
+                release();
+                await reader.cancel(reason);
+            },
+        });
+    }
+    /** Sends a call whose answer is a stream, holding a stream slot and a
+     * connection slot from before it is sent until `release`: once its body is
+     * read, failed or cancelled, or its deadline or signal ends it, whichever
+     * comes first, so a stream nobody finishes still gives its slots back at
+     * its deadline. */
+    async #opened(call) {
+        const gate = this.#gate(call, [this.#streams, this.#slots]);
+        await gate.take();
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            call.signal?.removeEventListener("abort", release);
+            gate.lend();
+        };
+        try {
+            const response = await this.#send(call, async (response) => response, gate);
+            if (call.signal?.aborted)
+                release();
+            else
+                call.signal?.addEventListener("abort", release, { once: true });
+            return { response, release };
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
     }
     /** Newline-delimited JSON events, as they arrive. */
     async *events(call) {
-        const response = await this.send({ ...call, accept: "application/x-ndjson" });
+        const { response, release } = await this.#opened(this.#prepare({ ...call, accept: "application/x-ndjson" }));
         if (!response.body)
-            return;
+            return release();
         const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
         let buffer = "";
         try {
@@ -477,6 +611,7 @@ export class Transport {
             // Cleanup must not replace a parse, network or callback error.
             await reader.cancel().catch(() => undefined);
             reader.releaseLock();
+            release();
         }
     }
     /** A WebSocket to an API path, authenticated with the same key. */

package/dist/types.d.ts

@@ -5,6 +5,8 @@ export type SandboxInfo = {
     kind: "sandbox";
     name: string | null;
     labels: Record<string, string>;
+    /** @deprecated Read `state`. An older, coarser name for it, still sent for
+     * older clients. */
     status: "pending" | "active" | "paused" | "stopping" | "stopped";
     state: "starting" | "running" | "pausing" | "paused" | "resuming" | "stopping" | "stopped";
     region: string;
@@ -14,7 +16,10 @@ export type SandboxInfo = {
     diskMiB: number;
     cpu: "shared" | "reserved";
     cpuFloorMillis: number;
+    /** @deprecated Always true for a sandbox created since 5 October 2026:
+     * every sandbox can pause. */
     pausable: boolean;
+    /** Its time limit in seconds; 0 is none: it runs while it works. */
     timeoutSeconds: number;
     /** Pauses after this many idle seconds; 0 is never. */
     idlePauseSeconds?: number;
@@ -23,19 +28,31 @@ export type SandboxInfo = {
     idlePauseUnusedOnly?: boolean;
     /** A request (exec, files, terminal, a visit to a shared port) wakes it when paused. */
     autoWake?: boolean;
-    /** Its lease renews itself while credit lasts, and its disk is kept after a stop. */
+    /** Runs until stopped while credit lasts, never paused for idleness or a
+     * time limit, and its disk is kept after a stop. */
     persistent?: boolean;
     /** The last exec, file, terminal, desktop or preview request, to within a minute. */
     lastActiveAt?: string | null;
     onLeaseEnd: "pause" | "stop";
     createdAt: string;
     readyAt: string | null;
+    /** Paid up to: a time ahead of now that moves on by itself while it runs.
+     * Not when it ends; that is `endsAt`. */
     expiresAt: string;
+    /** When it stops or pauses by itself: its time limit, or where its funding
+     * ends once credit or a spending limit stops its renewal. Null when it
+     * never will, and when it is not running. Absent from older servers. */
+    endsAt?: string | null;
     endedAt: string | null;
+    /** Why it stopped or paused, such as `requested`, `idle` or `time_limit`
+     * (its `timeoutSeconds` ran out). A server before 4 October 2026 sent
+     * `lease_expired` for `time_limit`. */
     stopReason: string | null;
     pausedAt: string | null;
     pausedExpiresAt: string | null;
     chargedMicros: number;
+    /** @deprecated Read `chargedMicros` and `runtime.usage()`. Still sent for
+     * older clients. */
     heldMicros: number;
     simulated?: boolean;
     replayed?: boolean;
@@ -76,25 +93,31 @@ export type CreateSandbox = {
     diskMiB?: number;
     cpu?: "shared" | "reserved";
     cpuFloorMillis?: number;
-    /** How long it may run before its lease ends. Default 1800. */
+    /** A time limit, 60 to 3600 seconds. Leave it out (or 0) for none: the
+     * sandbox runs while it works and pauses when idle, until you stop it or
+     * credit runs out. */
     timeoutSeconds?: number;
+    /** @deprecated Ignored since 5 October 2026: every sandbox can pause. */
     pausable?: boolean;
-    /** What happens when timeoutSeconds runs out: "pause" (default) or "stop". */
+    /** What happens when its time limit or credit runs out: "pause" (default) or "stop". */
     onLeaseEnd?: "pause" | "stop";
     /** Pause after this many seconds in which nothing happens in it: no
      * request, no command or terminal running, no open connection, no network
-     * traffic and no CPU use. Default 60 for a pausable sandbox; 0 never;
+     * traffic and no CPU use. Default 60 unless persistent; 0 never;
      * otherwise 10 to 86400. A request wakes it again. */
     idlePauseSeconds?: number;
     /** A request to a paused sandbox wakes it. Default true. */
     autoWake?: boolean;
-    /** Keep it running while credit lasts (its lease renews itself) and keep its
-     * disk after a stop, for restart(). Paid only. */
+    /** Keep it running until you stop it, while credit lasts, with no idle
+     * pause unless idlePauseSeconds asks for one. Its disk is billed as any
+     * sandbox's, and kept after a stop, for restart(), as any sandbox's is.
+     * Paid only. */
     persistent?: boolean;
     /** The most it may cost over its whole life, in microdollars. */
     maxTotalCostMicros?: number;
     /** With name: return the sandbox that already has the name, woken if paused. */
     getOrCreate?: boolean;
+    /** @deprecated Use `maxTotalCostMicros`. Still accepted for older clients. */
     maxCostMicros?: number;
     /** Network rules from the first start; the same shape as sandbox.network.set.
      * Omit for the public web on ports 80 and 443. */
@@ -197,6 +220,7 @@ export type OutputEvent = {
     error: {
         code: string;
         message: string;
+        status?: number;
         requestId?: string;
     };
 };
@@ -227,6 +251,8 @@ export type Usage = {
     unit: "microdollars";
     credited: string;
     spent: string;
+    /** What running sandboxes and the hour ahead of stored items are about to
+     * use, already taken out of `available`. */
     held: string;
     /** Credit that expired, or grant credit taken back. */
     expired: string;
@@ -237,6 +263,7 @@ export type Usage = {
     trial: {
         totalMs: number;
         usedMs: number;
+        /** @deprecated Read `availableMs`. Still sent for older clients. */
         reservedMs: number;
         availableMs: number;
     } | null;
@@ -253,6 +280,23 @@ export type Usage = {
         /** What the balance or a spending limit could not cover; never charged. */
         writtenOffMicros: string;
     } | null;
+    /** The account's pilot while it serves its sandboxes, a free run agreed
+     * with Runtime: `hours` sandbox-hours of running time, `usedMs` and
+     * `leftMs` of it used and left. Null on every other account. */
+    pilot?: {
+        id: string;
+        sandboxes: number;
+        vcpu: number;
+        memoryMiB: number;
+        diskMiB: number;
+        startsAt: string;
+        endsAt: string;
+        graceEndsAt: string;
+        endedAt: string | null;
+        hours: number;
+        usedMs: number;
+        leftMs: number;
+    } | null;
     resources: Array<Record<string, unknown>>;
     [key: string]: unknown;
 };
@@ -269,7 +313,8 @@ export type SandboxSettings = {
     /** Pause after this many seconds with no activity, counted from now; 0
      * never, otherwise 10 to 86400. */
     idlePauseSeconds?: number;
-    /** Keep it running while credit lasts and keep its disk after a stop. Paid only. */
+    /** Keep it running until you stop it, while credit lasts, and keep its disk
+     * after a stop. Paid only. */
     persistent?: boolean;
     /** Lifetime cap in microdollars; null removes it. */
     maxTotalCostMicros?: number | null;
@@ -288,11 +333,11 @@ export type DeletedSandbox = {
     endedAt: string | null;
     replayed?: boolean;
 };
-/** How `sandbox.keepAlive()` extends the lease. */
+/** How `sandbox.keepAlive()` moves on the time limit of a sandbox that has one. */
 export type KeepAliveOptions = {
     /** How often it checks, in seconds. Default 60. */
     everySeconds?: number;
-    /** How much lease it keeps ahead of now, in seconds (60 to 3600). Default 600. */
+    /** How much of its time limit it keeps ahead of now, in seconds (60 to 3600). Default 600. */
     marginSeconds?: number;
     /** Called with an error an extension met; the loop carries on. */
     onError?: (error: unknown) => void;

package/dist/vercel/filesystem.js

@@ -119,7 +119,9 @@ export class FileSystem {
         const result = await this.#call(syscall, path, () => this.#ctx.run(argv, options));
         if (result.exitCode === 0)
             return result.stdout;
-        if (/No such file or directory/.test(result.stderr))
+        // dash, the sh of Debian and Ubuntu (a Runtime sandbox's), says "cannot
+        // create ...: Directory nonexistent" for a missing parent.
+        if (/No such file or directory|Directory nonexistent/.test(result.stderr))
             throw fsError("ENOENT", syscall, path);
         if (syscall === "unlink" || syscall === "rm")
             throw fsError("EACCES", syscall, path);

package/dist/vercel/sandbox.d.ts

@@ -9,7 +9,9 @@ import { Snapshot } from "./snapshot.js";
  * 2026). Runtime gives 2 vCPU and 4096 MiB. */
 export declare const DEFAULT_VCPUS = 2;
 export declare 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 declare const DEFAULT_TIMEOUT_MS = 300000;
 /** Vercel's working directory; `/workspace` on Runtime. */
 export declare const HOME = "/vercel/sandbox";
@@ -40,9 +42,10 @@ export interface CreateSandboxParams extends Credentials {
     /** Shared at public HTTPS addresses (Runtime previews); `domain(port)`
      * answers from them. */
     ports?: number[];
-    /** Milliseconds. Default 300 000, at least 60 s. Over an hour, the
-     * sandbox's hour-long lease is extended while this object lives, up to the
-     * timeout (`sandbox.timeout`). */
+    /** Milliseconds, at least 60 s: when it stops. Leave it out for no time
+     * limit: it runs while it works and pauses when idle. Over an hour, the
+     * hour-long limit is extended while this object lives, up to the timeout
+     * (`sandbox.timeout`). */
     timeout?: number;
     resources?: {
         vcpus: number;
@@ -135,13 +138,15 @@ export declare class Sandbox {
     get cwd(): string;
     get status(): "pending" | "running" | "stopping" | "stopped";
     /** Milliseconds from the start of the session: the timeout given at
-     * create, with every extension, or the lease of a sandbox found by name. */
+     * 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(): number;
     get expiresAt(): Date;
     get tags(): Record<string, string>;
     get sourceSnapshotId(): string | undefined;
     /** 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 create(params?: CreateSandboxParams): Promise<Sandbox & AsyncDisposable>;
@@ -269,9 +274,10 @@ export declare class Sandbox {
         signal?: AbortSignal;
     }): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
-    /** 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. */
+    /** 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. */
     extendTimeout(duration: number, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -281,7 +287,8 @@ export declare class Sandbox {
     }): Promise<NetworkPolicy>;
     /** 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. */
     update(params: {
         timeout?: number;
         ports?: number[];