withruntime 0.10.0 → 0.11.1

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.11.1";
 export declare 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
@@ -7,6 +7,11 @@ export declare 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 declare const SANDBOX_BASE_URL = "http://runtime.internal";
+/** 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 declare const sandboxMarker: {
+    path: string;
+};
 /** True in a Runtime sandbox. Node and Bun only; a browser is never one. */
 export declare function inRuntimeSandbox(marker?: string): boolean;
 /** Where calls go when no base URL is given: RUNTIME_API_URL, then Runtime's
@@ -51,17 +56,34 @@ export type Call = RequestOptions & {
     /** Called each time a call waits for room, with the refusal it is waiting
      * out and how long it will sleep before sending the call again. */
     onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
+    /** Internal: when the call's own deadline ends (performance.now()), set
+     * once the call is prepared; absent when it has none. */
+    deadlineAt?: number;
 };
+/** 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 declare const ANSWER_START_MS = 125000;
 export declare function apiOrigin(value: string): string;
 export declare function encodeQuery(query: Query | undefined): string;
+/** 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 declare const DEFAULT_MAX_CONNECTIONS = 48;
 /** 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 declare class Transport {
     #private;
     readonly baseUrl: string;
@@ -73,9 +95,13 @@ export declare class Transport {
         baseUrl?: string;
         fetch?: typeof fetch;
         timeoutMs?: number;
+        /** How long one attempt waits for its answer to start before it is sent
+         * again under the same key. Default ANSWER_START_MS. */
+        answerStartMs?: number;
         maxRetries?: number;
         client?: string;
-        /** Calls read whole that may be in flight at once. Default 32. */
+        /** Connections held at once, answers and streams together; the rest
+         * wait their turn. Default 48: one address may hold 64 to the API. */
         maxConnections?: number;
         /** How long a create waits for room. Default 120 000; 0 fails at once. */
         waitForCapacityMs?: number;

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.10.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,27 +28,40 @@ 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;
     /** The names of its own environment variables (`env`), on a create, an
      * update and a read of one sandbox. Values are never shown. */
     envNames?: string[];
-    /** On a create from an image with a start command: whether it started,
-     * became ready (readyMs), timed out, or exited first. The create's answer
+    /** On a create from an image with a start command: whether it started
+     * (and was still running half a second later), became ready (readyMs),
+     * timed out, or exited first (exitCode, and stderr's last lines). The create's answer
      * alone carries it, and the Sandbox that create returned keeps it through
      * later reads; `sandboxes.get` and `list` have none, because the API keeps
      * no record of it. */
@@ -52,6 +70,8 @@ export type SandboxInfo = {
         processId?: string;
         exitCode?: number | null;
         readyMs?: number;
+        /** With exited: the last lines the start command wrote to stderr. */
+        stderr?: string;
     };
     /** Present and true when getOrCreate answered a sandbox that already held the name. */
     reused?: boolean;
@@ -73,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. */
@@ -194,6 +220,7 @@ export type OutputEvent = {
     error: {
         code: string;
         message: string;
+        status?: number;
         requestId?: string;
     };
 };
@@ -224,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;
@@ -234,6 +263,7 @@ export type Usage = {
     trial: {
         totalMs: number;
         usedMs: number;
+        /** @deprecated Read `availableMs`. Still sent for older clients. */
         reservedMs: number;
         availableMs: number;
     } | null;
@@ -250,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;
 };
@@ -266,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;
@@ -285,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/index.d.ts

@@ -1,6 +1,7 @@
 export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, type CreateSandboxParams, type RunCommandParams, type NetworkPolicy, type SandboxRoute, } from "./sandbox.js";
 export { Command, CommandFinished, type CommandOutput, type LogOutputLine, type Signal, } from "./command.js";
 export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
 export { Snapshot } from "./snapshot.js";
 export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
 export type { Credentials, WithRuntime } from "./client.js";
@@ -16,13 +17,6 @@ export declare const Session: {
     new (...args: unknown[]): never;
     readonly [key: string]: (...args: unknown[]) => never;
 };
-export declare const SandboxUser: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
-export declare class SandboxUserAlreadyExistsError extends Error {
-}
 export declare const defineSandboxProxy: {
     (...args: unknown[]): never;
     new (...args: unknown[]): never;

package/dist/vercel/index.js

@@ -9,6 +9,7 @@ import { NotSupportedError } from "./errors.js";
 export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, } from "./sandbox.js";
 export { Command, CommandFinished, } from "./command.js";
 export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
 export { Snapshot } from "./snapshot.js";
 export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
 /** Vercel's default region; Runtime runs in one US region. */
@@ -32,7 +33,4 @@ function unsupportedExport(name, alternative) {
 }
 export const Drive = unsupportedExport("Drive", "Use a Runtime volume (runtime.volumes) and mount it with withruntime: { create: { volumes: [{ volumeId, path }] } }.");
 export const Session = unsupportedExport("Session", "A Runtime sandbox is its own session: call the methods on the sandbox.");
-export const SandboxUser = unsupportedExport("SandboxUser", "Commands run as the sandbox owner with passwordless sudo; create users with `sudo useradd` in runCommand.");
-export class SandboxUserAlreadyExistsError extends Error {
-}
 export const defineSandboxProxy = unsupportedExport("sandbox proxy (defineSandboxProxy)", "Share a port with sandbox.withruntime.previews.create(port) instead.");