withruntime 0.23.0 → 0.33.0

package/dist/products/secrets.d.ts

@@ -10,31 +10,99 @@ export type SecretRule = {
     paths: string[];
 };
 /** Which sandboxes get a secret: those whose labels hold every pair of any one
- * selector in `labels` (including sandboxes created or labelled later), and
- * those named in `sandboxes`. Any other sandbox of the organization sees no
- * placeholder, and its requests never carry the value. Absent on a secret:
- * every sandbox of the organization. */
+ * selector in `labels` (including sandboxes created or labelled later), those
+ * named in `sandboxes`, and every copy of the Apps named in `apps`. Any other
+ * sandbox of the organization sees no placeholder, and its requests never
+ * carry the value. Absent on a secret: every sandbox of the organization. */
 export type SecretScope = {
     /** 1 to 8 selectors of 1 to 8 key/value pairs: `[{ role: "hub" }]`. */
     labels?: Array<Record<string, string>>;
     /** 1 to 100 sandbox ids of the organization. */
     sandboxes?: string[];
+    /** 1 to 100 App or Function ids: every copy of each, of any version,
+     * including copies later deploys, restarts and scaling make. A deploy names
+     * the secrets its copies see (`apps.deploy(id, { secrets: [...] })`). */
+    apps?: string[];
+};
+/** A GitHub App the servers act as. The secret's value is the App's private
+ * key (PEM); the servers make its installation tokens themselves, each for an
+ * hour. The key goes into no request, and each request the rules allow carries
+ * the current token: `Authorization: Bearer` to the API, and git's
+ * `x-access-token` to git over HTTPS. Takes no `header` or `format`. */
+export type SecretGithubApp = {
+    /** The App's id. */
+    id: number;
+    /** The installation's id: where the App is installed. */
+    installation: number;
+    /** The repositories each token reaches, by name. Absent: every repository of
+     * the installation. */
+    repositories?: string[];
+    /** What each token may do, at most what the App holds: `{ contents: "write" }`.
+     * Absent: all the App's permissions. */
+    permissions?: Record<string, "read" | "write" | "admin">;
+    /** The App's API on GitHub Enterprise Server (`https://<host>/api/v3`); one
+     * of `hosts`. Default `https://api.github.com`. */
+    api?: string;
+};
+/** What a git push over HTTPS carrying the secret may update. A push to any
+ * other ref, a tag, or a delete is refused before it leaves the server, in
+ * git's own words (`! [remote rejected]`). */
+export type SecretGit = {
+    /** The branches a push may update: `refs/heads/` then a name, with `*` only
+     * at the end for any name that begins so, and `{label.<key>}` for the
+     * sandbox's own label of that key (a sandbox without it pushes nothing it
+     * names): `["refs/heads/task/{label.task}", "refs/heads/task/{label.task}--*"]`.
+     * Empty: no push at all. */
+    push: string[];
+};
+/** Each sandbox's hour with the secret, the far end's reserve, GraphQL's
+ * mutations and shared copies. */
+export type SecretApiPolicy = {
+    /** The most requests each sandbox makes with the secret in an hour; past it,
+     * 429 with `Retry-After`. */
+    callsPerHour?: number;
+    /** The most writes (any method but GET, HEAD and OPTIONS; a GraphQL
+     * mutation) each sandbox makes in an hour. 0: none. */
+    writesPerHour?: number;
+    /** Calls the far end keeps for others: none is sent while its
+     * `x-ratelimit-remaining` says this many or fewer are left, until its reset. */
+    keep?: number;
+    /** Reads (GET over HTTP/2) answered from the server's copy while the far end
+     * answers 304 to its ETag, shared by every sandbox the secret reaches on that
+     * server; past a sandbox's hour, from the copy unasked. Answers carry
+     * `x-runtime-copy`. */
+    copies?: boolean;
+    /** With `copies`: 1 to 300 seconds a copy is answered without asking the far
+     * end, GraphQL queries included. */
+    fresh?: number;
+    /** A GraphQL query always goes; a mutation only when every one is listed. */
+    graphql?: {
+        /** Default `/graphql`. */
+        path?: string;
+        /** The mutations a request may make; any other is refused with 403. */
+        mutations: string[];
+    };
 };
 /** A secret your sandboxes use without seeing it. Every sandbox of your
- * organization has an environment variable of the secret's name holding
- * `placeholder`; the egress proxy sets `header` on every HTTPS request to
+ * organization has an environment variable of the secret's name (or `env`)
+ * holding `placeholder`; the egress proxy sets `header` on every HTTPS request to
  * `hosts`, or, without `header`, replaces the placeholder in a credential
  * header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key,
  * x-subscription-token, private-token). Never in the URL or another header.
  * The value is never returned. */
 export type Secret = {
     name: string;
+    /** The environment variable the placeholder is in, when not `name`. */
+    env?: string;
     hosts: string[];
     header?: string;
     format?: string;
     rules?: SecretRule[];
     /** Absent: every sandbox of the organization. */
     only?: SecretScope;
+    githubApp?: SecretGithubApp;
+    git?: SecretGit;
+    api?: SecretApiPolicy;
     placeholder: string;
     valueBytes: number;
     createdAt: string;
@@ -62,6 +130,22 @@ export type SetSecret = {
      * has stays, so a new value never widens who gets it. `{}`: every sandbox of
      * the organization again. */
     only?: SecretScope;
+    /** The value is a GitHub App's private key (PEM), and the servers make the
+     * App's installation tokens themselves. Takes no `header` or `format`. */
+    githubApp?: SecretGithubApp;
+    /** What a git push over HTTPS carrying the secret may update. Absent: the
+     * secret limits no push. */
+    git?: SecretGit;
+    /** Each sandbox's hour with the secret, the far end's reserve, GraphQL's
+     * mutations and shared copies. */
+    api?: SecretApiPolicy;
+    /** The environment variable sandboxes see it in, when not the secret's
+     * name. Several secrets may share one, each scoped (`only`) to sandboxes no
+     * other of them reaches, such as one `GITHUB_TOKEN` per repository: a write
+     * that would put two in one sandbox is refused (409, conflict). The
+     * secret's own name gives the name back. Absent when replacing a secret:
+     * the variable it has stays. */
+    env?: string;
     /** Also keep a copy for scheduled jobs, which a job puts into its run's
      * environment (`jobs.create({ secrets: [...] })`). Unlike the sandboxes'
      * copy, the jobs copy is yours rather than the account's, versioned, and can

package/dist/products/secrets.js

@@ -4,7 +4,9 @@ import { switchedOff } from "./jobs.js";
  * names what took effect. Calling again with the same arguments is safe. */
 export class SecretPartlyStoredError extends RuntimeError {
 }
-const unavailable = (error) => error instanceof RuntimeError && (error.code === "unavailable" || error.status === 503);
+/** Secrets for jobs switched off here (501; 503 from an older server). */
+const unavailable = (error) => error instanceof RuntimeError &&
+    (error.code === "unavailable" || error.status === 501 || error.status === 503);
 export function secrets(t) {
     const off = switchedOff("Secrets for jobs");
     const store = (call) => t.json(call).catch(off);
@@ -62,7 +64,11 @@ export function secrets(t) {
             ];
             for (const replay of replays) {
                 const answer = await replay().catch((again) => {
-                    if (again instanceof RuntimeError && again.status === 409)
+                    // Not this request's earlier send: a conflict, or its key held by
+                    // another request (idempotency_conflict, 422; 409 from an older
+                    // server).
+                    if (again instanceof RuntimeError &&
+                        (again.status === 409 || again.code === "idempotency_conflict"))
                         return undefined;
                     throw again;
                 });

package/dist/proxy.d.ts

@@ -16,9 +16,9 @@ export type Route = {
 export declare function exemption(list: string, hostname: string, port: string): string | undefined;
 /** The route the SDK takes to `target`, read from the environment now. */
 export declare function routeFor(target: string, env?: Env): Route;
-/** Words for a failed connection: the route it took, and what to check.
- * `cause` is the error fetch threw, or the status a proxy answered with (Bun's
- * fetch hands a refused tunnel back as a response). */
+/** The certificate error under a failed call, if that is why it failed: its
+ * code, found anywhere in the cause chain. Pure. */
+export declare function untrustedCertificate(cause: unknown): string | undefined;
 export declare function describeRoute(target: string, cause: unknown, env?: Env): {
     via: string;
     hint?: string;

package/dist/proxy.js

@@ -91,6 +91,26 @@ function invalidProxy(name, shown, problem) {
 /** Words for a failed connection: the route it took, and what to check.
  * `cause` is the error fetch threw, or the status a proxy answered with (Bun's
  * fetch hands a refused tunnel back as a response). */
+/** The TLS codes Node gives when a certificate chain is not one it trusts:
+ * a proxy or firewall that inspects TLS with its own authority, most often. */
+const UNTRUSTED = new Set([
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+]);
+/** The certificate error under a failed call, if that is why it failed: its
+ * code, found anywhere in the cause chain. Pure. */
+export function untrustedCertificate(cause) {
+    for (let c = cause, depth = 0; c && typeof c === "object" && depth < 8; depth++) {
+        const code = c.code;
+        if (typeof code === "string" && UNTRUSTED.has(code))
+            return code;
+        c = c.cause;
+    }
+    return undefined;
+}
 export function describeRoute(target, cause, env = processEnv()) {
     let route;
     try {

package/dist/sandbox.d.ts

@@ -1,7 +1,7 @@
 import type { Page } from "./page.js";
 import { type FileEvent, type WatchHandle, type WatchOptions } from "./products/watch.js";
 import { Transport, type RequestOptions } from "./transport.js";
-import type { CommandResult, DeletedSandbox, ExecOptions, FileEntry, OutputEvent, BinaryOutputEvent, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
+import type { CommandResult, TracedFiles, DeletedSandbox, ExecOptions, FileEntry, FileLink, OutputEvent, BinaryOutputEvent, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
 import { type SandboxExtensions } from "./products/index.js";
 import { Tunnel, type PortForward } from "./tunnel.js";
 import type { StreamUploadSource } from "./file-source.js";
@@ -206,6 +206,9 @@ export declare class Process {
     } & Pick<RequestOptions, "signal" | "timeoutMs">): Promise<void>;
     kill(signal?: "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2", options?: RequestOptions): Promise<void>;
     resize(cols: number, rows: number, options?: RequestOptions): Promise<void>;
+    /** What a process spawned with `traceFiles` opened and wrote. Known once it
+     * has ended: a running one answers 409 process_running. */
+    files(): Promise<TracedFiles>;
     refresh(): Promise<ProcessInfo>;
 }
 export declare class Terminal {
@@ -314,6 +317,31 @@ export declare class Files {
     rename(from: string, to: string, options?: {
         overwrite?: boolean;
     } & RequestOptions): Promise<void>;
+    /** A link anyone can open with no API key to download this file, for a
+     * browser or another service: Range works, so videos play and downloads
+     * resume. One hour by default, at most 7 days (`expiresInSeconds`).
+     * `filename` makes it a download with that name; `archive: true` links a
+     * folder as a .tar.gz. Revoking the key that made it ends it, as does
+     * `revokeLinks()`. */
+    downloadUrl(path: string, options?: RequestOptions & {
+        expiresInSeconds?: number;
+        filename?: string;
+        wake?: boolean;
+        archive?: boolean;
+    }): Promise<FileLink>;
+    /** A link anyone can PUT a file's bytes to, with no API key: the body
+     * becomes the file at `path`, whole or not at all, up to `maxBytes` (5 GiB
+     * at most; the body must arrive within 5 minutes). */
+    uploadUrl(path: string, options?: RequestOptions & {
+        expiresInSeconds?: number;
+        maxBytes?: number;
+        wake?: boolean;
+    }): Promise<FileLink>;
+    /** Ends every link made for this sandbox so far; links made after work. */
+    revokeLinks(options?: RequestOptions): Promise<{
+        sandboxId: string;
+        revokedAt: string;
+    }>;
     /** Packs a directory as archive bytes; `gzip: false` returns plain tar.
      * Exclusions are relative paths, not globs. `user: root` selects guest root. */
     archive(path: string, options?: RequestOptions & {

package/dist/sandbox.js

@@ -86,6 +86,7 @@ function commandBody(command, options) {
                 ? { stdin: options.stdin }
                 : { stdinBase64: toBase64(options.stdin) }),
         ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        ...(options.traceFiles ? { traceFiles: true } : {}),
     };
 }
 /** How long past its timeoutMs a streamed exec waits for an exit that never came. */
@@ -190,6 +191,12 @@ export class Sandbox extends Machine {
             finally {
                 clearTimeout(timer);
             }
+            // A stream the server ended (continue) is followed to its exit, which
+            // names no files: they are the process's own to read.
+            const files = exit?.files ??
+                (options.traceFiles && processId && exit?.state
+                    ? await new Process(this.#t, this.id, { id: processId }).files()
+                    : undefined);
             result = {
                 exitCode: exit?.exitCode ?? null,
                 ...out,
@@ -198,6 +205,7 @@ export class Sandbox extends Machine {
                 ...(exit?.durationMs === undefined ? {} : { durationMs: exit.durationMs }),
                 ...(processId ? { processId } : {}),
                 ...(exit?.outOfMemory ? { outOfMemory: exit.outOfMemory } : {}),
+                ...(files ? { files } : {}),
             };
         }
         if (options.check && (result.exitCode !== 0 || result.timedOut))
@@ -354,6 +362,8 @@ export class Sandbox extends Machine {
             path: `/v1/sandboxes/${enc(this.id)}:fork`,
             body,
             wait: 60,
+            // Its key replays a refusal for room or a limit, so it is told at once.
+            waitForCapacityMs: 0,
             ...requestOnly({ idempotencyKey, signal, timeoutMs }),
         });
         const sandboxes = reply.sandboxes.map((info) => new Sandbox(this.#t, info));
@@ -410,9 +420,11 @@ function processBytes(encoded) {
 function cutOff(error) {
     return (!(error instanceof RuntimeError) ||
         error instanceof ConnectionError ||
-        ((error instanceof RateLimitError || error instanceof ServiceUnavailableError) &&
-            [429, 502, 503, 504].includes(error.status) &&
-            !DELIBERATE.has(error.code)));
+        // The API says whether it passes; an older server is judged by status.
+        (error.sentRetryable ??
+            ((error instanceof RateLimitError || error instanceof ServiceUnavailableError) &&
+                [429, 502, 503, 504].includes(error.status) &&
+                !DELIBERATE.has(error.code))));
 }
 /** How long a follow keeps reconnecting while every attempt fails. A command
  * runs for hours whether or not anyone reads it; a few minutes of a deploy, a
@@ -758,6 +770,14 @@ export class Process {
             ...options,
         });
     }
+    /** What a process spawned with `traceFiles` opened and wrote. Known once it
+     * has ended: a running one answers 409 process_running. */
+    files() {
+        return this.t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${enc(this.sandboxId)}/processes/${enc(this.id)}/files`,
+        });
+    }
     async refresh() {
         this.info = await this.t.json({
             method: "GET",
@@ -817,6 +837,8 @@ export class Terminal {
         });
     }
     write(data) {
+        // A view of shared memory is refused by WebSocket.send: the bytes it
+        // takes are an ArrayBuffer's, which TypeScript 7's DOM types ask for.
         this.socket.send(typeof data === "string" ? new TextEncoder().encode(data) : data);
     }
     resize(cols, rows) {
@@ -1213,6 +1235,37 @@ export class Files {
             ...request,
         });
     }
+    /** A link anyone can open with no API key to download this file, for a
+     * browser or another service: Range works, so videos play and downloads
+     * resume. One hour by default, at most 7 days (`expiresInSeconds`).
+     * `filename` makes it a download with that name; `archive: true` links a
+     * folder as a .tar.gz. Revoking the key that made it ends it, as does
+     * `revokeLinks()`. */
+    async downloadUrl(path, options = {}) {
+        const { expiresInSeconds, filename, wake, archive, ...request } = options;
+        return this.t.json({
+            method: "POST",
+            path: this.#path("/files:link"),
+            body: { path, method: "GET", expiresInSeconds, filename, wake, archive },
+            ...request,
+        });
+    }
+    /** A link anyone can PUT a file's bytes to, with no API key: the body
+     * becomes the file at `path`, whole or not at all, up to `maxBytes` (5 GiB
+     * at most; the body must arrive within 5 minutes). */
+    async uploadUrl(path, options = {}) {
+        const { expiresInSeconds, maxBytes, wake, ...request } = options;
+        return this.t.json({
+            method: "POST",
+            path: this.#path("/files:link"),
+            body: { path, method: "PUT", expiresInSeconds, maxBytes, wake },
+            ...request,
+        });
+    }
+    /** Ends every link made for this sandbox so far; links made after work. */
+    async revokeLinks(options = {}) {
+        return this.t.json({ method: "POST", path: this.#path("/files:revoke-links"), ...options });
+    }
     /** Packs a directory as archive bytes; `gzip: false` returns plain tar.
      * Exclusions are relative paths, not globs. `user: root` selects guest root. */
     async archive(path, options = {}) {

package/dist/snapshots.d.ts

@@ -17,7 +17,7 @@ export type Snapshot = {
         diskMiB: number;
         memoryGuarantee: string;
     };
-    /** Null: kept while your account has credit, up to a year from when it was taken. */
+    /** Null: kept while your account has credit, with no end date. */
     retentionDays: number | null;
     /** True while raw fork memory awaits verified compression. The snapshot
      * remains ready for starts on its current host, with no storage charge or

package/dist/switched-off.d.ts

@@ -0,0 +1,5 @@
+import { type RuntimeError } from "./errors.js";
+/** A product switched off on this deployment, by its `<product>_unavailable`
+ * code: a 501, or a 503 with a deliberate code from an older server (whose
+ * host_unavailable and api_unavailable are 503s too, and pass). */
+export declare function productSwitchedOff(error: RuntimeError): boolean;

package/dist/switched-off.js

@@ -0,0 +1,8 @@
+import { DELIBERATE } from "./errors.js";
+/** A product switched off on this deployment, by its `<product>_unavailable`
+ * code: a 501, or a 503 with a deliberate code from an older server (whose
+ * host_unavailable and api_unavailable are 503s too, and pass). */
+export function productSwitchedOff(error) {
+    return (error.code.endsWith("_unavailable") &&
+        (error.status === 501 || (error.status === 503 && DELIBERATE.has(error.code))));
+}

package/dist/tar.d.ts

@@ -8,7 +8,7 @@ export declare function packDirectory(root: string): Promise<Uint8Array>;
  * once the whole archive arrived, so an archive cut short leaves nothing
  * behind that could pass for the folder. A target that exists is merged
  * into, files of the same name replaced. */
-export declare function unpackStream(source: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, target: string, options?: {
+export declare function unpackStream(from: AsyncIterable<Uint8Array> | Iterable<Uint8Array> | ReadableStream<Uint8Array>, target: string, options?: {
     signal?: AbortSignal;
 }): Promise<void>;
 /** Unpacks a whole gzipped tar held in memory, by the same rules. */

package/dist/tar.js

@@ -455,14 +455,32 @@ async function merge(from, to, root, signal) {
             await rename(source, destination);
     }
 }
+/** A web stream's chunks, read through its reader. The SDK is built with
+ * TypeScript 5, whose DOM types do not make a ReadableStream async iterable
+ * (TypeScript 7's do), so a download's body is read this way in both. */
+async function* chunksOf(stream) {
+    const reader = stream.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            yield value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 /** Unpacks a gzipped tar that arrives as a stream into `target`, refusing any
  * entry that would land outside it, holding no more than a chunk at a time.
  * It unpacks into a folder beside the target and moves it into place only
  * once the whole archive arrived, so an archive cut short leaves nothing
  * behind that could pass for the folder. A target that exists is merged
  * into, files of the same name replaced. */
-export async function unpackStream(source, target, options = {}) {
+export async function unpackStream(from, target, options = {}) {
     checkSignal(options.signal);
+    const source = from instanceof ReadableStream ? chunksOf(from) : from;
     const final = resolve(target);
     await mkdir(dirname(final), { recursive: true });
     const staging = await mkdtemp(`${final}.runtime-partial-`);

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.23.0";
+export declare const VERSION = "0.33.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

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 { describeRoute, envFetch, openWebSocket, untrustedCertificate } from "./proxy.js";
 import { warningText } from "./product-renames.js";
-export const VERSION = "0.23.0";
+export const VERSION = "0.33.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
@@ -42,6 +42,10 @@ function processEnv() {
 /** How long an answer that ran nothing (NOTHING_RAN) is retried for a call
  * that has no deadline of its own. */
 const NOTHING_RAN_MS = 300_000;
+/** The longest wait the SDK sleeps on for a retry. A refusal that names a
+ * longer one (a daily cap, about an hour) is thrown at once, still
+ * retryable and with its `retryAfterMs`, for the caller to schedule. */
+const LONGEST_RETRY_WAIT_MS = 60_000;
 /** How long one attempt waits for its answer to start. The API starts every
  * answer within 120 s: Caddy answers 503 itself past that, and a longer call
  * gets its 200 at 90 s and then its JSON (runtime-late-answer). An attempt
@@ -316,6 +320,19 @@ export class Transport {
         const route = this.#routed && !cancelled
             ? describeRoute(`${this.baseUrl}${call.path}`, cause)
             : { via: "" };
+        // A certificate this machine does not trust answered, most often a proxy
+        // that inspects TLS: said as that, never as "no answer" (18 October 2026,
+        // the published CLI on Node behind such a proxy, where Bun trusted it).
+        const certificate = cancelled ? undefined : untrustedCertificate(cause);
+        if (certificate)
+            return new ConnectionError({
+                message: `Runtime at ${this.baseUrl}${route.via} could not be reached: the TLS certificate presented is not one this machine trusts (${certificate}).`,
+                hint: "A proxy or firewall that inspects TLS signs with its own authority: point NODE_EXTRA_CA_CERTS at its certificate (Node), or add it to the system's trusted certificates.",
+                code: "connection_error",
+                status: 0,
+                ...(call.idempotencyKey ? { idempotencyKey: call.idempotencyKey } : {}),
+                cause,
+            });
         return new ConnectionError({
             message: cancelled
                 ? "The call was cancelled or ran past its deadline."
@@ -453,13 +470,17 @@ export class Transport {
                     parsed = { error: { message: text.slice(0, 500) || `HTTP ${status}` } };
                 }
                 const error = errorFor(status, parsed, key);
+                const header = Number(response.headers.get("retry-after"));
+                const headerMs = Number.isFinite(header) && header > 0 ? header * 1000 : undefined;
                 // A full house: wait for a slot or for room, then send the same call
                 // again. A request that can never fit (a fork of more copies than the
                 // trial runs) is not waited for.
                 if (retry &&
                     roomMs > 0 &&
                     WAITS_FOR_ROOM.has(error.code) &&
-                    error.details?.field !== "count") {
+                    error.details?.field !== "count" &&
+                    // A quota on what is kept says it never clears by waiting.
+                    error.sentRetryable !== false) {
                     const left = roomUntil - performance.now();
                     if (left <= 0)
                         throw error;
@@ -478,21 +499,32 @@ export class Transport {
                 // still says nothing ran.
                 if ([429, 503].includes(status) &&
                     NOTHING_RAN.has(error.code) &&
+                    error.sentRetryable !== false &&
                     (!late || error.code === "guest_busy")) {
-                    const header = Number(response.headers.get("retry-after"));
-                    const base = error.retryAfterMs ?? (Number.isFinite(header) && header > 0 ? header * 1000 : 250);
+                    const named = error.retryAfterMs ?? headerMs;
+                    if (named !== undefined && named > LONGEST_RETRY_WAIT_MS)
+                        throw withWait(error, named);
+                    const base = named ?? 250;
                     const pause = Math.min(30_000, base * 2 ** Math.min(idleAttempt++, 3)) * (0.9 + Math.random() * 0.2);
                     if (pause >= idleUntil() - performance.now())
                         throw error;
                     await this.#retryAfter(error, pause, signal, gate);
                     continue;
                 }
-                const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
+                // The API says whether the same request may succeed; an older
+                // server is judged by its status. A refusal for room or for the
+                // account's own limit is the room wait's above on a create, wake or
+                // restart, which set waitForCapacityMs (0 fails at once); any other
+                // call retries what the answer says.
+                const retryable = (error.sentRetryable ??
+                    ([429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code))) &&
+                    !(call.waitForCapacityMs !== undefined && WAITS_FOR_ROOM.has(error.code));
                 if (!retry || !retryable || attempt >= this.#maxRetries)
                     throw error;
-                const header = Number(response.headers.get("retry-after"));
-                const wait = error.retryAfterMs ??
-                    (Number.isFinite(header) && header > 0 ? header * 1000 : backoff(attempt));
+                const named = error.retryAfterMs ?? headerMs;
+                if (named !== undefined && named > LONGEST_RETRY_WAIT_MS)
+                    throw withWait(error, named);
+                const wait = named ?? backoff(attempt);
                 await this.#rest(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal, gate);
             }
             catch (cause) {
@@ -796,6 +828,13 @@ export function neverSent(cause) {
     }
     return false;
 }
+/** `error` thrown for a wait too long to sleep on, carrying that wait as
+ * `retryAfterMs` when only the Retry-After header named it. */
+function withWait(error, ms) {
+    if (error.retryAfterMs === undefined)
+        error.retryAfterMs = Math.round(ms);
+    return error;
+}
 function backoff(attempt) {
     return Math.min(8000, 250 * 2 ** attempt) * (0.5 + Math.random());
 }

package/dist/types.d.ts

@@ -133,8 +133,9 @@ export type CreateSandbox = {
     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;
-     * otherwise 10 to 86400. A request wakes it again. */
+     * traffic and no CPU use. Default 300 unless persistent; 0 never;
+     * otherwise 60 to 86400 (a shorter time is raised to 60). A request wakes
+     * it again. */
     idlePauseSeconds?: number;
     /** A request to a paused sandbox wakes it. Default true. */
     autoWake?: boolean;
@@ -165,7 +166,7 @@ export type CreateSandbox = {
     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`
+     * With no other server that has room, the create answers 503 `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`. */
@@ -197,6 +198,16 @@ export type OutOfMemory = {
     /** What to do: a larger memoryMiB, or a program that uses less. */
     hint: string;
 };
+/** What a command run with `traceFiles` opened and wrote, until it exited. */
+export type TracedFiles = {
+    /** Every file and directory it, or anything it started, opened: sorted
+     * absolute paths, links resolved; a directory (a listing) ends in "/". */
+    read: string[];
+    /** Every file it wrote. */
+    written: string[];
+    /** Some paths are missing: the lists are not the whole story. */
+    truncated: boolean;
+};
 export type CommandResult = {
     exitCode: number | null;
     stdout: string;
@@ -208,6 +219,8 @@ export type CommandResult = {
     processId?: string;
     replayed?: boolean;
     outOfMemory?: OutOfMemory;
+    /** With `traceFiles` only. */
+    files?: TracedFiles;
 };
 export type ExecOptions = {
     cwd?: string;
@@ -226,6 +239,9 @@ export type ExecOptions = {
     onStderr?: (text: string) => unknown;
     /** Throw CommandError when the exit code is not 0. */
     check?: boolean;
+    /** Answer `files`: what the command read and wrote, for keying a cache by
+     * what a test really read. */
+    traceFiles?: boolean;
     signal?: AbortSignal;
     idempotencyKey?: string;
 };
@@ -265,6 +281,8 @@ export type OutputEvent = {
     timedOut: boolean;
     durationMs?: number;
     outOfMemory?: OutOfMemory;
+    /** An exec with `traceFiles`. */
+    files?: TracedFiles;
 } | {
     type: "truncated";
     droppedBytes: number;
@@ -302,6 +320,19 @@ export type FileEntry = {
     group?: string;
     symlinkTarget?: string;
 };
+/** A signed link to one file of a sandbox (POST .../files:link): `url` opens
+ * with no API key, GET to download (Range works) or PUT to upload, until
+ * `expiresAt`. */
+export type FileLink = {
+    url: string;
+    method: "GET" | "PUT";
+    path: string;
+    sandboxId: string;
+    expiresAt: string;
+    filename?: string;
+    maxBytes?: number;
+    archive?: boolean;
+};
 /** GET /v1/usage. Money is integer microdollars in strings (1,000,000 = $1),
  * exact past 2^53: available = credited - spent - expired - held. */
 export type Usage = {
@@ -457,7 +488,7 @@ export type SandboxSettings = {
     /** A request to a paused sandbox wakes it. */
     autoWake?: boolean;
     /** Pause after this many seconds with no activity, counted from now; 0
-     * never, otherwise 10 to 86400. */
+     * never, otherwise 60 to 86400 (a shorter time is raised to 60). */
     idlePauseSeconds?: number;
     /** Keep it running until you stop it, while credit lasts, and keep its disk
      * after a stop. Paid only. */