withruntime 0.11.0 → 0.11.1

package/dist/sandbox.js

@@ -1,10 +1,13 @@
 import { KEEP_ALIVE_MARGIN_SECONDS, STREAMED_EXEC_TIMEOUT_MS, WAIT_FOR_TIMEOUT_SECONDS, } from "./api-defaults.js";
-import { CommandError, ConnectionError, NotFoundError, RuntimeError } from "./errors.js";
+import { CommandError, ConnectionError, DELIBERATE, errorFor, NotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "./errors.js";
 import { Page } from "./page.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
 import { Transport } from "./transport.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
+import { pause } from "./wait.js";
+/** How long snapshot() waits, pause and capture together, unless told. */
+const SNAPSHOT_DEADLINE_MS = 10 * 60_000;
 const CHUNK = 1_048_576;
 /** Chunks of a large write in flight at once. Each chunk's reply waits on the
  * API and the guest, and the link idles while every chunk in flight waits:
@@ -380,7 +383,8 @@ export class Sandbox {
         this.#keepAlive?.();
         return deleteSandbox(this.#t, this.id, options);
     }
-    /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
+    /** Carries on a paused sandbox; for one with a time limit,
+     * `timeoutSeconds` is its new one. */
     async wake(options = {}) {
         const { timeoutSeconds, ...rest } = options;
         try {
@@ -391,13 +395,15 @@ export class Sandbox {
             // lease asked for, the refusal stands: it was not given.
             if (!(error instanceof RuntimeError) || error.code !== "not_paused" || timeoutSeconds)
                 throw error;
-            await this.refresh(pick(rest));
+            await this.refresh(requestOnly(rest));
             if (this.state !== "running" && this.state !== "starting")
                 throw error;
             return this;
         }
     }
-    /** More time before the lease ends (at most an hour ahead of now). */
+    /** More time before its time limit ends (at most an hour ahead of now). A
+     * sandbox with no time limit needs none: the call answers at once and
+     * changes nothing. */
     async extend(seconds, options = {}) {
         return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
     }
@@ -411,48 +417,51 @@ export class Sandbox {
      * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
      * volumes, environment, name and previews. Its processes restart, and
      * everything else on its old disk (sudo installs, apt packages, /etc) is
-     * lost, which `keep: "workspace"` says you know; snapshot it first to keep
-     * everything. A running sandbox is paused first. A switch that fails is
-     * undone (`switch_undone`), the sandbox on its old image with nothing lost.
-     * Charged as a wake. */
-    async switchImage(image, options) {
-        const { keep, ...rest } = options;
+     * lost; snapshot it first to keep everything. A running sandbox is paused
+     * first. A switch that fails is undone (`switch_undone`), the sandbox on
+     * its old image with nothing lost. Charged as a wake. `keep` is optional:
+     * "workspace" is the only value, and it is sent either way, so an API from
+     * before it was optional accepts the call too. */
+    async switchImage(image, options = {}) {
+        const { keep = "workspace", ...rest } = options;
         this.#keep(await this.#t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}:switch-image`,
             body: { image, keep },
             // A pause, two boots and the copy between them.
             wait: 120,
-            ...pick(rest),
+            ...requestOnly(rest),
         }));
         return this;
     }
     /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
      * whole disk, volumes, environment, name and previews stay, and its
-     * programs stop, which `restart: true` says you know (snapshot it first to
-     * keep its memory too). A running sandbox is paused, or stopped if it is
+     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
      * persistent, and comes back running at the new size on the same server; a
      * paused or stopped one is started. Memory bills on the new size from then.
      * Refused, with nothing changed, when the server has no room
      * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
-     * while a snapshot or fork of it is being taken. */
-    async resize(size, options) {
-        const { restart, ...rest } = options;
+     * while a snapshot or fork of it is being taken. `restart` is optional:
+     * true is the only value, and it is sent either way, so an API from before
+     * it was optional accepts the call too. */
+    async resize(size, options = {}) {
+        const { restart = true, ...rest } = options;
         this.#keep(await this.#t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}:resize`,
             body: { ...size, restart },
             // A pause or stop and a cold boot.
             wait: 120,
-            ...pick(rest),
+            ...requestOnly(rest),
         }));
         return this;
     }
