withruntime 0.11.0 → 0.11.2

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.11.2";
 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
@@ -45,23 +50,40 @@ export type Call = RequestOptions & {
     retry?: boolean;
     /** How long to keep retrying, with the same key and input, a refusal that
      * clears when a sandbox stops or a host frees room (WAITS_FOR_ROOM): a
-     * full trial, a full quota, a full region. Then the refusal is thrown as
+     * full slots without credit, a full quota, a full region. Then the refusal is thrown as
      * it came. Only a create sets it; 0 or absent fails at once. */
     waitForCapacityMs?: number;
     /** 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,10 +95,16 @@ 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;
+        /** Called each time a call has to wait for one of those connections. */
+        onQueued?: (maxConnections: number) => void;
         /** 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.11.0";
+export const VERSION = "0.11.2";
 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
@@ -107,7 +120,7 @@ function abortReason(signal) {
 }
 /** At most `maximum` holders at once; the rest wait their turn, first come
  * first served. */
-function slots(maximum) {
+function slots(maximum, onWait) {
     let active = 0;
     const waiting = [];
     return {
@@ -117,6 +130,7 @@ function slots(maximum) {
                 active++;
                 return;
             }
+            onWait?.();
             await new Promise((resolve, reject) => {
                 const ready = () => {
                     signal?.removeEventListener("abort", abort);
@@ -141,14 +155,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 +180,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 +200,13 @@ 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);
+        const queued = options.onQueued && (() => options.onQueued(most));
+        this.#slots = slots(most, queued);
+        this.#streams = slots(Math.max(1, most - KEPT_FOR_CALLS), queued);
         this.waitForCapacityMs = Math.max(0, options.waitForCapacityMs ?? 120_000);
     }
     /** The key, found once on first use when it was not given. */
@@ -225,6 +254,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 +281,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 +311,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 +325,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 +400,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 +425,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 +439,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 +509,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 +526,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 +613,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,34 @@ 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";
+    /** What happens when its time limit, credit or a spending limit ends it. */
+    onLeaseEnd: "pause" | "stop" | "delete";
+    /** onLeaseEnd's newer name (0381): the same value. */
+    onTimeout?: "pause" | "stop" | "delete";
     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;
@@ -68,7 +88,7 @@ export type CreateSandbox = {
      * `env`. At most 32 variables and 32 KiB. Values are never shown again;
      * answers list only `envNames`. Copies made by fork() keep them. */
     env?: Record<string, string>;
-    /** Omit to use the free trial while it lasts, then prepaid credit. */
+    /** Omit to use the included usage while it lasts, then prepaid credit. */
     funding?: "trial" | "paid";
     region?: string;
     vcpu?: number;
@@ -76,25 +96,33 @@ 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 86400 seconds (24 hours). 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". */
-    onLeaseEnd?: "pause" | "stop";
+    /** What happens when its time limit, credit or a spending limit ends it:
+     * "pause" (default), "stop", or "delete" (when the time limit runs out,
+     * delete it and its files; credit or a spending limit only stops it). */
+    onLeaseEnd?: "pause" | "stop" | "delete";
     /** 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 +225,7 @@ export type OutputEvent = {
     error: {
         code: string;
         message: string;
+        status?: number;
         requestId?: string;
     };
 };
@@ -227,6 +256,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,12 +265,41 @@ export type Usage = {
     available: string;
     /** The part of spent that refunds and disputes took. */
     takenBack: string;
+    /** Machine time the account can still run without credit, in
+     * milliseconds, or null when it has none. `totalMs` and `usedMs` count free
+     * hours given before 5 October 2026 (0 for an account given none);
+     * `availableMs` is the larger of those hours left and this month's included
+     * usage, as time at 2 vCPU and 4 GiB. The field keeps its older name. */
     trial: {
         totalMs: number;
         usedMs: number;
+        /** @deprecated Read `availableMs`. Still sent for older clients. */
         reservedMs: number;
         availableMs: number;
+        /** `monthly`: the included usage every month only. `hours`: free hours
+         * given before 5 October 2026, kept, beside the included usage. Absent
+         * from an API older than 5 October 2026. */
+        offer?: "monthly" | "hours";
+        /** When the included usage renews: the 1st of next month, 00:00 UTC. */
+        renewsAt?: string;
     } | null;
+    /** What the account uses free this calendar month (UTC), one row per
+     * product, drawn before credit and never charged
+     * (https://withruntime.com/docs/included-usage). */
+    allowances?: Array<{
+        /** machine-memory, machine-cpu, saved-copies or disks. */
+        pool: string;
+        /** GiB-hour, vCPU-hour or GB-month. */
+        unit: string;
+        quantity: number;
+        used: number;
+        /** Held for what is running now; given back unless used. */
+        reserved: number;
+        left: number;
+        /** The month's first day, YYYY-MM-DD. */
+        month: string;
+        renewsAt: string;
+    }>;
     /** Outbound traffic this calendar month, UTC: the first `allowanceBytes` an
      * account sends are free, and the rest is charged at the rate in the pricing
      * guide (https://withruntime.com/docs/pricing#network-products). */
@@ -253,6 +313,35 @@ 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, and `running`, its sandboxes running now:
+     * `leftMs / running` is how long the hours last at this rate. 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;
+        running?: number;
+    } | null;
+    /** Everything this key acts for, a row a kind, past the hundred newest
+     * `resources` lists: how many, and what was charged and is held, in
+     * integer microdollars as strings. Absent from an API before 6 October 2026. */
+    kinds?: Array<{
+        kind: string;
+        resources: number;
+        chargedMicros: string;
+        heldMicros: string;
+    }>;
     resources: Array<Record<string, unknown>>;
     [key: string]: unknown;
 };
@@ -269,7 +358,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 +378,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;