withruntime 0.14.0 → 0.16.0

package/dist/products/limits.d.ts

@@ -18,9 +18,23 @@ export type KeyLimits = {
     /** Machine time the account can still run without credit, the same
      * figures as `usage.get()`'s `trial`, or null when it has none. */
     trial: Usage["trial"];
+    /** Every limit the account is held to, with what it uses of each now: the
+     * numbers a create past one is refused `quota_exceeded` by (its
+     * `details.limit` names the row). Null when they can't be read. */
+    account: AccountLimit[] | null;
 };
-/** `runtime.limits.get()`: whether this key is read-only, and what its agent
- * may still spend today. An owner sets the limit at
+/** One of the account's limits, as https://withruntime.com/account/limits shows it. */
+export type AccountLimit = {
+    /** `<kind>.<dimension>`: sandbox.count, sandbox.vcpu, sandbox.memory_mib, volume.count… */
+    limit: string;
+    label: string;
+    /** What `max` and `used` count: things, or MiB. */
+    unit: "count" | "mib";
+    max: number;
+    used: number;
+};
+/** `runtime.limits.get()`: whether this key is read-only, what its agent
+ * may still spend today, and the account's limits with what it uses of each. An owner sets the limit at
  * https://withruntime.com/account/keys; a key can read it, never change it.
  * Past it, a create, wake, extension or renewal fails with
  * `spending_limit_reached` (HTTP 402). */

package/dist/products/limits.js

@@ -1,5 +1,5 @@
-/** `runtime.limits.get()`: whether this key is read-only, and what its agent
- * may still spend today. An owner sets the limit at
+/** `runtime.limits.get()`: whether this key is read-only, what its agent
+ * may still spend today, and the account's limits with what it uses of each. An owner sets the limit at
  * https://withruntime.com/account/keys; a key can read it, never change it.
  * Past it, a create, wake, extension or renewal fails with
  * `spending_limit_reached` (HTTP 402). */

package/dist/products/mcp.d.ts

