withruntime 0.12.0 → 0.16.0

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.12.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
@@ -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: {
@@ -51,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
@@ -66,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;
@@ -87,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.12.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
@@ -9,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" };
@@ -45,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);
@@ -176,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;
@@ -204,7 +231,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;
@@ -254,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;
@@ -301,6 +341,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 {
@@ -322,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;
@@ -413,7 +467,8 @@ export class Transport {
                     inCallback = true;
                     call.onCapacityWait?.(error, pause);
                     inCallback = false;
-                    await this.#rest(pause, signal, gate);
+                    call.extendDeadline?.(pause);
+                    await this.#retryAfter(error, pause, signal, gate);
                     continue;
                 }
                 // Nothing ran: safe to send again for any call, past maxRetries,
@@ -427,9 +482,9 @@ 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.#rest(pause, signal, gate);
+                    await this.#retryAfter(error, pause, signal, gate);
                     continue;
                 }
                 const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);

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 = {
@@ -92,7 +102,7 @@ export type CreateSandbox = {
      * `env`. At most 32 variables and 32 KiB. Values are never shown again;
      * answers list only `envNames`. Copies made by fork() keep them. */
     env?: Record<string, string>;
-    /** Omit to use the 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;
@@ -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?: {
@@ -295,11 +312,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
@@ -318,9 +335,13 @@ 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 included usage
+     * 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. */
@@ -426,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 {};