-    /** Keeps a running sandbox's lease ahead of now, in the background, until
-     * stop() or the returned function ends it: every `everySeconds` (60) it
-     * extends the lease so that `marginSeconds` (600) remain, never more than
-     * the hour ahead the API allows. Running time is billed as it is used, as
-     * for any extension. A paused sandbox is left paused (a request wakes it,
+    /** Keeps a sandbox with a time limit running past it, in the background,
+     * until stop() or the returned function ends it: every `everySeconds` (60)
+     * it extends the limit so that `marginSeconds` (600) remain, never more
+     * than the hour ahead the API allows. A sandbox with no time limit
+     * (`endsAt` null) needs none, and is only watched. Running time is billed
+     * as it is used. A paused sandbox is left paused (a request wakes it,
      * unless autoWake is off); a stopped one ends the loop. It does not keep a
      * Node or Bun process alive by itself. */
     keepAlive(options = {}) {
@@ -475,8 +484,9 @@ export class Sandbox {
                 await this.refresh();
                 if (this.state === "stopped" || this.state === "stopping")
                     return end();
-                if (this.state === "running") {
-                    const left = (Date.parse(this.info.expiresAt) - Date.now()) / 1000;
+                // No time limit: nothing to extend (an older server sends no endsAt).
+                if (this.state === "running" && this.info.endsAt !== null) {
+                    const left = (Date.parse(this.info.endsAt ?? this.info.expiresAt) - Date.now()) / 1000;
                     const need = Math.ceil(margin - left);
                     if (need >= 1)
                         await this.extend(Math.min(3600, need));
@@ -500,16 +510,34 @@ export class Sandbox {
     }
     /** Keeps this sandbox's whole machine (files, memory, running processes) as
      * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. */
+     * the moment it takes, then woken; a paused one stays paused. Past
+     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
+     * the error names the snapshot. */
     async snapshot(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
         if (body.mode !== undefined && body.mode !== "memory" && body.mode !== "disk")
             throw new TypeError("Snapshot mode must be memory or disk.");
         signal?.throwIfAborted();
-        const until = performance.now() + Math.min(timeoutMs && timeoutMs > 0 ? timeoutMs : 60_000, 60_000);
+        // One minute, whatever `timeoutMs` said, was too short: pausing a busy
+        // 16 vCPU, 32 GiB sandbox writes its memory out first (4 October 2026).
+        const until = performance.now() + (timeoutMs && timeoutMs > 0 ? timeoutMs : SNAPSHOT_DEADLINE_MS);
+        let running = false;
+        /** The capture in progress, once the server has one. */
+        let capturing;
+        let late = false;
         const request = () => {
             signal?.throwIfAborted();
             const left = Math.ceil(until - performance.now());
+            if (left <= 0 && capturing) {
+                late = true;
+                throw new RuntimeError({
+                    code: "snapshot_timeout",
+                    status: 0,
+                    message: `Snapshot ${capturing} was still capturing at the deadline.${running ? " The sandbox stays paused until it ends: waking it now would fail the capture." : ""}`,
+                    hint: `Wait until runtime.snapshots.get("${capturing}") is ready${running ? ", then wake the sandbox" : ""}, or pass a longer timeoutMs.`,
+                    details: { snapshotId: capturing, sourceSandboxId: this.id },
+                });
+            }
             if (left <= 0)
                 throw new RuntimeError({
                     code: "snapshot_timeout",
@@ -526,7 +554,7 @@ export class Sandbox {
             await this.waitFor("running", request());
         else if (this.state === "pausing")
             await this.waitFor("paused", request());
-        const running = this.state === "running";
+        running = this.state === "running";
         // Check before entering cleanup: an abort during refresh must not pause or wake.
         const pauseOptions = running ? request() : undefined;
         let captured;
@@ -547,14 +575,8 @@ export class Sandbox {
             // Prefer: wait is bounded on the server. A capture still in progress
             // must keep its source paused, or the worker refuses it after we wake.
             while (snapshot.state === "capturing") {
-                signal?.throwIfAborted();
-                if (performance.now() >= until)
-                    throw new RuntimeError({
-                        code: "snapshot_timeout",
-                        status: 0,
-                        message: "Snapshot capture did not finish within one minute.",
-                        details: { snapshotId: snapshot.id },
-                    });
+                capturing = snapshot.id;
+                request();
                 await new Promise((resolve) => setTimeout(resolve, 200));
                 snapshot = await this.#t.json({
                     method: "GET",
@@ -581,8 +603,13 @@ export class Sandbox {
         catch (error) {
             failed = true;
             primary = error;
+            // A request cut off by the deadline mid-capture is late all the same.
+            if (capturing && performance.now() >= until)
+                late = true;
         }
-        if (running) {
+        // A capture still running needs its source paused: the worker fails one
+        // whose source woke. The timeout says so and leaves the wake to the caller.
+        if (running && !late) {
             try {
                 await this.wake();
             }
@@ -617,11 +644,7 @@ export class Sandbox {
             path: `/v1/sandboxes/${enc(this.id)}:fork`,
             body,
             wait: 60,
-            ...pick({
-                ...(idempotencyKey ? { idempotencyKey } : {}),
-                ...(signal ? { signal } : {}),
-                ...(timeoutMs ? { timeoutMs } : {}),
-            }),
+            ...requestOnly({ idempotencyKey, signal, timeoutMs }),
         });
         const sandboxes = reply.sandboxes.map((info) => new Sandbox(this.#t, info));
         return options.count === undefined ? sandboxes[0] : sandboxes;
@@ -636,7 +659,7 @@ export class Sandbox {
             path: `/v1/sandboxes/${enc(this.id)}:${verb}`,
             body,
             wait: options.wait === false ? 0 : 60,
-            ...pick(options),
+            ...requestOnly(options),
         }));
         return this;
     }
@@ -660,13 +683,10 @@ class OutputCursor {
         this.cursor = cursor;
     }
     *pass(event) {
+        // As the status the API would have answered it, so a passing failure (a
+        // host restarting) is followed again rather than ending the read.
         if (event.type === "error")
-            throw new RuntimeError({
-                message: event.error.message,
-                code: event.error.code,
-                status: 0,
-                ...(event.error.requestId ? { requestId: event.error.requestId } : {}),
-            });
+            throw errorFor(event.error.status ?? 0, event);
         if (event.type === "truncated")
             this.cursor = Math.max(this.cursor, event.resumeAt);
         if (event.type === "stdout" || event.type === "stderr") {
@@ -697,11 +717,20 @@ function processBytes(encoded) {
         });
     }
 }
-/** A stream cut off by the network rather than refused by Runtime: worth
- * reconnecting to from the cursor. */
+/** A stream cut off by the network, or refused by a failure that passes by
+ * itself (a busy API, a 429, a host restarting), rather than refused for good:
+ * worth reconnecting to from the cursor. */
 function cutOff(error) {
-    return !(error instanceof RuntimeError) || error instanceof ConnectionError;
+    return (!(error instanceof RuntimeError) ||
+        error instanceof ConnectionError ||
+        ((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
+ * network blip or a busy API must not end the read of it. */
+const FOLLOW_OUTAGE_MS = 300_000;
 /** A streamed command keeps all its output unless the reader fell more than the
  * process's output buffer behind, which the server marks with a "truncated"
  * event. That event does not say which stream lost bytes, so both flags carry
@@ -709,6 +738,8 @@ function cutOff(error) {
 function truncation(dropped) {
     return { stdoutTruncated: dropped, stderrTruncated: dropped };
 }
+/** A command's request options: its `timeoutMs` is the command's own limit
+ * in the guest, so the call is given a minute more for the answer. */
 function pick(options) {
     return {
         ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
@@ -716,6 +747,15 @@ function pick(options) {
         ...(options.timeoutMs ? { timeoutMs: options.timeoutMs + 60_000 } : {}),
     };
 }
+/** Any other call's request options, as the caller gave them: `timeoutMs` is
+ * the call's whole deadline, and 0 turns it off. */
+function requestOnly(options) {
+    return {
+        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    };
+}
 /** Sessions: a token your backend makes and hands to your own frontend, which
  * then runs commands, reads and writes files and reaches previews in this one
  * sandbox directly, without proxying through your servers. A session cannot
@@ -804,12 +844,19 @@ export class Processes {
     /** Output events from `cursor` until the process exits, across stream slices. */
     async *follow(processId, options = {}) {
         const read = new OutputCursor(options.cursor ?? 0);
-        // Reconnections in a row that brought nothing: a stream that keeps
-        // closing without output or an exit is given up, not followed forever.
+        // Reconnections in a row that closed cleanly with nothing: a stream that
+        // keeps closing without output or an exit is given up, not followed
+        // forever.
         let idle = 0;
+        // Since when every reconnection has failed (a cut, a busy API, a host
+        // restarting). The command runs on regardless, so these are waited out
+        // for FOLLOW_OUTAGE_MS, with backoff, before the follow gives up.
+        let failingSince;
+        let failures = 0;
         for (;;) {
             const before = read.cursor;
             let resumed = false;
+            let failure;
             try {
                 for await (const event of this.t.events({
                     method: "GET",
@@ -831,8 +878,28 @@ export class Processes {
             catch (error) {
                 if (options.signal?.aborted || !cutOff(error))
                     throw error;
+                failure = error;
+            }
+            if (resumed || read.cursor > before) {
+                idle = failures = 0;
+                failingSince = undefined;
+                continue;
+            }
+            if (failure === undefined)
+                idle++;
+            else {
+                failingSince ??= performance.now();
+                if (performance.now() - failingSince >= FOLLOW_OUTAGE_MS)
+                    throw new ConnectionError({
+                        message: `Lost the output stream of process ${processId} for ${FOLLOW_OUTAGE_MS / 60_000} minutes; the command may still be running.`,
+                        code: "connection_error",
+                        status: 0,
+                        hint: `Follow it again: runtime sandbox logs ${this.sandboxId} ${processId} -f`,
+                        details: { sandboxId: this.sandboxId, processId },
+                        cause: failure,
+                    });
+                await pause(Math.min(5000, 50 * 2 ** failures++), options.signal);
             }
-            idle = resumed || read.cursor > before ? 0 : idle + 1;
             if (idle > 3)
                 throw new ConnectionError({
                     message: `The output stream of process ${processId} keeps closing before it ends.`,

package/dist/tar.d.ts

@@ -1,3 +1,5 @@
+/** One entry's header: the ustar block, after the long-name and long-link
+ * entries it needs. A whole number of 512-byte blocks. */
 export declare function tarHeader(name: string, size: number, mode: number, type: "0" | "5" | "2", link?: string, mtime?: number): Uint8Array;
 export declare function packDirectory(root: string): Promise<Uint8Array>;
 /** Unpacks a gzipped tar that arrives as a stream into `target`, refusing any

package/dist/tar.js

@@ -1,25 +1,35 @@
-import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
+import { chmod, copyFile, link as hardLink, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { createGunzip, gzipSync } from "node:zlib";
 import { RuntimeError } from "./errors.js";
-/* A small ustar writer and reader for directory uploads and downloads, so the
-   SDK needs no dependency. Regular files, directories and symbolic links;
-   names up to 255 bytes through the ustar prefix field. */
-export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
-    const block = new Uint8Array(512);
-    const bytes = new TextEncoder().encode(name);
-    let prefix = new Uint8Array();
-    let short = bytes;
-    if (bytes.length > 100) {
-        const split = name.lastIndexOf("/", 155);
-        if (split <= 0 || new TextEncoder().encode(name.slice(split + 1)).length > 100)
-            throw new Error(`Path too long for a tar archive: ${name}`);
-        prefix = new TextEncoder().encode(name.slice(0, split));
-        short = new TextEncoder().encode(name.slice(split + 1));
+/* A small tar writer and reader for directory uploads and downloads, so the
+   SDK needs no dependency. Regular files, directories, symbolic links and,
+   reading, hard links. A name that does not fit the ustar name and prefix
+   fields, or a link target longer than 100 bytes, travels in a GNU long-name
+   or long-link entry, which GNU tar, BusyBox tar and every SDK's reader
+   take; nothing is cut short. */
+const encode = (value) => new TextEncoder().encode(value);
+/** The ustar prefix and name of `name`, split at a slash so that each fits
+ * its field in bytes, or null when no split fits. */
+function ustarName(name) {
+    const bytes = encode(name);
+    if (bytes.length <= 100)
+        return { prefix: new Uint8Array(), short: bytes };
+    for (let split = name.lastIndexOf("/"); split > 0; split = name.lastIndexOf("/", split - 1)) {
+        const prefix = encode(name.slice(0, split));
+        const short = encode(name.slice(split + 1));
+        if (short.length > 100)
+            return null;
+        if (prefix.length <= 155)
+            return { prefix, short };
     }
+    return null;
+}
+function headerBlock(short, prefix, size, mode, type, link, mtime) {
+    const block = new Uint8Array(512);
     const put = (offset, value, length) => {
-        const data = typeof value === "string" ? new TextEncoder().encode(value) : value;
+        const data = typeof value === "string" ? encode(value) : value;
         block.set(data.subarray(0, length), offset);
     };
     const octal = (value, length) => value.toString(8).padStart(length - 1, "0") + "\0";
@@ -40,6 +50,29 @@ export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
     put(148, sum.toString(8).padStart(6, "0") + "\0 ", 8);
     return block;
 }
+/** A GNU long-name ("L") or long-link ("K") entry carrying `value`. */
+function longEntry(type, value) {
+    const size = value.length + 1;
+    const out = new Uint8Array(512 + Math.ceil(size / 512) * 512);
+    out.set(headerBlock(encode("././@LongLink"), new Uint8Array(), size, 0o644, type, new Uint8Array(), 0));
+    out.set(value, 512);
+    return out;
+}
+/** One entry's header: the ustar block, after the long-name and long-link
+ * entries it needs. A whole number of 512-byte blocks. */
+export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
+    const parts = [];
+    let fitted = ustarName(name);
+    if (!fitted) {
+        parts.push(longEntry("L", encode(name)));
+        fitted = { prefix: new Uint8Array(), short: encode(name).subarray(0, 100) };
+    }
+    const target = encode(link);
+    if (target.length > 100)
+        parts.push(longEntry("K", target));
+    parts.push(headerBlock(fitted.short, fitted.prefix, size, mode, type, target, mtime));
+    return parts.length === 1 ? parts[0] : new Uint8Array(Buffer.concat(parts));
+}
 export async function packDirectory(root) {
     const parts = [];
     const base = resolve(root);
@@ -352,8 +385,15 @@ async function unpackEntries(bytes, root, signal) {
             links.push({ destination, link, name });
             await skip();
         }
+        else if (type === "1") {
+            await hardLinkEntry(root, destination, link, name);
+            await skip();
+        }
         else if (type === "0" || type === "\0" || type === "7") {
             await mkdir(dirname(destination), { recursive: true });
+            // A name already unpacked may share its file with a hard link; writing
+            // through it would change the link's copy too.
+            await unlink(destination).catch(() => undefined);
             const file = await open(destination, "w");
             try {
                 for await (const part of bytes.take(size)) {
@@ -378,6 +418,24 @@ async function unpackEntries(bytes, root, signal) {
             await skip();
     }
 }
+/** A second name for a file the archive already carried: tar writes the
+ * first name as a file and every other as a hard link to it. The link names
+ * a plain file unpacked earlier in this archive, or the unpack fails; it
+ * never reaches outside, through a link or ahead. */
+async function hardLinkEntry(root, destination, link, name) {
+    const named = link.replace(/^(\.\/)+/, "");
+    const source = resolve(root, named);
+    if (!named || isAbsolute(named) || source === root || !source.startsWith(root + sep))
+        throw new Error(`Refusing an archive hard link that leads outside the target: ${name} -> ${link}`);
+    await assertPlain(root, source, named);
+    if (!(await lstat(source).catch(() => undefined))?.isFile())
+        throw new Error(`Refusing an archive hard link to a file it does not carry: ${name} -> ${link}`);
+    if (source === destination)
+        return;
+    await mkdir(dirname(destination), { recursive: true });
+    await unlink(destination).catch(() => undefined);
+    await hardLink(source, destination).catch(() => copyFile(source, destination));
+}
 /** Moves what was unpacked in `from` into `to`, merging with what is there
  * and replacing files of the same name, never through a link in `to`. */
 async function merge(from, to, root, signal) {

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.11.1";
 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,11 @@ 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";
+/** 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: {
+    path: string;
+};
 /** True in a Runtime sandbox. Node and Bun only; a browser is never one. */
 export declare function inRuntimeSandbox(marker?: string): boolean;
 /** Where calls go when no base URL is given: RUNTIME_API_URL, then Runtime's
@@ -51,17 +56,34 @@ export type Call = RequestOptions & {
     /** 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;
 };
+/** 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
+ * 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. */
+export declare const ANSWER_START_MS = 125000;
 export declare function apiOrigin(value: string): string;
 export declare function encodeQuery(query: Query | undefined): string;
+/** Connections a client holds at once by default: under the 64 one address
+ * may hold to the API (api.md, "Limits"), with room for a second client. */
+export declare const DEFAULT_MAX_CONNECTIONS = 48;
 /** One connection pool, one retry policy, one error shape for every product.
  * Node's and Bun's fetch keep connections alive, so a client reused across
  * calls pays TLS once. Over HTTP/1.1 every call in flight holds its own
- * connection, so a hundred calls at once would open a hundred, past what one
- * address may hold at the edge (64). Answers read whole are therefore held to
- * `maxConnections` at once and the rest queue here, reusing those
- * connections; streams and terminals are long-lived and do not wait behind
- * them. */
+ * connection, and one address may hold 64 to the API before it has used a
+ * valid key: past that the API's edge holds new ones back until one closes.
+ * So a client holds at most `maxConnections` at once,
+ * answers and streams together, and the rest queue here, first come first
+ * 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. */
 export declare class Transport {
     #private;
     readonly baseUrl: string;
@@ -73,9 +95,13 @@ export declare class Transport {
         baseUrl?: string;
         fetch?: typeof fetch;
         timeoutMs?: number;
+        /** How long one attempt waits for its answer to start before it is sent
+         * again under the same key. Default ANSWER_START_MS. */
+        answerStartMs?: number;
         maxRetries?: number;
         client?: string;
-        /** Calls read whole that may be in flight at once. Default 32. */
+        /** Connections held at once, answers and streams together; the rest
+         * wait their turn. Default 48: one address may hold 64 to the API. */
         maxConnections?: number;
         /** How long a create waits for room. Default 120 000; 0 fails at once. */
         waitForCapacityMs?: number;