withruntime 0.11.0 → 0.11.2

package/dist/blaxel/sandbox.js

@@ -71,10 +71,12 @@ export function durationMs(value) {
         total += Number(count) * unit[letter];
     return total;
 }
-/** The lease and the paused retention that honour Blaxel's TTL, expiry and
- * lifecycle: never deleted before Blaxel would delete it. A fixed deadline
- * within the hour is a lease that ends the sandbox; any other deadline keeps
- * a paused sandbox that many days, rounded up; none keeps it 365 days. */
+/** The time limit and the paused retention that honour Blaxel's TTL, expiry
+ * and lifecycle: never deleted before Blaxel would delete it. A fixed
+ * deadline within the hour is a time limit that ends the sandbox; past that
+ * there is none, so it runs while it works and pauses when idle (0300), and
+ * a paused sandbox is kept that many days, rounded up; none keeps it 365
+ * days. */
 export function lifetimeOf(asked) {
     const now = Date.now();
     const fixed = [];
@@ -110,7 +112,7 @@ export function lifetimeOf(asked) {
         : KEEP_DAYS;
     return soonest <= LEASE_SECONDS * 1000
         ? { timeoutSeconds: Math.max(60, Math.ceil(soonest / 1000)), onLeaseEnd: "stop", days }
-        : { timeoutSeconds: LEASE_SECONDS, onLeaseEnd: "pause", days };
+        : { onLeaseEnd: "pause", days };
 }
 /** Blaxel's network settings as Runtime's rules: allowed and forbidden
  * domains, from the network itself or from its proxy (Blaxel's current
@@ -402,9 +404,10 @@ export class SandboxInstance {
     }
     // ---- the live sandbox ---------------------------------------------------
     /** The sandbox, ready for a call. A paused one wakes by itself on the call
-     * (autoWake); one made without autoWake is woken here. A lease nearing its
-     * end is renewed in the background, so a sandbox in use is not paused by
-     * its lease. */
+     * (autoWake); one made without autoWake is woken here. A time limit
+     * nearing its end (an hour, on a sandbox made before 0300) is renewed in
+     * the background, so a sandbox in use is not paused by it; one with no
+     * time limit renews itself. */
     async #live() {
         if (this.#deleted)
             throw responseError(404, `Sandbox ${this.name} was deleted.`);
@@ -414,6 +417,8 @@ export class SandboxInstance {
             await this.#wake();
         else if (state === "running" &&
             rt.info.onLeaseEnd === "pause" &&
+            // One with no time limit renews itself (0300).
+            rt.info.endsAt !== null &&
             !this.#renewing &&
             Date.parse(rt.info.expiresAt) - Date.now() < RENEW_BELOW_MS)
             this.#renewing = rt
@@ -461,7 +466,7 @@ export class SandboxInstance {
                     labels: { ...labels, [IDLE_PAUSE]: labels[IDLE_PAUSE] ?? String(current ?? 0) },
                 }))
                 : undefined,
-            rt.info.onLeaseEnd === "pause" && need >= 1
+            rt.info.onLeaseEnd === "pause" && rt.info.endsAt !== null && need >= 1
                 ? rt.extend(Math.ceil(need)).catch(() => undefined)
                 : undefined,
         ]);