@@ -38,6 +38,8 @@ export type McpServerRequest = {
 export type McpGateway = {
     running: boolean;
     port: number | null;
+    /** The URLs are a public preview: no link token, no expiry. */
+    public?: boolean;
     /** Send it as `Authorization: Bearer <token>`. */
     token?: string | null;
     headers?: Record<string, string>;
@@ -65,6 +67,9 @@ export declare function sandboxMcp(t: Transport, sandbox: Sandbox): {
     start: (servers: McpServerRequest[], input?: {
         port?: number;
         replace?: boolean;
+        /** URLs that never expire, guarded by the header alone, which is kept
+         * across starts until `stop()`. Paid accounts only. */
+        public?: boolean;
     }, options?: RequestOptions) => Promise<McpGateway>;
     /** Their state, and fresh URLs. */
     get: (options?: RequestOptions) => Promise<McpGateway>;

package/dist/products/network-products.d.ts

@@ -8,7 +8,10 @@ export type DnsRecord = {
 export type Domain = {
     id: string;
     hostname: string;
-    sandboxId: string;
+    /** The sandbox it serves; null for an App's. */
+    sandboxId: string | null;
+    /** The App it serves, through every deploy and rollback; null for a sandbox's. */
+    appId?: string | null;
     port: number;
     /** pending until the TXT record proves the name is yours, then active. */
     state: "pending" | "active" | "released";
@@ -20,6 +23,13 @@ export type Domain = {
     verifiedAt: string | null;
     checkedAt: string | null;
     checkError: string | null;
+    /** An App's domain's certificate, issued before visitors arrive: point the
+     * name at the App once `ready` is true. Null for a sandbox's. */
+    certificate?: {
+        ready: boolean;
+        expiresAt: string | null;
+        issuers: string[];
+    } | null;
     createdAt: string;
 };
 export type CheckedDomain = Domain & {
@@ -97,12 +107,20 @@ export type TunnelPeerCreated = {
 /** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
 export declare function domains(t: Transport): {
     /** Claims the hostname and answers the DNS records to set. Calling it again
-     * with another sandbox or port points the name there. */
+     * with another sandbox or port points the name there. With `appId`, an App
+     * serves it: add the `_acme-challenge` CNAME too, and point the name at
+     * the App once `certificate.ready` is true. */
     add: (input: {
         hostname: string;
+    } & ({
         sandboxId: string;
         port: number;
-    }, options?: RequestOptions) => Promise<CheckedDomain>;
+        appId?: never;
+    } | {
+        appId: string;
+        sandboxId?: never;
+        port?: never;
+    }), options?: RequestOptions) => Promise<CheckedDomain>;
     /** Checks the TXT record now; the name goes live when it matches. */
     verify: (hostname: string, options?: RequestOptions) => Promise<CheckedDomain>;
     get: (hostname: string, options?: RequestOptions) => Promise<Domain>;

package/dist/products/network-products.js

@@ -5,7 +5,9 @@ const enc = encodeURIComponent;
 export function domains(t) {
     return {
         /** Claims the hostname and answers the DNS records to set. Calling it again
-         * with another sandbox or port points the name there. */
+         * with another sandbox or port points the name there. With `appId`, an App
+         * serves it: add the `_acme-challenge` CNAME too, and point the name at
+         * the App once `certificate.ready` is true. */
         add: (input, options) => t.json({ method: "POST", path: "/v1/domains", body: input, ...options }),
         /** Checks the TXT record now; the name goes live when it matches. */
         verify: (hostname, options) => t.json({

package/dist/products/previews.d.ts

@@ -9,9 +9,12 @@ export type Preview = {
     /** `https://<port>-<sandbox>.<preview domain>/`. A private preview also
      * needs the token. */
     url: string;
-    /** Private previews: a fresh signed token. Send it as the
-     * `x-runtime-preview-token` header. */
+    /** Private previews: a token signed for this answer. Send it as the
+     * `x-runtime-preview-token` header. Every create and read signs its own;
+     * one signed before keeps working until its own expiry or a rotate. */
     token: string | null;
+    /** When this answer's token stops working. Not stored on the preview: a
+     * later read signs another token and leaves this one as it is. */
     tokenExpiresAt: string | null;
     /** Private previews: a link that carries the token once, for a browser. */
     urlWithToken: string | null;
@@ -48,7 +51,7 @@ export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
     /** Shares `port`, or changes its visibility and embedOrigins if it is
      * shared already. */
     create: (port: number, input?: CreatePreview, options?: RequestOptions) => Promise<Preview>;
-    /** Every shared port, each private one with a fresh token. */
+    /** Every shared port, each private one with a fresh token that lasts a day; tokens signed before keep their own expiry. */
     list: (options?: RequestOptions) => Promise<Preview[]>;
     /** One preview, with a fresh private token. `expiresAt` bounds its expiry
      * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */

package/dist/products/previews.js

@@ -10,7 +10,7 @@ export function sandboxPreviews(t, sandbox) {
         /** Shares `port`, or changes its visibility and embedOrigins if it is
          * shared already. */
         create: (port, input = {}, options) => t.json({ method: "POST", path: base(), body: { port, ...input }, ...options }),
-        /** Every shared port, each private one with a fresh token. */
+        /** Every shared port, each private one with a fresh token that lasts a day; tokens signed before keep their own expiry. */
         list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
         /** One preview, with a fresh private token. `expiresAt` bounds its expiry
          * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */

package/dist/snapshots.d.ts

@@ -37,6 +37,10 @@ export type Snapshot = {
         durableAt: string | null;
         storedBytes: number | null;
     };
+    /** An opaque tag for the server it is kept on, like `pl_3f9a0c1b2d4e5f60`.
+     * The same tag as a sandbox of yours means the same server. Null before it
+     * is placed. Absent from older servers. */
+    placement?: string | null;
     error: string | null;
     createdAt: string;
     readyAt: string | null;

package/dist/ssh.d.ts

@@ -16,6 +16,41 @@ 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>;
+/** The editors `runtime sandboxes code` opens: each one's command line program
+ * and the URL scheme its app registers. All three are VS Code underneath and
+ * name an SSH remote the same way, `ssh-remote+<host>`. */
+export declare const EDITORS: {
+    readonly vscode: {
+        readonly name: "VS Code";
+        readonly bin: "code";
+        readonly scheme: "vscode";
+    };
+    readonly cursor: {
+        readonly name: "Cursor";
+        readonly bin: "cursor";
+        readonly scheme: "cursor";
+    };
+    readonly windsurf: {
+        readonly name: "Windsurf";
+        readonly bin: "windsurf";
+        readonly scheme: "windsurf";
+    };
+};
+export type EditorName = keyof typeof EDITORS;
+/** What opens a sandbox's folder in an editor over the `*.runtime` ssh host:
+ * the editor's own program and its arguments, or, without the program on the
+ * PATH, the link its app answers. */
+export declare function editorLaunch(editor: EditorName, sandboxId: string, path: string): {
+    host: string;
+    bin: "code" | "cursor" | "windsurf";
+    args: string[];
+    link: string;
+};
+/** `runtime sandboxes code <id|name> [--editor cursor] [--path /workspace] [--print]`:
+ * a sandbox opened in VS Code, Cursor or Windsurf in one step. It makes sure
+ * the sandbox has an SSH server and this machine has the `*.runtime` ssh
+ * entry, then hands the editor the SSH remote. */
+export declare function editorCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
 /** `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

@@ -11,6 +11,9 @@ ${me} sandboxes ssh config [--install]          The ssh config for \`ssh <id|nam
                                       VS Code Remote-SSH and JetBrains Gateway; --install adds
                                       it to ~/.ssh/config
 ${me} sandboxes ssh proxy <id|name>[.runtime]   ProxyCommand mode: SSH on stdin and stdout
+${me} sandboxes code <id|name> [--editor vscode|cursor|windsurf] [--path /workspace] [--print]
+                                      Open it in your editor over SSH; installs the ssh config
+                                      above once. --print gives the link instead
 ${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
 
@@ -98,7 +101,7 @@ Host *.runtime
 async function installConfig(env) {
     const file = join(configDirectory(env), "ssh", "config");
     await writeFile(file, await sshConfig(env), { mode: 0o600 });
-    const sshDir = join(homedir(), ".ssh");
+    const sshDir = join(env.HOME || homedir(), ".ssh");
     await mkdir(sshDir, { recursive: true, mode: 0o700 });
     const main = join(sshDir, "config");
     const current = await readFile(main, "utf8").catch(() => "");
@@ -236,6 +239,95 @@ function usageError(message, me) {
         hint: `Run \`${me} sandboxes ssh help\`.`,
     });
 }
+/** The editors `runtime sandboxes code` opens: each one's command line program
+ * and the URL scheme its app registers. All three are VS Code underneath and
+ * name an SSH remote the same way, `ssh-remote+<host>`. */
+export const EDITORS = {
+    vscode: { name: "VS Code", bin: "code", scheme: "vscode" },
+    cursor: { name: "Cursor", bin: "cursor", scheme: "cursor" },
+    windsurf: { name: "Windsurf", bin: "windsurf", scheme: "windsurf" },
+};
+/** What opens a sandbox's folder in an editor over the `*.runtime` ssh host:
+ * the editor's own program and its arguments, or, without the program on the
+ * PATH, the link its app answers. */
+export function editorLaunch(editor, sandboxId, path) {
+    const { bin, scheme } = EDITORS[editor];
+    const remote = `ssh-remote+${sandboxId}.runtime`;
+    return {
+        host: `${sandboxId}.runtime`,
+        bin,
+        args: ["--remote", remote, path],
+        link: `${scheme}://vscode-remote/${remote}${path}`,
+    };
+}
+/** Runs a program, answering whether it started and exited 0; a program
+ * missing from the PATH is false, not an error. */
+function launched(bin, args, env) {
+    return new Promise((resolve) => {
+        const child = spawn(bin, args, {
+            env,
+            stdio: "ignore",
+            // `code` and `cursor` are .cmd scripts on Windows.
+            shell: process.platform === "win32",
+        });
+        child.on("error", () => resolve(false));
+        child.on("exit", (code) => resolve(code === 0));
+    });
+}
+/** `runtime sandboxes code <id|name> [--editor cursor] [--path /workspace] [--print]`:
+ * a sandbox opened in VS Code, Cursor or Windsurf in one step. It makes sure
+ * the sandbox has an SSH server and this machine has the `*.runtime` ssh
+ * entry, then hands the editor the SSH remote. */
+export async function editorCommand(argv, env, out, connect, me) {
+    const valueOf = (flag) => {
+        const at = argv.indexOf(flag);
+        return at === -1 ? undefined : argv[at + 1];
+    };
+    const editor = (valueOf("--editor") ?? "vscode").toLowerCase().replace(/^code$/, "vscode");
+    const path = valueOf("--path") ?? "/workspace";
+    const valued = new Set(["--editor", "--path"]);
+    const [target] = argv.filter((word, i) => !word.startsWith("--") && !valued.has(argv[i - 1] ?? ""));
+    if (!target || target === "help") {
+        out.write(SSH_HELP(me));
+        return target ? 0 : 64;
+    }
+    if (!(editor in EDITORS))
+        throw new RuntimeError({
+            message: `${editor} is not an editor this opens.`,
+            code: "usage",
+            status: 0,
+            hint: `Use --editor ${Object.keys(EDITORS).join(", --editor ")}; JetBrains Gateway connects to <id>.runtime after \`${me} sandboxes ssh config --install\`.`,
+        });
+    if (!path.startsWith("/"))
+        throw usageError(`--path is a folder in the sandbox, from /: ${path}`, me);
+    const sbx = await resolveSandbox(await connect(), target);
+    await ensureSshd(sbx, out);
+    await installConfig(env);
+    const how = editorLaunch(editor, sbx.id, path);
+    const { name } = EDITORS[editor];
+    const print = argv.includes("--print");
+    // Without the editor's program on the PATH (VS Code's `code` is opt-in on a
+    // Mac), the desktop opens the editor's link.
+    const [opener, ...openerArgs] = process.platform === "darwin"
+        ? ["open", how.link]
+        : process.platform === "win32"
+            ? ["cmd", "/c", "start", '""', how.link]
+            : ["xdg-open", how.link];
+    const opened = print
+        ? false
+        : (await launched(how.bin, how.args, env))
+            ? "program"
+            : (await launched(opener, openerArgs, env))
+                ? "link"
+                : false;
+    if (out.json)
+        out.write(JSON.stringify({ sandboxId: sbx.id, editor, host: how.host, path, link: how.link, opened }));
+    else if (opened)
+        out.write(`Opening ${path} of ${sbx.id} in ${name} over SSH (host ${how.host}). It needs ${name === "VS Code" ? "the Remote - SSH extension" : "its Remote - SSH extension"}; the first connection installs the editor's server in the sandbox.`);
+    else
+        out.write(`${print ? "" : `Could not start ${how.bin} or open a link here. `}Open this link on this machine:\n${how.link}\nor run: ${how.bin} ${how.args.join(" ")}`);
+    return opened || print ? 0 : 1;
+}
 /** `runtime sandboxes port-forward <id> 5432 8080:3000 ...` */
 export async function portForwardCommand(argv, out, connect, me) {
     const at = argv.indexOf("--address");

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.14.0";
+export declare const VERSION = "0.16.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
@@ -54,14 +54,17 @@ export type Call = RequestOptions & {
     /** 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 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. */
+     * it came. A create, wake or restart 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;
+    /** Internal: when the call's own deadline ends now (performance.now()),
+     * set once the call is prepared; absent when it has none. */
+    deadlineAt?: () => number;
+    /** Internal: moves the call's deadline on by a wait for room, so a wait
+     * for capacity never spends the caller's own `timeoutMs`. */
+    extendDeadline?: (ms: number) => void;
 };
 /** 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
@@ -69,8 +72,8 @@ export type Call = RequestOptions & {
  * 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. */
+ * refuse, so it waited out the whole deadline and failed (a controller
+ * failover drill, 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;
@@ -90,7 +93,7 @@ export declare const DEFAULT_MAX_CONNECTIONS = 48;
 /** 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
+ * the live promise probe broke this way on 9 October 2026. Every
  * deadline the SDK makes from a customer's or a computed value goes through
  * this. */
 export declare function timeoutSignal(ms: number): AbortSignal;

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { ConnectionError, DELIBERATE, errorFor, NOTHING_RAN, RuntimeError, WAITS_FOR_ROOM, } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
 import { warningText } from "./product-renames.js";
-export const VERSION = "0.14.0";
+export const VERSION = "0.16.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
@@ -48,8 +48,8 @@ const NOTHING_RAN_MS = 300_000;
  * 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. */
+ * refuse, so it waited out the whole deadline and failed (a controller
+ * failover drill, 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);
@@ -179,12 +179,36 @@ const KEPT_FOR_CALLS = 8;
 /** 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
+ * the live promise probe broke this way on 9 October 2026. 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)));
 }
+/** A deadline `ms` from now that `extend` moves later; it aborts with a
+ * TimeoutError, as AbortSignal.timeout does. */
+function movableDeadline(ms) {
+    const controller = new AbortController();
+    let at = performance.now() + ms;
+    let timer;
+    const arm = () => {
+        timer = setTimeout(() => controller.abort(new DOMException("The operation timed out.", "TimeoutError")), Math.max(1, Math.ceil(at - performance.now())));
+        // Never keeps a process alive by itself, as AbortSignal.timeout does not.
+        timer.unref?.();
+    };
+    arm();
+    return {
+        signal: controller.signal,
+        at: () => at,
+        extend: (by) => {
+            if (controller.signal.aborted || by <= 0)
+                return;
+            at += by;
+            clearTimeout(timer);
+            arm();
+        },
+    };
+}
 export class Transport {
     baseUrl;
     #apiKey;
@@ -263,22 +287,29 @@ export class Transport {
      * signal through every retry and the complete response body. */
     #prepare(call) {
         const timeoutMs = call.timeoutMs ?? this.#timeoutMs;
-        const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
-        const deadline = timeoutMs === 0 ? undefined : timeoutSignal(timeoutMs + roomMs);
+        // The deadline is the caller's timeoutMs plus only the time actually
+        // spent waiting for room (WAITS_FOR_ROOM), which moves it on as it waits:
+        // a wake given timeoutMs 20 on a server that never answers still ends at
+        // 20 ms, not two minutes later (lifecycle-deadlines.test.ts).
+        const deadline = timeoutMs === 0 ? undefined : movableDeadline(timeoutMs);
         const signal = deadline
             ? call.signal
-                ? AbortSignal.any([call.signal, deadline])
-                : deadline
+                ? AbortSignal.any([call.signal, deadline.signal])
+                : deadline.signal
             : call.signal;
-        return {
+        const prepared = {
             ...call,
             timeoutMs: 0,
-            ...(timeoutMs === 0 ? {} : { deadlineAt: performance.now() + timeoutMs + roomMs }),
             ...(signal ? { signal } : {}),
             ...(call.method !== "GET"
                 ? { idempotencyKey: call.idempotencyKey ?? crypto.randomUUID() }
                 : {}),
         };
+        if (deadline) {
+            prepared.deadlineAt = deadline.at;
+            prepared.extendDeadline = deadline.extend;
+        }
+        return prepared;
     }
     #connectionError(call, cause) {
         const cancelled = call.signal?.aborted === true;
@@ -343,7 +374,9 @@ export class Transport {
         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;
+        // Read at each use: a wait for room moves the call's deadline on.
+        const idleFallback = performance.now() + NOTHING_RAN_MS;
+        const idleUntil = () => call.deadlineAt?.() ?? idleFallback;
         let idleAttempt = 0;
         // The last try never left, and was sent again at once.
         let resentAtOnce = false;
@@ -434,6 +467,7 @@ export class Transport {
                     inCallback = true;
                     call.onCapacityWait?.(error, pause);
                     inCallback = false;
+                    call.extendDeadline?.(pause);
                     await this.#retryAfter(error, pause, signal, gate);
                     continue;
                 }
@@ -448,7 +482,7 @@ export class Transport {
                     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())
+                    if (pause >= idleUntil() - performance.now())
                         throw error;
                     await this.#retryAfter(error, pause, signal, gate);
                     continue;

package/dist/types.d.ts

@@ -62,6 +62,11 @@ export type SandboxInfo = {
     /** The names of its own environment variables (`env`), on a create, an
      * update and a read of one sandbox. Values are never shown. */
     envNames?: string[];
+    /** On an update with labels by a key that may read secrets, when one of
+     * the account's egress secrets is scoped: true once every server running its sandboxes holds the change,
+     * so the next request uses the new scope; false while one has not
+     * confirmed (it takes it within 15 seconds). */
+    secretsEnforced?: boolean;
     /** On a create from an image with a start command: whether it started
      * (and was still running half a second later), became ready (readyMs),
      * timed out, or exited first (exitCode, and stderr's last lines). The create's answer
@@ -78,6 +83,11 @@ export type SandboxInfo = {
     };
     /** Present and true when getOrCreate answered a sandbox that already held the name. */
     reused?: boolean;
+    /** An opaque tag for the server it is on, like `pl_3f9a0c1b2d4e5f60`. Your
+     * sandboxes and snapshots with the same tag are on the same server. It is
+     * never the server's name, and other accounts see unrelated tags. Null
+     * before it is placed. Absent from older servers. */
+    placement?: string | null;
     [key: string]: unknown;
 };
 export type CreateSandbox = {
@@ -142,6 +152,13 @@ export type CreateSandbox = {
     image?: string;
     /** A ready snapshot's id: the sandbox starts as a copy of it, with its shape. Not with image. */
     snapshot?: string;
+    /** One to 16 ids of your own sandboxes or snapshots. The new sandbox starts
+     * on a server none of them is on, and stays apart if its start is moved.
+     * With no other server that has room, the create answers 409 `no_capacity`
+     * and nothing is made or charged. A copy of a snapshot starts only where that
+     * snapshot is kept, so a `snapshot` with `spreadFrom` naming its server also
+     * answers `no_capacity`. */
+    spreadFrom?: string[];
     /** Up to four volumes: read-write ("rw", one sandbox at a time) or a
      * read-only "snapshot" copy. */
     volumes?: {
@@ -430,6 +447,13 @@ export type SandboxSettings = {
     persistent?: boolean;
     /** Lifetime cap in microdollars; null removes it. */
     maxTotalCostMicros?: number | null;
+    /** A new time limit counted from now, 60 to 86400 seconds, sooner or later
+     * than the one it had; 0 takes the limit away. A paused sandbox counts it
+     * from its next wake. Not for a persistent sandbox. */
+    timeoutSeconds?: number;
+    /** What the end of its time limit does: pause, stop (keep the disk) or
+     * delete. */
+    onTimeout?: "pause" | "stop" | "delete";
 };
 /** A deleted sandbox, as `delete()` answers it the first time and every time
  * after. It reads nowhere else afterwards. */

package/dist/vercel/command.d.ts

@@ -1,3 +1,4 @@
+import type { Readable } from "node:stream";
 import type { Process } from "../sandbox.js";
 /** One piece of a command's output, as Vercel's `logs()` yields it. */
 export type LogOutputLine = {
@@ -21,6 +22,8 @@ type Init = {
     sandboxName: string;
     process?: Process;
     lines?: LogOutputLine[];
+    /** Each line as it arrives, for an attached command's stdout/stderr. */
+    onLine?: (line: LogOutputLine) => void;
 };
 /** A command in a sandbox, as Vercel's `Command`. A detached one runs on:
  * `wait()` for its end, `logs()` for its output as it happens. `cmdId` is
@@ -30,6 +33,8 @@ export declare class Command {
     exitCode: number | null;
     durationMs?: number;
     protected readonly init: Init;
+    /** Set when the command was started with a `Readable` for stdin. */
+    stdinPipe: StdinPipe | null;
     constructor(init: Init);
     get cmdId(): string;
     get cwd(): string;
@@ -41,7 +46,8 @@ export declare class Command {
     }): AsyncGenerator<LogOutputLine, void, void> & Disposable & {
         close(): void;
     };
-    /** Waits for the command to end. */
+    /** Waits for the command to end. With a `Readable` piped to its stdin,
+     * rejects if piping fails, and stops piping once the command exits. */
     wait(params?: {
         signal?: AbortSignal;
     }): Promise<CommandFinished>;
@@ -60,11 +66,52 @@ export declare class Command {
     kill(signal?: Signal, opts?: {
         abortSignal?: AbortSignal;
     }): Promise<void>;
+    /** Writes to the stdin of a command started with `stdin: true` and
+     * `detached: true`. Writes reach the process in call order and resolve once
+     * it has accepted the data; Runtime's input offsets make every resend exact,
+     * so no byte is written twice. If a write fails, part of it may have been
+     * written, and later writes are refused; closeStdin still works. */
+    writeStdin(data: string | Uint8Array, opts?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
+    /** Closes the command's stdin, so it reads EOF once it has consumed what
+     * was written. */
+    closeStdin(opts?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
 }
+/** A `Readable` being written to a command's stdin. */
+export interface StdinPipe {
+    /** Resolves once the stream has ended and stdin is closed, or the command
+     * stops accepting input; rejects if a write fails or the stream errors. */
+    done: Promise<void>;
+    /** Stops reading the stream, for when the command has exited. */
+    stop(): void;
+}
+/** Writes a stream to a command's stdin in order, closing stdin when it
+ * ends. What is read while a write is in flight goes in the next write, and
+ * reading pauses while too much waits. The stream is never ended or
+ * destroyed, and every listener is removed once piping stops. */
+export declare function pipeStdin(command: Command, stream: Readable, signal?: AbortSignal): StdinPipe;
+/** Waits for a command to finish, rejecting early if piping its stdin fails,
+ * and stops piping once it has exited. Aborting `signal` stops waiting but
+ * leaves the pipe running. */
+export declare function waitWithStdinPipe<T>(finished: Promise<T>, pipe: StdinPipe | null, opts?: {
+    signal?: AbortSignal;
+    onPipeError?: () => void;
+}): Promise<T>;
 /** A command that has ended; `exitCode` is set. */
 export declare class CommandFinished extends Command {
     exitCode: number;
     constructor(init: Init, exitCode: number, durationMs?: number);
     wait(): Promise<CommandFinished>;
+    /** Always throws: the command has already exited. */
+    writeStdin(_data: string | Uint8Array, _opts?: {
+        abortSignal?: AbortSignal;
+    }): Promise<never>;
+    /** Always throws: the command has already exited. */
+    closeStdin(_opts?: {
+        abortSignal?: AbortSignal;
+    }): Promise<never>;
 }
 export {};