withruntime 0.11.1 → 0.12.0

package/dist/ssh.d.ts

@@ -16,6 +16,6 @@ export declare function sshKey(env: NodeJS.ProcessEnv): Promise<{
 export declare function resolveSandbox(runtime: Runtime, target: string): Promise<Sandbox>;
 export declare function sshConfig(env: NodeJS.ProcessEnv): Promise<string>;
 export declare function sshCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
-/** `runtime sandbox port-forward <id> 5432 8080:3000 ...` */
+/** `runtime sandboxes port-forward <id> 5432 8080:3000 ...` */
 export declare function portForwardCommand(argv: string[], out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
 export {};

package/dist/ssh.js

@@ -6,12 +6,12 @@ import { isAbsolute, join } from "node:path";
 import { RuntimeError } from "./errors.js";
 import { VERSION } from "./transport.js";
 const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
-export const SSH_HELP = (me) => `${me} sandbox ssh <id|name> [-- <command...>]   Log in over SSH (an interactive shell, or run the command)
-${me} sandbox ssh config [--install]          The ssh config for \`ssh <id|name>.runtime\`, also from
+export const SSH_HELP = (me) => `${me} sandboxes ssh <id|name> [-- <command...>]   Log in over SSH (an interactive shell, or run the command)
+${me} sandboxes ssh config [--install]          The ssh config for \`ssh <id|name>.runtime\`, also from
                                       VS Code Remote-SSH and JetBrains Gateway; --install adds
                                       it to ~/.ssh/config
-${me} sandbox ssh proxy <id|name>[.runtime]   ProxyCommand mode: SSH on stdin and stdout
-${me} sandbox port-forward <id|name> <port|local:remote>... [--address 127.0.0.1]
+${me} sandboxes ssh proxy <id|name>[.runtime]   ProxyCommand mode: SSH on stdin and stdout
+${me} sandboxes port-forward <id|name> <port|local:remote>... [--address 127.0.0.1]
                                       Forward local ports to ports in the sandbox, until Ctrl-C
 
 SSH and port forwarding go through Runtime's API with your key: the sandbox opens
@@ -63,7 +63,7 @@ export async function resolveSandbox(runtime, target) {
             : `No live sandbox is named ${name}.`,
         code: page.data.length ? "ambiguous_name" : "sandbox_not_found",
         status: 0,
-        hint: "Use its id: runtime sandbox ls",
+        hint: "Use its id: runtime sandboxes ls",
     });
 }
 const quote = (text) => /^[A-Za-z0-9_./:@=-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
@@ -193,7 +193,7 @@ export async function sshCommand(argv, env, out, connect, me) {
     }
     if (first === "proxy") {
         if (!second)
-            throw usageError(`Give the host: ${me} sandbox ssh proxy <id>.runtime`, me);
+            throw usageError(`Give the host: ${me} sandboxes ssh proxy <id>.runtime`, me);
         return proxy(await connect(), second, await publicKey());
     }
     const runtime = await connect();
@@ -223,7 +223,7 @@ export async function sshCommand(argv, env, out, connect, me) {
             message: `Could not run ssh: ${error.message}`,
             code: "ssh_missing",
             status: 0,
-            hint: "Install OpenSSH, or use `runtime sandbox shell <id>`, which needs nothing.",
+            hint: "Install OpenSSH, or use `runtime sandboxes shell <id>`, which needs nothing.",
         })));
         child.on("exit", (code) => resolve(code ?? 255));
     });
@@ -233,10 +233,10 @@ function usageError(message, me) {
         message,
         code: "usage",
         status: 0,
-        hint: `Run \`${me} sandbox ssh help\`.`,
+        hint: `Run \`${me} sandboxes ssh help\`.`,
     });
 }