@@ -518,8 +523,7 @@ export class SandboxInstance {
     // ---- create, get, list ---------------------------------------------------
     /** Creates a sandbox and answers once it runs. Blaxel's defaults: the base
      * image (Runtime's stock image) and 4096 MB, with vCPUs at one per 2048 MB.
-     * Funding is left to Runtime: the free trial while the account has trial
-     * time, then prepaid credit. A name another live sandbox holds is refused
+     * Funding is left to Runtime: the included usage first, then prepaid credit. A name another live sandbox holds is refused
      * with a 409, as in Blaxel. */
     static async create(sandbox, { createIfNotExist = false } = {}) {
         const config = configOf(sandbox);
@@ -545,7 +549,7 @@ export class SandboxInstance {
             vcpu: Math.min(MAX_VCPU, Math.max(1, Math.round(memory / MEMORY_PER_VCPU))),
             memoryMiB: memory,
             ...STANDBY,
-            timeoutSeconds: lifetime.timeoutSeconds,
+            ...(lifetime.timeoutSeconds === undefined ? {} : { timeoutSeconds: lifetime.timeoutSeconds }),
             onLeaseEnd: lifetime.onLeaseEnd,
             ...(config.name ? { name: config.name } : {}),
             labels,

package/dist/cli.d.ts

@@ -30,7 +30,7 @@ declare const kit: {
 };
 export type CliKit = typeof kit;
 export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;
-/** `runtime usage` for a person: the balance, the trial and what each kind
+/** `runtime usage` for a person: the balance, the included usage and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */
 /** One row per resource, for a spreadsheet: when it ran, how big it was, how

package/dist/cli.js

@@ -36,7 +36,7 @@ Account
                                                The account's audit log (owner or admin keys)
   sso                                          Single sign-on and SCIM directory sync (owner or
                                                admin keys); an owner changes it on the website
-  usage [--csv]                                Balance, trial time and charges; --csv, each resource
+  usage [--csv]                                Balance, included usage and charges; --csv, each resource
   usage export --since <UTC time> --until <UTC time>
                                                Every settlement in the range as CSV; --json, each page
   limits                                       Whether this key is read-only, and its daily spending limit
@@ -140,10 +140,10 @@ const SANDBOX_HELP = `runtime sandbox <command>
   resize <id> [--vcpu 2] [--memory 4096] --restart
                                               Change its size by a restart: the whole disk stays,
                                               programs stop (snapshot it first to keep memory)
-  extend <id> <seconds>                       More time before the lease ends
+  extend <id> <seconds>                       Move a time limit on (one with none needs nothing)
   update <id> [--name n] [--label k=v]... [--env K=V]... [--unset-env K]... [--idle-pause <seconds>] [--auto-wake on|off]
               [--persistent on|off] [--max-total-cost <usd>|none]
-                                              Change its settings; persistent keeps it running
+                                              Change its settings; persistent keeps it running until stopped
   snapshot <id> [--name n] [--retention days] Keep its whole machine; prints the snapshot id
   mount <id> <s3|r2|gcs>://<bucket>[/prefix] <path> [--secret NAME] [--region r]
         [--endpoint https://...] [--account-id id] [--read-only]
@@ -517,8 +517,18 @@ function describe(info) {
         ],
         ["funding", info.funding],
         ["region", info.region],
-        ["expires", info.expiresAt ?? "-"],
-        ["at lease end", info.onLeaseEnd ?? "-"],
+        // A sandbox with no time limit runs while it works (0300): endsAt is
+        // null. An older server sends no endsAt; its expiresAt was the end.
+        ["time limit", info.timeoutSeconds ? `${info.timeoutSeconds} s` : "none"],
+        [
+            "ends",
+            info.endsAt === null
+                ? info.state === "running"
+                    ? "when idle, stopped or out of credit"
+                    : "-"
+                : (info.endsAt ?? info.expiresAt ?? "-"),
+        ],
+        ["at its end", info.onLeaseEnd ?? "-"],
         // Why a sandbox is no longer running (troubleshooting.md, "A sandbox
         // stopped on its own"); `get` left both out until 30 September 2026.
         ...(info.pausedAt ? [["paused at", info.pausedAt]] : []),
@@ -685,16 +695,18 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         const [who, spend] = await Promise.all([rt.me(), rt.usage().catch(() => undefined)]);
         const trialLeft = spend?.trial ? spend.trial.availableMs / 3_600_000 : 0;
         const credit = spend ? BigInt(spend.available) : 0n;
+        // A pilot's sandboxes run on the pilot, before anything else and free.
         const funding = !spend
             ? undefined
             : [
+                ...(spend.pilot ? [pilotFunding(spend.pilot)] : []),
                 ...(trialLeft > 0
                     ? [
-                        `free trial, ${trialLeft.toLocaleString("en-US", { maximumFractionDigits: 1 })} hours left`,
+                        `included usage, ${trialLeft.toLocaleString("en-US", { maximumFractionDigits: 1 })} hours left without credit`,
                     ]
                     : []),
                 ...(credit > 0n ? [`${dollars(credit)} of credit`] : []),
-            ].join("; ") || "no trial time or credit left: runtime billing";
+            ].join("; ") || "no included usage or credit left: runtime billing";
         print(table([
             ["organization", who.orgName ? `${who.orgName} (${who.orgId})` : who.orgId],
             ...(who.role ? [["role", who.role]] : []),
@@ -755,7 +767,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "limits") {
-        const l = await (await client(env)).limits.get();
+        const rt = await client(env);
+        // The usage call only adds the pilot's line: a key that cannot read it
+        // still gets its limits.
+        const [l, spend] = await Promise.all([rt.limits.get(), rt.usage().catch(() => undefined)]);
         // As `usage` shows money: $0.0014 of spend read $0.00 until 30 September 2026.
         const usd = (micros) => dollars(micros);
         const access = l.access === "read"
@@ -773,7 +788,13 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             ],
             ["used, last 24 hours", usd(l.daily.usedMicros)],
             ...(l.daily.remainingMicros === null ? [] : [["left", usd(l.daily.remainingMicros)]]),
-            ...(l.trial ? [["free trial", trialLeft(l.trial)]] : []),
+            ...(l.trial ? [["free time", trialLeft(l.trial)]] : []),
+            ...(spend?.pilot
+                ? [
+                    ["pilot", pilotFunding(spend.pilot)],
+                    ["pilot sandbox hours", pilotLeft(spend.pilot)],
+                ]
+                : []),
         ]), l);
         return 0;
     }
@@ -1019,7 +1040,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     throw unknown("command", command, COMMANDS);
 }
-/** `runtime usage` for a person: the balance, the trial and what each kind
+/** `runtime usage` for a person: the balance, the included usage and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */
 /** One row per resource, for a spreadsheet: when it ran, how big it was, how
@@ -1071,10 +1092,45 @@ export function usageCsv(u) {
         .join(","));
     return [head.join(","), ...rows].join("\n");
 }
-/** The free trial's time left, as `runtime usage` and `runtime limits` say it. */
+/** Milliseconds as hours, to a tenth: "8,731.2". */
+const hours = (ms) => (ms / 3_600_000).toLocaleString("en-US", { maximumFractionDigits: 1 });
+/** The machine time left without credit, as `runtime usage` and `runtime
+ * limits` say it: this month's included usage, as hours at 2 vCPU and 4 GiB,
+ * or for an account given free hours before 5 October 2026, those hours too. */
 function trialLeft(trial) {
-    const hours = (ms) => (ms / 3_600_000).toLocaleString("en-US", { maximumFractionDigits: 1 });
-    return `${hours(trial.availableMs)} of ${hours(trial.totalMs)} hours left${trial.reservedMs > 0 ? `, ${hours(trial.reservedMs)} held by running sandboxes` : ""}`;
+    const renews = trial.renewsAt ? `, renews ${trial.renewsAt.slice(0, 10)}` : "";
+    return trial.totalMs > 0
+        ? `${hours(trial.availableMs)} hours left (${hours(trial.totalMs)} free hours given before 5 October 2026, and the included usage${renews})`
+        : `${hours(trial.availableMs)} hours at 2 vCPU and 4 GiB left this month${renews}`;
+}
+/** This month's included usage, one row per product, as `runtime usage`
+ * says it. */
+function allowanceRows(allowances) {
+    const amount = (n) => n.toLocaleString("en-US", { maximumFractionDigits: 1 });
+    return allowances.map((a) => [
+        `included ${a.pool.replace(/-/g, " ")}`,
+        `${amount(a.left)} of ${amount(a.quantity)} ${a.unit}s left`,
+    ]);
+}
+/** What a pilot gives, as `runtime whoami` and `runtime limits` say it: the
+ * sandboxes it runs free and until when, past which credit does not run
+ * them. */
+function pilotFunding(pilot) {
+    const at = (iso) => `${iso.slice(0, 16).replace("T", " ")} UTC`;
+    return `a pilot: up to ${pilot.sandboxes.toLocaleString("en-US")} sandboxes free, running until ${at(pilot.graceEndsAt)}; credit does not run it; to extend it, write to support`;
+}
+/** A pilot's sandbox hours left, as `runtime usage` says them. */
+function pilotLeft(pilot) {
+    const left = `${hours(pilot.leftMs)} of ${pilot.hours.toLocaleString("en-US")} left`;
+    // How long they last at the rate its sandboxes run now (an API before
+    // 0414 does not say how many run).
+    const running = pilot.running ?? 0;
+    const pace = running > 0
+        ? `; at ${running.toLocaleString("en-US")} running, about ${hours(pilot.leftMs / running)} hours`
+        : "";
+    return pilot.leftMs > 0
+        ? `${left}${pace}; new pilot sandboxes until ${pilot.endsAt.slice(0, 16).replace("T", " ")} UTC`
+        : "This pilot's sandbox hours are used.";
 }
 function usageSummary(u) {
     const micros = (value) => typeof value === "string" || typeof value === "number" || typeof value === "bigint"
@@ -1088,15 +1144,19 @@ function usageSummary(u) {
         // its own line, so "spent" reads as what was used.
         ["used", dollars(micros(u.spent) - takenBack)],
         ...(takenBack > 0n ? [["returned by refunds and disputes", dollars(takenBack)]] : []),
-        // Holds cover running sandboxes and the hour ahead of stored snapshots,
-        // images and volumes (pricing guide), so an account with nothing running
-        // can still show one.
-        ["held for running sandboxes and this hour's storage", dollars(micros(u.held))],
+        // What running sandboxes and the hour ahead of stored snapshots, images
+        // and volumes are about to use, so an account with nothing running can
+        // still show some. Said without "held": no guide teaches holds.
+        ["set aside for running sandboxes and this hour's storage", dollars(micros(u.held))],
     ];
     if (micros(u.expired) > 0n)
         rows.push(["expired or taken back", dollars(micros(u.expired))]);
     if (u.trial)
-        rows.push(["free trial", trialLeft(u.trial)]);
+        rows.push(["free time", trialLeft(u.trial)]);
+    if (u.allowances)
+        rows.push(...allowanceRows(u.allowances));
+    if (u.pilot)
+        rows.push(["pilot sandbox hours", pilotLeft(u.pilot)]);
     if (u.outbound) {
         const gib = (bytes) => `${(bytes / 1_073_741_824).toLocaleString("en-US", { maximumFractionDigits: 1 })} GiB`;
         const left = Math.max(0, u.outbound.allowanceBytes - u.outbound.freeBytes);
@@ -1106,7 +1166,15 @@ function usageSummary(u) {
         ]);
     }
     const kinds = new Map();
-    for (const resource of u.resources ?? []) {
+    // Every resource, by kind, from an API that totals them (6 October 2026);
+    // an older one sends only its hundred newest, counted here.
+    for (const k of u.kinds ?? [])
+        kinds.set(k.kind, {
+            count: k.resources,
+            charged: micros(k.chargedMicros),
+            held: micros(k.heldMicros),
+        });
+    for (const resource of u.kinds ? [] : (u.resources ?? [])) {
         const kind = typeof resource.kind === "string" ? resource.kind : "other";
         const entry = kinds.get(kind) ?? { count: 0, charged: 0n, held: 0n };
         entry.count++;
@@ -1285,7 +1353,7 @@ function runningTime(seconds) {
     });
     return `${shown} ${unit}${shown === "1" ? "" : "s"}`;
 }
-/** The sandboxes the free trial paid for, said beside what was priced. */
+/** The sandboxes free usage paid for, said beside what was priced. */
 function trialNote(trial, all, trialSeconds) {
     if (!trial)
         return "";
@@ -1294,7 +1362,7 @@ function trialNote(trial, all, trialSeconds) {
             ? "It"
             : "All of them"
         : `${trial} of them, ${runningTime(trialSeconds)} of that time,`;
-    return ` ${which} ran on the free trial, which charged nothing; Runtime's side prices ${trial === 1 ? "it" : "them"} at the standard rates, what the same work costs on paid credit.`;
+    return ` ${which} ran on free usage, which charged nothing; Runtime's side prices ${trial === 1 ? "it" : "them"} at the standard rates, what the same work costs on paid credit.`;
 }
 async function switching(command, argv, env, out) {
     const args = parse(argv, [], command === "compare" ? ["from", "days"] : ["from"]);
@@ -1474,11 +1542,13 @@ async function sandbox(argv, env, out) {
                 s.state,
                 `${s.info.vcpu}/${s.info.memoryMiB}`,
                 s.info.funding,
-                s.info.expiresAt ?? "-",
+                // When it stops or pauses by itself (0381): its time limit's end, or
+                // "-" when it never will. An older server sends no endsAt.
+                (s.info.endsAt === undefined ? s.info.expiresAt : s.info.endsAt) ?? "-",
             ]);
             print([
                 rows.length
-                    ? table([["ID", "NAME", "STATE", "CPU/MIB", "FUNDING", "EXPIRES"], ...rows])
+                    ? table([["ID", "NAME", "STATE", "CPU/MIB", "FUNDING", "ENDS"], ...rows])
                     : stopped
                         ? "No live sandboxes."
                         : "No sandboxes. Create one: runtime sandbox create",
@@ -1704,7 +1774,9 @@ async function sandbox(argv, env, out) {
             const sbx = await get(rest[0]);
             const seconds = Number(need(rest[1], "seconds, e.g. runtime sandbox extend <id> 600"));
             await sbx.extend(seconds);
-            print(`${sbx.id} now ends at ${sbx.info.expiresAt}`, sbx.info);
+            print(sbx.info.endsAt === null
+                ? `${sbx.id} has no time limit: it runs while it works, so nothing was extended`
+                : `${sbx.id} now ends at ${sbx.info.endsAt ?? sbx.info.expiresAt}`, sbx.info);
             return 0;
         }
         case "exec": {
@@ -2783,8 +2855,8 @@ read = readSecret) {
 }
 const JOB_HELP = `runtime job <command>
 
-  A job runs a command in a fresh sandbox, once or on a schedule. Each run is a
-  paid sandbox billed at the sandbox rates; the trial's hours do not fund jobs.
+  A job runs a command in a fresh sandbox, once or on a schedule. Each run spends
+  the included usage first, then credit at the sandbox rates.
 
   create <name> (--cron "<min hour day month weekday>" [--timezone Europe/Berlin] | --at <time|now>)
          [--vcpu 2] [--memory 4096] [--disk 4096] [--cpu shared|reserved] [--cpu-floor <thousandths>]
@@ -3230,7 +3302,7 @@ const CREATE_FLAGS = [
     "get-or-create",
 ];
 /** Says on standard error, once for each reason, why a create has not
- * answered yet: it is waiting for a trial slot or room, which can take up to
+ * answered yet: it is waiting for a slot without credit or room, which can take up to
  * two minutes, and silence reads as a hang. */
 function waiting(out) {
     const said = new Set();

package/dist/client.d.ts

@@ -1,11 +1,11 @@
-import { RuntimeError } from "./errors.js";
-import type { Page } from "./page.js";
 import { type ClientExtensions } from "./products/index.js";
 import { usageExport as makeUsageExport } from "./products/observability.js";
+import { Machines } from "./machine.js";
 import { Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
 import { Transport, type RequestOptions } from "./transport.js";
 import type { CreateSandbox, DeletedSandbox, FeedbackKind, SandboxInfo, Usage } from "./types.js";
+export type { CreateOptions } from "./machine.js";
 export type RuntimeOptions = {
     /** Default: the RUNTIME_API_KEY environment variable. */
     apiKey?: string;
@@ -16,11 +16,18 @@ export type RuntimeOptions = {
     timeoutMs?: number;
     /** Retries of transport failures, 429, 502, 503 and 504. Default 4. */
     maxRetries?: number;
-    /** Calls in flight at once; more wait their turn and reuse connections. Default 32. */
+    /** Connections held at once, calls and streams (a command's output, a
+     * download) together; more wait their turn, first come first served, and
+     * reuse them. Default 48: one address may hold 64 connections to the API
+     * before it has used a valid key. 8 are kept for calls whatever the
+     * streams hold. */
     maxConnections?: number;
+    /** Called each time a call has to wait for one of those connections: an
+     * adapter warns with it, once, that its caller is being held back. */
+    onQueued?: (maxConnections: number) => void;
     /** How long `sandboxes.create` keeps retrying, with the same key and input,
-     * when the trial's slots, the account's quota or the region is full
-     * (trial_busy, quota_exceeded, no_capacity and the like). Default 120 000
+     * when the slots without credit, the account's quota or the region is full
+     * (no_credit_running_limit, quota_exceeded, no_capacity and the like). Default 120 000
      * (two minutes); 0 fails at once. The refusal is thrown as it came when the
      * wait runs out. */
     waitForCapacityMs?: number;
@@ -53,8 +60,8 @@ export declare class Runtime {
         /** The role of the member who made this key: owner, admin, developer or billing. */
         role?: string | null;
     }>;
-    /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
-    /** Credit, holds, trial time and per-resource charges. */
+    /** Balance, holds, free time and per-resource charges, in integer microdollars. */
+    /** Credit, holds, free time and per-resource charges. */
     usage(options?: RequestOptions): Promise<Usage>;
     /** This account's authenticated API answers, in hourly windows. Counts are
      * exact decimal strings, and an empty window has a null error percentage.
@@ -76,60 +83,9 @@ export declare class Runtime {
         }>;
     }>;
 }
-/** How `sandboxes.create` waits when every trial slot, the account's quota or
- * the region is full. */
-export type CreateOptions = RequestOptions & {
-    /** How long to keep retrying a refusal that clears by itself. Default: the
-     * client's, two minutes; 0 fails at once. */
-    waitForCapacityMs?: number;
-    /** Called before each wait, with the refusal and the milliseconds until the
-     * next try: to tell a person why nothing has happened yet. */
-    onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
-};
-export declare class Sandboxes {
-    private readonly t;
+/** `runtime.sandboxes`: the sandbox product of the machine engine. */
+export declare class Sandboxes extends Machines<Sandbox, SandboxInfo, CreateSandbox, DeletedSandbox> {
     constructor(t: Transport);
-    /** Creates a sandbox and waits until it is running. Every field is optional:
-     * with none you get the free trial while it lasts, the default region and a
-     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
-     * When every trial slot or the account's quota is taken, it waits for one to
-     * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
-    create(input?: CreateSandbox & {
-        wait?: boolean;
-    }, options?: CreateOptions): Promise<Sandbox>;
-    /** The sandbox named `name` in this account, ready to use: running as it
-     * is, woken if it is paused, restarted if it is stopped and persistent, or
-     * created with `input` when no sandbox has the name. `sandbox.info.reused`
-     * says which. The other fields apply only when it is created. */
-    getOrCreate(name: string, input?: Omit<CreateSandbox, "name" | "getOrCreate"> & {
-        wait?: boolean;
-    }, options?: CreateOptions): Promise<Sandbox>;
-    get(id: string, options?: RequestOptions): Promise<Sandbox>;
-    /** Deletes a sandbox for good, by id, without reading it first: see
-     * `sandbox.delete()`. Deleting it again answers the same. */
-    delete(id: string, options?: RequestOptions): Promise<DeletedSandbox>;
-    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
-     * Request options apply to the initial request and every subsequent page. */
-    list(filter?: {
-        state?: SandboxInfo["state"][];
-        includeStopped?: boolean;
-        /** Every label must match. */
-        labels?: Record<string, string>;
-        name?: string;
-        limit?: number;
-    }, options?: RequestOptions): Promise<Page<Sandbox>>;
-    /** Stops every live sandbox whose labels all match, eight at a time, and
-     * says which stopped and which failed; one failure does not stop the rest.
-     * Needs at least one label, so stopping everything is never one call. */
-    stopAll(filter: {
-        labels: Record<string, string>;
-    }, options?: RequestOptions): Promise<{
-        stopped: string[];
-        failed: {
-            id: string;
-            error: unknown;
-        }[];
-    }>;
 }
 export declare class FeedbackApi {
     private readonly t;

package/dist/client.js

@@ -1,10 +1,9 @@
-import { WAIT_FOR_TIMEOUT_SECONDS } from "./api-defaults.js";
-import { RuntimeError } from "./errors.js";
 import { clientFactories, clientProductAliases } from "./products/index.js";
 import { usageExport as makeUsageExport } from "./products/observability.js";
-import { Sandbox, deleteSandbox, sandboxPage } from "./sandbox.js";
+import { Machines } from "./machine.js";
+import { SANDBOXES, Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
-import { Transport, missingKey } from "./transport.js";
+import { DEFAULT_BASE_URL, Transport, missingKey } from "./transport.js";
 /** The key `runtime login` saved for this machine and this API origin, found
  * on first use. A constructor override must never receive another API's key. */
 const savedKey = async (apiOrigin) => {
@@ -30,15 +29,20 @@ export class Runtime {
     /** Date-range settlements, paged with exact charges and the server's CSV. */
     usageExport;
     constructor(options = {}) {
+        // The saved key is found by the origin as given, as `runtime login` saved
+        // it; the calls go where that origin is reachable from here, which in a
+        // sandbox is runtime.internal (transport.ts, `reachable`).
+        const origin = options.baseUrl || env("RUNTIME_API_URL") || DEFAULT_BASE_URL;
         this.transport = new Transport({
             // A key given, then RUNTIME_API_KEY, then (in Node and Bun) the key
             // `runtime login` saved for this machine, read on the first call.
-            apiKey: options.apiKey ?? env("RUNTIME_API_KEY") ?? (() => savedKey(this.transport.baseUrl)),
+            apiKey: options.apiKey ?? env("RUNTIME_API_KEY") ?? (() => savedKey(origin)),
             baseUrl: options.baseUrl ?? env("RUNTIME_API_URL"),
             ...(options.fetch ? { fetch: options.fetch } : {}),
             ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
             ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
             ...(options.maxConnections !== undefined ? { maxConnections: options.maxConnections } : {}),
+            ...(options.onQueued ? { onQueued: options.onQueued } : {}),
             ...(options.waitForCapacityMs !== undefined
                 ? { waitForCapacityMs: options.waitForCapacityMs }
                 : {}),
@@ -64,8 +68,8 @@ export class Runtime {
             ...options,
         });
     }
-    /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
-    /** Credit, holds, trial time and per-resource charges. */
+    /** Balance, holds, free time and per-resource charges, in integer microdollars. */
+    /** Credit, holds, free time and per-resource charges. */
     usage(options = {}) {
         return this.transport.json({
             method: "GET",
@@ -85,103 +89,10 @@ export class Runtime {
         });
     }
 }
-export class Sandboxes {
-    t;
+/** `runtime.sandboxes`: the sandbox product of the machine engine. */
+export class Sandboxes extends Machines {
     constructor(t) {
-        this.t = t;
-    }
-    /** Creates a sandbox and waits until it is running. Every field is optional:
-     * with none you get the free trial while it lasts, the default region and a
-     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
-     * When every trial slot or the account's quota is taken, it waits for one to
-     * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
-    async create(input = {}, options = {}) {
-        const { wait, ...body } = input;
-        const info = await this.t.json({
-            method: "POST",
-            path: "/v1/sandboxes",
-            body,
-            wait: wait === false ? 0 : 60,
-            ...options,
-            waitForCapacityMs: options.waitForCapacityMs ?? this.t.waitForCapacityMs,
-        });
-        const sandbox = new Sandbox(this.t, info);
-        if (wait !== false && info.state !== "running") {
-            await sandbox.waitFor("running", {
-                timeoutSeconds: WAIT_FOR_TIMEOUT_SECONDS,
-                signal: options.signal,
-                timeoutMs: options.timeoutMs,
-                idempotencyKey: options.idempotencyKey,
-            });
-            if (sandbox.state !== "running")
-                throw new RuntimeError({
-                    message: `Sandbox ${info.id} is ${sandbox.state}, not running.`,
-                    code: "start_failed",
-                    status: 0,
-                    hint: "Read it with runtime.sandboxes.get(id); stopReason says why.",
-                });
-        }
-        return sandbox;
-    }
-    /** The sandbox named `name` in this account, ready to use: running as it
-     * is, woken if it is paused, restarted if it is stopped and persistent, or
-     * created with `input` when no sandbox has the name. `sandbox.info.reused`
-     * says which. The other fields apply only when it is created. */
-    async getOrCreate(name, input = {}, options = {}) {
-        return this.create({ ...input, name, getOrCreate: true }, options);
-    }
-    async get(id, options = {}) {
-        return new Sandbox(this.t, await this.t.json({
-            method: "GET",
-            path: `/v1/sandboxes/${encodeURIComponent(id)}`,
-            ...options,
-        }));
-    }
-    /** Deletes a sandbox for good, by id, without reading it first: see
-     * `sandbox.delete()`. Deleting it again answers the same. */
-    delete(id, options = {}) {
-        return deleteSandbox(this.t, id, options);
-    }
-    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
-     * Request options apply to the initial request and every subsequent page. */
-    async list(filter = {}, options = {}) {
-        const query = {
-            ...(filter.state ? { state: filter.state } : {}),
-            ...(filter.includeStopped ? { includeStopped: true } : {}),
-            ...(filter.labels
-                ? { label: Object.entries(filter.labels).map(([k, v]) => `${k}:${v}`) }
-                : {}),
-            ...(filter.name ? { name: filter.name } : {}),
-            ...(filter.limit ? { limit: filter.limit } : {}),
-        };
-        return sandboxPage(this.t, await this.t.json({ method: "GET", path: "/v1/sandboxes", query, ...options }), query, options);
-    }
-    /** Stops every live sandbox whose labels all match, eight at a time, and
-     * says which stopped and which failed; one failure does not stop the rest.
-     * Needs at least one label, so stopping everything is never one call. */
-    async stopAll(filter, options = {}) {
-        if (!filter?.labels || Object.keys(filter.labels).length === 0)
-            throw new RuntimeError({
-                message: "stopAll needs at least one label to match.",
-                code: "invalid_request",
-                status: 0,
-                hint: "Stop one sandbox with sandbox.stop(), or label the ones to stop together.",
-            });
-        const live = await (await this.list({ labels: filter.labels, limit: 100 }, options)).toArray(Infinity);
-        // One key cannot name several stops: each stop makes its own.
-        const { idempotencyKey: _one, ...each } = options;
-        // In list order, oldest first, whichever finishes first.
-        const errors = new Array(live.length);
-        let next = 0;
-        const worker = async () => {
-            for (let at = next++; at < live.length; at = next++)
-                await live[at].stop(each).catch((error) => (errors[at] = error ?? "failed"));
-        };
-        await Promise.all(Array.from({ length: Math.min(8, live.length) }, worker));
-        return {
-            stopped: live.filter((_, at) => errors[at] === undefined).map((sbx) => sbx.id),
-            failed: live.flatMap((sbx, at) => errors[at] === undefined ? [] : [{ id: sbx.id, error: errors[at] }]),
-        };
+        super(SANDBOXES, t, (transport, info) => new Sandbox(transport, info));
     }
 }
 export class FeedbackApi {

package/dist/compat/files.js

@@ -63,10 +63,14 @@ export class GuestFiles {
         if (!overwrite) {
             // cp -n alone reports success when it skips a raced destination. Stage
             // privately, then publish without replacement and verify it moved.
+            // mv -n that skips succeeds before coreutils 9.2 and fails from it on
+            // (the guest's 9.4 says "not replacing"), so a skip is told by the
+            // staged copy still being there beside a destination; with none there,
+            // mv's own error stands.
             await checked(sandbox, [
                 "bash",
                 "-c",
-                'set -e; parent=$(dirname -- "$2"); stage="$parent/.runtime-copy-$4"; mkdir -m 700 -- "$stage"; trap \'rm -rf -- "$stage"\' EXIT; if [ "$3" = true ]; then cp -R -n -- "$1" "$stage/item"; else cp -n -- "$1" "$stage/item"; fi; mv -n -T -- "$stage/item" "$2"; if [ -e "$stage/item" ] || [ -L "$stage/item" ]; then printf "Destination exists: %s\\n" "$2" >&2; exit 73; fi',
+                'set -e; parent=$(dirname -- "$2"); stage="$parent/.runtime-copy-$4"; mkdir -m 700 -- "$stage"; trap \'rm -rf -- "$stage"\' EXIT; if [ "$3" = true ]; then cp -R -- "$1" "$stage/item"; else cp -- "$1" "$stage/item"; fi; mv -n -T -- "$stage/item" "$2" 2>"$stage/mv.err" || :; if [ -e "$stage/item" ] || [ -L "$stage/item" ]; then if [ -e "$2" ] || [ -L "$2" ]; then printf "Destination exists: %s\\n" "$2" >&2; exit 73; fi; cat -- "$stage/mv.err" >&2; exit 1; fi',
                 "bash",
                 this.path(from),
                 this.path(to),

package/dist/compat/lease.d.ts

@@ -5,6 +5,7 @@ export interface Leased {
     readonly state: string;
     readonly info: {
         expiresAt: string;
+        endsAt?: string | null;
     };
     extend(seconds: number): Promise<unknown>;
     refresh(): Promise<unknown>;