withruntime 0.11.2 → 0.14.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.2";
+export declare const VERSION = "0.14.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
@@ -7,6 +7,9 @@ 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";
+/** How a Runtime secret's placeholder starts, the value a sandbox sees in its
+ * place (packages/cloud-guide/docs/security.md). */
+export declare const PLACEHOLDER = "rtsec_";
 /** 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: {
@@ -84,6 +87,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;
@@ -128,7 +138,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.2";
+import { warningText } from "./product-renames.js";
+export const VERSION = "0.14.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
@@ -8,6 +9,9 @@ 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";
+/** How a Runtime secret's placeholder starts, the value a sandbox sees in its
+ * place (packages/cloud-guide/docs/security.md). */
+export const PLACEHOLDER = "rtsec_";
 /** 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" };
@@ -172,6 +176,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;
@@ -194,7 +207,13 @@ export class Transport {
             throw missingKey();
         else
             this.#apiKey = options.apiKey;
-        this.baseUrl = apiOrigin(options.baseUrl ? reachable(options.baseUrl) : defaultBaseUrl());
+        // A secret's placeholder becomes the key only on its way out through the
+        // sandbox's proxy; runtime.internal goes to the host without it, so the
+        // API sees the placeholder and answers 401 (land-lander, 11 October 2026:
+        // every worker's `check --remote`). Such a key's calls take the public API.
+        const placeholder = this.#apiKey?.startsWith(PLACEHOLDER) === true;
+        const origin = options.baseUrl || processEnv().RUNTIME_API_URL || DEFAULT_BASE_URL;
+        this.baseUrl = apiOrigin(placeholder ? origin : reachable(origin));
         // The environment's proxy (HTTPS_PROXY, NO_PROXY) on Node and Bun alike;
         // a fetch passed in is used as it is.
         this.#fetch = options.fetch ?? envFetch;
@@ -245,7 +264,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])
@@ -291,6 +310,18 @@ export class Transport {
         await sleep(ms, signal);
         await gate?.take();
     }
+    /** Wait before sending a refused call again. When the call's deadline
+     * ends the wait, the refusal stands: on a loaded machine bun can fire
+     * AbortSignal.timeout before a shorter setTimeout, and the call then
+     * failed as a timeout although the transport had judged the wait to fit
+     * (11 October 2026). A caller's own cancel still ends it as a cancel. */
+    async #retryAfter(refusal, ms, signal, gate) {
+        await this.#rest(ms, signal, gate).catch((cause) => {
+            throw signal?.reason?.name === "TimeoutError"
+                ? refusal
+                : cause;
+        });
+    }
     async #send(call, consume, gate) {
         let apiKey;
         try {
@@ -314,6 +345,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;
@@ -344,6 +377,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
@@ -400,7 +434,7 @@ export class Transport {
                     inCallback = true;
                     call.onCapacityWait?.(error, pause);
                     inCallback = false;
-                    await this.#rest(pause, signal, gate);
+                    await this.#retryAfter(error, pause, signal, gate);
                     continue;
                 }
                 // Nothing ran: safe to send again for any call, past maxRetries,
@@ -416,7 +450,7 @@ export class Transport {
                     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);
+                    await this.#retryAfter(error, pause, signal, gate);
                     continue;
                 }
                 const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
@@ -439,7 +473,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);
                 });
             }
@@ -628,6 +669,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 {
@@ -688,6 +740,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

@@ -82,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 included usage while it lasts, then prepaid credit. */
+    /** Omit to use the free usage while it lasts, then prepaid credit. */
     funding?: "trial" | "paid";
     region?: string;
     vcpu?: number;
@@ -153,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;
@@ -163,6 +179,7 @@ export type CommandResult = {
     durationMs?: number | null;
     processId?: string;
     replayed?: boolean;
+    outOfMemory?: OutOfMemory;
 };
 export type ExecOptions = {
     cwd?: string;
@@ -196,6 +213,7 @@ export type ProcessInfo = {
     timeoutMs: number | null;
     outputBytes: number;
     firstOffset: number;
+    outOfMemory?: OutOfMemory;
 };
 export type OutputEvent = {
     type: "start";
@@ -212,6 +230,7 @@ export type OutputEvent = {
     state: string;
     timedOut: boolean;
     durationMs?: number;
+    outOfMemory?: OutOfMemory;
 } | {
     type: "truncated";
     droppedBytes: number;
@@ -276,11 +295,11 @@ export type Usage = {
         /** @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
+        /** `monthly`: the free usage every month only. `hours`: free hours
+         * given before 5 October 2026, kept, beside the free 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. */
+        /** When the free 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
@@ -299,7 +318,55 @@ export type Usage = {
         /** The month's first day, YYYY-MM-DD. */
         month: string;
         renewsAt: string;
+        /** When the free machine time ends for an account that has never paid
+         * (30 days after it opened); null once it has paid, when it renews
+         * every month. Absent from an API older than 14 October 2026. */
+        freeUntil?: string | null;
+    }>;
+    /** What Runtime for Startups includes (https://withruntime.com/startups).
+     * Startup hours are given once, used after this month's free 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). */

package/dist/vercel/sandbox.d.ts

@@ -147,7 +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 included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * Runtime: the free 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,7 +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 included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     static async create(params = {}) {
         refuseCreate(params);
         const client = clientFor(params);
@@ -520,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,
@@ -775,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"];

package/dist/volumes/index.js

@@ -0,0 +1,10 @@
+/** `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 } from "../client.js";
+/** `runtime.volumes` of a client made with `options`. */
+export function volumes(options) {
+    return new Runtime(options).volumes;
+}

package/dist/wallet.d.ts

@@ -17,8 +17,11 @@ export type WalletClaim = {
     status: Exclude<Topup["status"], "paid">;
     orgId: string;
     topup: Topup | null;
+    /** What to do now, such as sending the top-up again when it has no address. */
+    next?: string;
 };
-/** Opens an account and a stablecoin top-up of `usd` dollars ($10 to $10,000).
+/** Opens an account and a stablecoin top-up of `usd` dollars ($10 to $500,
+ *  a new account's first week).
  *  `acceptTerms` must be true: opening one means agreeing to
  *  https://withruntime.com/legal/terms, so ask the person you work for first. */
 export declare function openWalletAccount(input: {

package/dist/wallet.js

@@ -33,7 +33,8 @@ async function post(options, path, body) {
         });
     return [response.status, answer];
 }
-/** Opens an account and a stablecoin top-up of `usd` dollars ($10 to $10,000).
+/** Opens an account and a stablecoin top-up of `usd` dollars ($10 to $500,
+ *  a new account's first week).
  *  `acceptTerms` must be true: opening one means agreeing to
  *  https://withruntime.com/legal/terms, so ask the person you work for first. */
 export async function openWalletAccount(input, options = {}) {