-/** `runtime sandbox port-forward <id> 5432 8080:3000 ...` */
+/** `runtime sandboxes port-forward <id> 5432 8080:3000 ...` */
 export async function portForwardCommand(argv, out, connect, me) {
     const at = argv.indexOf("--address");
     const address = at === -1 ? "127.0.0.1" : argv[at + 1];
@@ -244,10 +244,10 @@ export async function portForwardCommand(argv, out, connect, me) {
     const [target, ...specs] = positional;
     if (!target || !specs.length || !address)
         throw new RuntimeError({
-            message: `Give a sandbox and at least one port: ${me} sandbox port-forward <id> 5432 8080:3000`,
+            message: `Give a sandbox and at least one port: ${me} sandboxes port-forward <id> 5432 8080:3000`,
             code: "usage",
             status: 0,
-            hint: `Run \`${me} sandbox ssh help\`.`,
+            hint: `Run \`${me} sandboxes ssh help\`.`,
         });
     const ports = specs.map((spec) => {
         const match = /^(?:(\d{1,5}):)?(\d{1,5})$/.exec(spec);

package/dist/terminal.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Text that came from someone else's program, made safe to print on a
+ * terminal: log lines, labels, anything a customer's code wrote. Printed raw,
+ * an escape sequence in it could clear or rewrite the screen, set the
+ * clipboard (OSC 52), forge a link (OSC 8) or reorder what is read (Unicode
+ * direction overrides). Each such character is shown as its \uXXXX escape
+ * instead, so nothing is hidden and nothing acts. Tab stays; a newline inside
+ * one value is escaped too, so a line on screen is always one value.
+ *
+ * Only for a terminal: a pipe or a file gets the bytes as they are.
+ */
+export declare function terminalSafe(text: string): string;
+/** As {@link terminalSafe}, for a stream of lines: its newlines stay. */
+export declare function terminalSafeLines(text: string): string;
+/**
+ * Writes a log stream (a sandbox process's, an image build's, a job run's) to
+ * `to`: escaped on a terminal, as written to a pipe or a file, or with `raw`.
+ * Not for `exec` or an attached process, whose output is the customer's own
+ * terminal session.
+ */
+export declare function logStream(to: {
+    isTTY?: boolean;
+    write(text: string): unknown;
+}, raw: boolean): (text: string) => void;

package/dist/terminal.js

@@ -0,0 +1,32 @@
+/**
+ * Text that came from someone else's program, made safe to print on a
+ * terminal: log lines, labels, anything a customer's code wrote. Printed raw,
+ * an escape sequence in it could clear or rewrite the screen, set the
+ * clipboard (OSC 52), forge a link (OSC 8) or reorder what is read (Unicode
+ * direction overrides). Each such character is shown as its \uXXXX escape
+ * instead, so nothing is hidden and nothing acts. Tab stays; a newline inside
+ * one value is escaped too, so a line on screen is always one value.
+ *
+ * Only for a terminal: a pipe or a file gets the bytes as they are.
+ */
+export function terminalSafe(text) {
+    return text.replace(UNSAFE, escaped);
+}
+/** As {@link terminalSafe}, for a stream of lines: its newlines stay. */
+export function terminalSafeLines(text) {
+    return text.replace(UNSAFE_BUT_NEWLINE, escaped);
+}
+/**
+ * Writes a log stream (a sandbox process's, an image build's, a job run's) to
+ * `to`: escaped on a terminal, as written to a pipe or a file, or with `raw`.
+ * Not for `exec` or an attached process, whose output is the customer's own
+ * terminal session.
+ */
+export function logStream(to, raw) {
+    return (text) => void to.write(to.isTTY && !raw ? terminalSafeLines(text) : text);
+}
+const escaped = (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`;
+// C0 but tab, DEL, C1, and the Unicode marks and overrides that reorder text.
+const CONTROLS = String.raw `\x00-\x08\x0b-\x1f\x7f-\x9f؜‎‏‪-‮⁦-⁩`;
+const UNSAFE = new RegExp(String.raw `[\n${CONTROLS}]`, "g");
+const UNSAFE_BUT_NEWLINE = new RegExp(`[${CONTROLS}]`, "g");

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.11.1";
+export declare const VERSION = "0.12.0";
 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
@@ -50,7 +50,7 @@ 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
@@ -84,6 +84,13 @@ export declare const DEFAULT_MAX_CONNECTIONS = 48;
  * 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. */
+/** AbortSignal.timeout in whole milliseconds, rounded up, never under 1.
+ * Node throws ERR_OUT_OF_RANGE on a fraction (Bun accepts one), so a
+ * customer's timeoutMs of 1500.5 would be a RangeError instead of a request;
+ * the live promise probe broke this way on 9 October 2026 (d3cd4bfbd). Every
+ * deadline the SDK makes from a customer's or a computed value goes through
+ * this. */
+export declare function timeoutSignal(ms: number): AbortSignal;
 export declare class Transport {
     #private;
     readonly baseUrl: string;
@@ -103,6 +110,8 @@ export declare class Transport {
         /** 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;
     });
@@ -126,7 +135,14 @@ export declare class Transport {
     /** A WebSocket to an API path, authenticated with the same key. */
     websocket(path: string, query?: Query): Promise<WebSocket>;
 }
+/** CLOUD.md section 4: a call under a renamed product word is answered with a
+ * Warning naming the new word. It is printed once per process, to stderr, so
+ * a loop does not drown its own output and stdout stays the caller's. */
+export declare function sayRenamed(header: string | null, say?: (line: string) => void): void;
 /** A download that ended short of (or past) the length the API promised. */
 export declare function incompleteDownload(got: number, expected: number): RuntimeError;
 /** No key given, none in RUNTIME_API_KEY, and none saved by `runtime login`. */
 export declare function missingKey(): RuntimeError;
+/** Whether a fetch failure is a connection that never opened: its code, or
+ * one of its causes', says so. A timeout or a reset never counts. */
+export declare function neverSent(cause: unknown): boolean;

package/dist/transport.js

@@ -1,6 +1,7 @@
 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.1";
+import { warningText } from "./product-renames.js";
+export const VERSION = "0.12.0";
 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
@@ -120,7 +121,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 {
@@ -130,6 +131,7 @@ function slots(maximum) {
                 active++;
                 return;
             }
+            onWait?.();
             await new Promise((resolve, reject) => {
                 const ready = () => {
                     signal?.removeEventListener("abort", abort);
@@ -171,6 +173,15 @@ const KEPT_FOR_CALLS = 8;
  * 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. */
+/** AbortSignal.timeout in whole milliseconds, rounded up, never under 1.
+ * Node throws ERR_OUT_OF_RANGE on a fraction (Bun accepts one), so a
+ * customer's timeoutMs of 1500.5 would be a RangeError instead of a request;
+ * the live promise probe broke this way on 9 October 2026 (d3cd4bfbd). Every
+ * deadline the SDK makes from a customer's or a computed value goes through
+ * this. */
+export function timeoutSignal(ms) {
+    return AbortSignal.timeout(Math.max(1, Math.ceil(ms)));
+}
 export class Transport {
     baseUrl;
     #apiKey;
@@ -203,8 +214,9 @@ export class Transport {
         this.#maxRetries = options.maxRetries ?? 4;
         this.#client = options.client ?? `sdk-js/${VERSION}`;
         const most = Math.max(1, options.maxConnections ?? DEFAULT_MAX_CONNECTIONS);
-        this.#slots = slots(most);
-        this.#streams = slots(Math.max(1, most - KEPT_FOR_CALLS));
+        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. */
@@ -243,7 +255,7 @@ export class Transport {
     #prepare(call) {
         const timeoutMs = call.timeoutMs ?? this.#timeoutMs;
         const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
-        const deadline = timeoutMs === 0 ? undefined : AbortSignal.timeout(timeoutMs + roomMs);
+        const deadline = timeoutMs === 0 ? undefined : timeoutSignal(timeoutMs + roomMs);
         const signal = deadline
             ? call.signal
                 ? AbortSignal.any([call.signal, deadline])
@@ -312,6 +324,8 @@ export class Transport {
         // 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;
+        // The last try never left, and was sent again at once.
+        let resentAtOnce = false;
         for (;;) {
             let response;
             let inCallback = false;
@@ -342,6 +356,7 @@ export class Transport {
                     await response.body?.cancel().catch(() => { });
                     throw new TypeError(`fetch failed: Runtime answered a redirect (${response.status}).`);
                 }
+                sayRenamed(response.headers.get("warning"));
                 /* An answer that took longer than the API holds its headers (90 s)
                  comes as a 200 sent early, and then its JSON: the answer, or
                  {"error": ...} when the work failed after the status went
@@ -437,7 +452,14 @@ export class Transport {
                     throw cause;
                 if (signal?.aborted || !retry || attempt >= this.#maxRetries)
                     throw this.#connectionError(call, cause);
-                await this.#rest(backoff(attempt), signal, gate).catch((cause) => {
+                // A connection that never opened sent no byte of the request, so
+                // the next try, which may reach another server, goes at once; once
+                // in a row, so an API that is down is not hammered. Anything that
+                // may have reached a server (a reset, a timeout, a cut answer)
+                // keeps the backoff and its key's rules.
+                const atOnce = response === undefined && neverSent(cause) && !resentAtOnce;
+                resentAtOnce = atOnce;
+                await this.#rest(atOnce ? Math.random() * 50 : backoff(attempt), signal, gate).catch((cause) => {
                     throw cause instanceof RuntimeError ? cause : this.#connectionError(call, cause);
                 });
             }
@@ -626,6 +648,17 @@ export class Transport {
 }
 /** The status a late answer's body failed with, or undefined when it is an
  * answer. The body is the error the API would have sent as its status. */
+const said = new Set();
+/** CLOUD.md section 4: a call under a renamed product word is answered with a
+ * Warning naming the new word. It is printed once per process, to stderr, so
+ * a loop does not drown its own output and stdout stays the caller's. */
+export function sayRenamed(header, say = console.warn) {
+    const text = warningText(header);
+    if (text === undefined || said.has(text))
+        return;
+    said.add(text);
+    say(`Runtime: ${text}`);
+}
 function lateFailure(text) {
     let body;
     try {
@@ -686,6 +719,28 @@ export function missingKey() {
         hint: "Run `npx -y withruntime login` (a browser approval; nothing to copy), set RUNTIME_API_KEY to a key from https://withruntime.com/account/keys, or pass { apiKey }.",
     });
 }
+/** Error codes of a connection that never opened (Node's and Bun's), so no
+ * byte of the request left this machine. */
+const NEVER_OPENED = new Set([
+    "ECONNREFUSED",
+    "ENOENT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EADDRNOTAVAIL",
+    "ConnectionRefused",
+    "FailedToOpenSocket",
+]);
+/** Whether a fetch failure is a connection that never opened: its code, or
+ * one of its causes', says so. A timeout or a reset never counts. */
+export function neverSent(cause) {
+    for (let at = cause, depth = 0; at && depth < 5; depth++) {
+        const code = at.code;
+        if (typeof code === "string" && NEVER_OPENED.has(code))
+            return true;
+        at = at.cause;
+    }
+    return false;
+}
 function backoff(attempt) {
     return Math.min(8000, 250 * 2 ** attempt) * (0.5 + Math.random());
 }

package/dist/tunnel.js

@@ -222,7 +222,7 @@ export class Tunnel {
                         message: `Nothing is listening on port ${port} in the sandbox.`,
                         code: "port_closed",
                         status: 0,
-                        hint: "Start the server with spawn (`runtime sandbox spawn <id> -- <command>`, sbx.spawn()), which keeps it running: a process started by exec ends with its command. Let it listen on 127.0.0.1, ::1 or every address.",
+                        hint: "Start the server with spawn (`runtime sandboxes spawn <id> -- <command>`, sbx.spawn()), which keeps it running: a process started by exec ends with its command. Let it listen on 127.0.0.1, ::1 or every address.",
                     })
                     : error.message === "reserved"
                         ? new RuntimeError({

package/dist/types.d.ts

@@ -33,7 +33,10 @@ export type SandboxInfo = {
     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.
@@ -79,13 +82,17 @@ export type SandboxInfo = {
 };
 export type CreateSandbox = {
     name?: string;
+    /** What the end of an `await using` block does to it. By default the
+     * block deletes it; `keep: true` stops it instead, which keeps its disk
+     * (billed while it is kept). Not sent to the API. */
+    keep?: boolean;
     labels?: Record<string, string>;
     /** Environment variables for every command, process, terminal, SSH session
      * and the image's start command in this sandbox, under each command's own
      * `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;
@@ -93,14 +100,16 @@ export type CreateSandbox = {
     diskMiB?: number;
     cpu?: "shared" | "reserved";
     cpuFloorMillis?: number;
-    /** 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. */
+    /** 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 its time limit or credit 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 unless persistent; 0 never;
@@ -148,6 +157,18 @@ export type CreateSandbox = {
         tags?: string[];
     };
 };
+/** Present on a command the sandbox's out-of-memory killer ended (the
+ * program, or anything it started): a bare exit -9, or 137 from a shell,
+ * does not say why. */
+export type OutOfMemory = {
+    code: "out_of_memory";
+    processesKilled: number;
+    /** The sandbox's memory size; null if it could not be read. */
+    memoryMiB: number | null;
+    message: string;
+    /** What to do: a larger memoryMiB, or a program that uses less. */
+    hint: string;
+};
 export type CommandResult = {
     exitCode: number | null;
     stdout: string;
@@ -158,6 +179,7 @@ export type CommandResult = {
     durationMs?: number | null;
     processId?: string;
     replayed?: boolean;
+    outOfMemory?: OutOfMemory;
 };
 export type ExecOptions = {
     cwd?: string;
@@ -191,6 +213,7 @@ export type ProcessInfo = {
     timeoutMs: number | null;
     outputBytes: number;
     firstOffset: number;
+    outOfMemory?: OutOfMemory;
 };
 export type OutputEvent = {
     type: "start";
@@ -207,6 +230,7 @@ export type OutputEvent = {
     state: string;
     timedOut: boolean;
     durationMs?: number;
+    outOfMemory?: OutOfMemory;
 } | {
     type: "truncated";
     droppedBytes: number;
@@ -260,13 +284,85 @@ 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;
+    }>;
+    /** What Runtime for Startups includes (https://withruntime.com/startups).
+     * Startup hours are given once, used after this month's included usage
+     * and before credit, never renewed, and gone after 12 months. Storage is
+     * GB kept free each month for those 12 months. Empty unless the account
+     * was accepted to the program or given it; absent from an older API. */
+    startupIncluded?: Array<{
+        /** machine-cpu, machine-memory, saved-copies (snapshots, images and
+         * backups) or disks (volumes). */
+        pool: string;
+        /** vCPU-hour or GiB-hour for startup hours given `once`, GB for `month` storage. */
+        unit: string;
+        /** `once`: given once and used up by what runs. `month`: `quantity` GB
+         * added to each month's included storage until `expiresAt`, never used
+         * up; storage past it bills at the published rate. Absent from an API
+         * before startup storage (7 October 2026): `once`. */
+        period?: "once" | "month";
+        quantity: number;
+        /** Null for monthly storage. */
+        used: number | null;
+        /** Held for what is running now; given back unless used. Null for
+         * monthly storage. */
+        reserved: number | null;
+        /** Null for monthly storage. */
+        left: number | null;
+        /** Storage GB kept now; null for startup hours given `once`. */
+        keptGB?: number | null;
+        /** `startup`. */
+        source: string;
+        grantedAt: string;
+        /** 12 months after `grantedAt`: what is left then is gone. */
+        expiresAt?: string;
+    }>;
+    /** What Runtime for Startups includes at once for its 12 months:
+     * image builds, and sandboxes (past it, a create answers quota_exceeded).
+     * Null without one or after them, when the account's own limits apply;
+     * absent from an API older than 7 October 2026. */
+    startupLimits?: {
+        buildsAtOnce: number;
+        sandboxesAtOnce: number;
     } | null;
+    /** @deprecated Renamed `startupIncluded`; works for 30 days after the rename, with a warning. */
+    readonly pot?: Usage["startupIncluded"];
+    /** @deprecated Renamed `startupLimits`; works for 30 days after the rename, with a warning. */
+    readonly potLimits?: Usage["startupLimits"];
     /** 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). */
@@ -282,7 +378,9 @@ export type Usage = {
     } | 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. */
+     * `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;
@@ -296,7 +394,17 @@ export type Usage = {
         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;
 };

package/dist/vercel/sandbox.d.ts

@@ -147,8 +147,7 @@ export declare class Sandbox {
     /** Creates a sandbox and waits until it runs. Vercel's defaults: 2 vCPUs,
      * 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. */
+     * Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
     static create(params?: CreateSandboxParams): Promise<Sandbox & AsyncDisposable>;
     /** A sandbox by name (or Runtime id), woken if it is paused unless
      * `resume: false`. */

package/dist/vercel/sandbox.js

@@ -2,7 +2,7 @@ import { extensionSeconds, LeaseKeeper, LEASE_MAX_SECONDS } from "../compat/leas
 import { RuntimeError } from "../errors.js";
 import { clientFor, signalOf, } from "./client.js";
 import { Command, CommandFinished, exitCodeOf } from "./command.js";
-import { APIError, guard, NotSupportedError, translate } from "./errors.js";
+import { APIError, guard, NotSupportedError, StreamError, translate } from "./errors.js";
 import { FileSystem } from "./filesystem.js";
 import { rootOrThrow, SandboxUser, SandboxUserAlreadyExistsError, validateName, } from "./sandbox-user.js";
 import { Snapshot } from "./snapshot.js";
@@ -105,7 +105,7 @@ async function resolveImage(client, params) {
     const found = page.data[0];
     if (found)
         return { image: found.id };
-    throw new NotSupportedError(`The image ${image}, which is not a Runtime image`, `Build it as a Runtime image with that name and this call starts from it: \`npx withruntime image build --dockerfile Dockerfile --name ${image}\`, or runtime.images.build({ name: "${image}", image: "<registry reference>" }).`);
+    throw new NotSupportedError(`The image ${image}, which is not a Runtime image`, `Build it as a Runtime image with that name and this call starts from it: \`npx withruntime images build --dockerfile Dockerfile --name ${image}\`, or runtime.images.build({ name: "${image}", image: "<registry reference>" }).`);
 }
 /** Runtime's state as Vercel's status: a paused sandbox is a stopped
  * persistent one. */
@@ -260,8 +260,7 @@ export class Sandbox {
     /** Creates a sandbox and waits until it runs. Vercel's defaults: 2 vCPUs,
      * 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. */
+     * Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
     static async create(params = {}) {
         refuseCreate(params);
         const client = clientFor(params);
@@ -521,6 +520,8 @@ export class Sandbox {
             onStdout: record("stdout", params.stdout),
             onStderr: record("stderr", params.stderr),
         }), params);
+        if (result.stdoutTruncated || result.stderrTruncated)
+            throw new StreamError("output_truncated", "Some command output is no longer available.", result.processId ?? this.#rt.id);
         return new CommandFinished({
             id: result.processId ?? `cmd_${startedAt}`,
             cwd: vercelCwd,
@@ -776,7 +777,7 @@ export class Sandbox {
      * Runtime's terminal opens with the account key, which must not leave the
      * server. */
     openInteractive() {
-        return Promise.reject(new NotSupportedError("Vercel's interactive shell (openInteractive)", "Use `await sandbox.withruntime.terminal({ cols, rows, onData })`, or `npx withruntime sandbox shell <id>`."));
+        return Promise.reject(new NotSupportedError("Vercel's interactive shell (openInteractive)", "Use `await sandbox.withruntime.terminal({ cols, rows, onData })`, or `npx withruntime sandboxes shell <id>`."));
     }
     /** The user commands run as, `runtime`, and its group. */
     getDefaultUser(_opts = {}) {

package/dist/vercel/snapshot.js

@@ -7,6 +7,14 @@ function statusOf(state) {
         return "deleted";
     return "created";
 }
+/** Vercel's snapshots always expire. Runtime's has no end date while it is kept
+ * for as long as the account has credit; it is then taken at the longest a
+ * snapshot is kept, a year from when it was made. */
+function expiresAtOf(snapshot) {
+    return snapshot.expiresAt === null
+        ? Date.parse(snapshot.createdAt) + 365 * 86_400_000
+        : Date.parse(snapshot.expiresAt);
+}
 function metadataOf(snapshot) {
     return {
         id: snapshot.id,
@@ -17,7 +25,7 @@ function metadataOf(snapshot) {
         sizeBytes: snapshot.storedBytes ?? 0,
         createdAt: Date.parse(snapshot.createdAt),
         updatedAt: Date.parse(snapshot.readyAt ?? snapshot.createdAt),
-        expiresAt: Date.parse(snapshot.expiresAt),
+        expiresAt: expiresAtOf(snapshot),
     };
 }
 /** A saved filesystem, as Vercel's Snapshot, over a Runtime disk snapshot.
@@ -52,7 +60,7 @@ export class Snapshot {
         return new Date(this.#snapshot.readyAt ?? this.#snapshot.createdAt);
     }
     get expiresAt() {
-        return new Date(this.#snapshot.expiresAt);
+        return new Date(expiresAtOf(this.#snapshot));
     }
     static async get(params) {
         const client = clientFor(params);

package/dist/volumes/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/volumes`: Volumes alone. Persistent disks to attach to sandboxes.
+ *
+ *   import { volumes } from "withruntime/volumes";
+ *   const client = volumes(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/volumes.js";
+/** `runtime.volumes` of a client made with `options`. */
+export declare function volumes(options?: RuntimeOptions): Runtime["volumes"];