withruntime 0.11.0 → 0.11.1

package/dist/products/desktop.js

@@ -1,3 +1,4 @@
+import { whileInstalling } from "../wait.js";
 /** `sbx.desktop`: a Linux desktop in the sandbox, driven like a person would.
  *
  *   const { streamUrl } = await sbx.desktop.start();
@@ -12,25 +13,10 @@ export function sandboxDesktop(t, sandbox) {
     const act = (body, options) => t.json({ method: "POST", path: `${base()}:act`, body, ...options });
     return {
         /** Starts the desktop. The first start in a sandbox installs it, which
-         * takes a minute or two; this waits for that (up to 10 minutes). */
+         * takes a minute or two; this waits for that (up to 10 minutes, or the
+         * call's timeoutMs). */
         async start(size = {}, options) {
-            const deadline = Date.now() + 600_000;
-            for (;;) {
-                try {
-                    return await t.json({
-                        method: "POST",
-                        path: `${base()}:start`,
-                        body: size,
-                        ...options,
-                    });
-                }
-                catch (error) {
-                    const code = error.code;
-                    if (code !== "desktop_installing" || Date.now() > deadline)
-                        throw error;
-                    await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 10_000));
-                }
-            }
+            return whileInstalling(["desktop_installing"], options, (request) => t.json({ method: "POST", path: `${base()}:start`, body: size, ...request }));
         },
         stop: (options) => t.json({ method: "POST", path: `${base()}:stop`, ...options }),
         /** PNG bytes, or JPEG with `format: "jpeg"`. */
@@ -53,18 +39,7 @@ export function sandboxDesktop(t, sandbox) {
         /** Opens `url` in Chromium on the desktop. Right after a sandbox's first
          * start, Chromium may still be installing; this waits for it. */
         async open(url, options) {
-            const deadline = Date.now() + 600_000;
-            for (;;) {
-                try {
-                    return await act({ action: "open", url }, options);
-                }
-                catch (error) {
-                    const code = error.code;
-                    if (code !== "desktop_installing" || Date.now() > deadline)
-                        throw error;
-                    await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 10_000));
-                }
-            }
+            return whileInstalling(["desktop_installing"], options, (request) => act({ action: "open", url }, request));
         },
         /** Starts a program on the desktop, detached. */
         launch: (argv, options) => act({ action: "launch", argv }, options),

package/dist/products/jobs.d.ts

@@ -1,7 +1,7 @@
 import { Page } from "../page.js";
 import type { RequestOptions, Transport } from "../transport.js";
-/** A run's sandbox. Every field has a default; a run is a paid sandbox of this
- * size, billed at the sandbox rates. */
+/** A run's sandbox. Every field has a default; a run is a sandbox of this
+ * size, on the trial's hours first and then on credit at the sandbox rates. */
 export type JobCompute = {
     region: string;
     vcpu: number;
@@ -147,11 +147,12 @@ export declare const JOB_DEFAULTS: {
     startSeconds: number;
 };
 /** A run is one sandbox: at most 16 vCPU and 64 GiB, a disk no smaller than
- * the system image, and paid for at most an hour. */
+ * the system image and no larger than 400 GiB, and paid for at most an hour. */
 export declare const JOB_LIMITS: {
     maxVcpu: number;
     maxMemoryMiB: number;
     minDiskMiB: number;
+    maxDiskMiB: number;
     maxDurationSeconds: number;
     maxAttempts: number;
     maxSecrets: number;
@@ -167,8 +168,9 @@ export declare function jobBody(input: CreateJob): Record<string, unknown>;
  * request id, and says no retry will change it. */
 export declare function switchedOff(product: string): (error: unknown) => never;
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a paid sandbox, charged at the sandbox rates through
- * the same holds and spending limits; the trial's hours do not fund jobs.
+ * schedule. Each run is a sandbox, paid for as one: from the free trial's
+ * hours first while the run fits the trial's size and count, then from credit
+ * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({
  *     name: "nightly-report",

package/dist/products/jobs.js

@@ -15,11 +15,12 @@ export const JOB_DEFAULTS = {
     startSeconds: JOB_START_SECONDS,
 };
 /** A run is one sandbox: at most 16 vCPU and 64 GiB, a disk no smaller than
- * the system image, and paid for at most an hour. */
+ * the system image and no larger than 400 GiB, and paid for at most an hour. */
 export const JOB_LIMITS = {
     maxVcpu: 16,
     maxMemoryMiB: 65_536,
     minDiskMiB: 3072,
+    maxDiskMiB: 409_600,
     maxDurationSeconds: 3600,
     maxAttempts: 5,
     maxSecrets: 16,
@@ -88,6 +89,8 @@ export function jobBody(input) {
         throw invalid(`A run's sandbox is at most ${JOB_LIMITS.maxVcpu} vCPU and ${JOB_LIMITS.maxMemoryMiB / 1024} GiB of memory; asked for ${compute.vcpu} vCPU and ${compute.memoryMiB} MiB.`, compute.vcpu > JOB_LIMITS.maxVcpu ? "compute.vcpu" : "compute.memoryMiB");
     if (compute.diskMiB < JOB_LIMITS.minDiskMiB)
         throw invalid(`A run's disk is at least ${JOB_LIMITS.minDiskMiB} MiB, the size of the system image; asked for ${compute.diskMiB}.`, "compute.diskMiB");
+    if (compute.diskMiB > JOB_LIMITS.maxDiskMiB)
+        throw invalid(`A run's disk is at most ${JOB_LIMITS.maxDiskMiB} MiB (${JOB_LIMITS.maxDiskMiB / 1024} GiB); asked for ${compute.diskMiB}.`, "compute.diskMiB");
     if (timeoutSeconds > compute.durationSeconds ||
         compute.durationSeconds > JOB_LIMITS.maxDurationSeconds)
         throw invalid(`timeoutSeconds (${timeoutSeconds}) must fit in the time a run is paid for (compute.durationSeconds ${compute.durationSeconds}), which is at most ${JOB_LIMITS.maxDurationSeconds} seconds.`, "timeoutSeconds");
@@ -125,8 +128,9 @@ export function switchedOff(product) {
     };
 }
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a paid sandbox, charged at the sandbox rates through
- * the same holds and spending limits; the trial's hours do not fund jobs.
+ * schedule. Each run is a sandbox, paid for as one: from the free trial's
+ * hours first while the run fits the trial's size and count, then from credit
+ * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({
  *     name: "nightly-report",

package/dist/products/mcp.d.ts

@@ -68,10 +68,14 @@ export declare function sandboxMcp(t: Transport, sandbox: Sandbox): {
     }, options?: RequestOptions) => Promise<McpGateway>;
     /** Their state, and fresh URLs. */
     get: (options?: RequestOptions) => Promise<McpGateway>;
-    /** Wait until every server is ready (or one failed). */
+    /** Wait until every server is ready (or one failed). Past `timeoutMs`
+     * (default ten minutes), the last state read; a status request still
+     * unanswered then is cut off at the deadline, and throws its timeout when
+     * no state was read at all. */
     ready(input?: {
         timeoutMs?: number;
         intervalMs?: number;
+        signal?: AbortSignal;
     }): Promise<McpGateway>;
     stop: (options?: RequestOptions) => Promise<{
         stopped: boolean;

package/dist/products/mcp.js

@@ -1,3 +1,4 @@
+import { pause } from "../wait.js";
 /** `runtime.mcp`: the catalog of MCP servers a sandbox can run. */
 export function mcp(t) {
     return {
@@ -20,16 +21,36 @@ export function sandboxMcp(t, sandbox) {
         start: (servers, input = {}, options) => t.json({ method: "POST", path: path(), body: { servers, ...input }, ...options }),
         /** Their state, and fresh URLs. */
         get: (options) => t.json({ method: "GET", path: path(), ...options }),
-        /** Wait until every server is ready (or one failed). */
+        /** Wait until every server is ready (or one failed). Past `timeoutMs`
+         * (default ten minutes), the last state read; a status request still
+         * unanswered then is cut off at the deadline, and throws its timeout when
+         * no state was read at all. */
         async ready(input = {}) {
-            const deadline = Date.now() + (input.timeoutMs ?? 600_000);
+            const deadline = performance.now() + (input.timeoutMs ?? 600_000);
+            let last;
             for (;;) {
-                const state = await t.json({ method: "GET", path: path() });
-                if (!state.running || state.servers.every((server) => server.status !== "installing"))
-                    return state;
-                if (Date.now() > deadline)
-                    return state;
-                await new Promise((resolve) => setTimeout(resolve, input.intervalMs ?? 2_000));
+                const left = Math.ceil(deadline - performance.now());
+                if (left <= 0 && last)
+                    return last;
+                try {
+                    last = await t.json({
+                        method: "GET",
+                        path: path(),
+                        timeoutMs: Math.max(1, left),
+                        ...(input.signal ? { signal: input.signal } : {}),
+                    });
+                }
+                catch (error) {
+                    if (last && !input.signal?.aborted && error.code === "timeout")
+                        return last;
+                    throw error;
+                }
+                if (!last.running || last.servers.every((server) => server.status !== "installing"))
+                    return last;
+                const rest = deadline - performance.now();
+                if (rest <= 0)
+                    return last;
+                await pause(Math.min(input.intervalMs ?? 2_000, rest), input.signal);
             }
         },
         stop: (options) => t.json({ method: "DELETE", path: path(), ...options }),

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

@@ -193,7 +193,7 @@ export type SetUpstreamProxy = {
  * `upstreamProxy`: after Runtime's own rules allow a connection, the host
  * reaches it with CONNECT through your proxy, so your proxy's controls and
  * logs apply. A proxy that refuses or cannot be reached fails the connection
- * (upstream-proxy-failed); nothing goes around it. Paid accounts only. */
+ * (upstream-proxy-failed); nothing goes around it. Needs a kept top-up. */
 export declare function network(t: Transport): {
     /** Your sandboxes reaching each other by name (`private-network.ts`). */
     private: {

package/dist/products/network-products.js

@@ -88,7 +88,7 @@ export function tunnel(t) {
  * `upstreamProxy`: after Runtime's own rules allow a connection, the host
  * reaches it with CONNECT through your proxy, so your proxy's controls and
  * logs apply. A proxy that refuses or cannot be reached fails the connection
- * (upstream-proxy-failed); nothing goes around it. Paid accounts only. */
+ * (upstream-proxy-failed); nothing goes around it. Needs a kept top-up. */
 export function network(t) {
     const path = "/v1/network/upstream-proxy";
     return {

package/dist/products/observability.d.ts

@@ -35,7 +35,7 @@ export type SandboxMetrics = {
     latest: MetricPoint | null;
     points: MetricPoint[];
 };
-export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted";
+export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted";
 /** An event as /v1/events lists it and a webhook delivers it. */
 export type RuntimeEvent = {
     id: string;

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

@@ -4,7 +4,7 @@ export type PrivateNetwork = {
     enabled: boolean;
     /** `sandbox.internal`. */
     suffix: string;
-    /** Whether this account may turn it on: paid accounts only. */
+    /** Whether this account may turn it on: it must have a kept top-up. */
     allowed: boolean;
     /** Why not, when `allowed` is false: `not_paid`, `revoked` or `suspended`. */
     why: string | null;

package/dist/products/secrets.d.ts

@@ -4,7 +4,7 @@ import type { RequestOptions, Transport } from "../transport.js";
  * absent) and `paths`, each exact (`/v1/chat/completions`) or a prefix ending
  * in `/*` (`/repos/acme/*`), written canonically: starting with `/`, no `.` or
  * `..` segments, no `;` or `\`, no encoded slash. A request whose path could be
- * read two ways gets no secret that has rules. Paid accounts only. */
+ * read two ways gets no secret that has rules. Needs credit on the account. */
 export type SecretRule = {
     methods?: string[];
     paths: string[];
@@ -37,7 +37,7 @@ export type SetSecret = {
     header?: string;
     /** With `header`: its value, `{value}` where the secret goes. Default `{value}`. */
     format?: string;
-    /** Only requests a rule allows carry the value. Paid accounts only. 1 to 16.
+    /** Only requests a rule allows carry the value. Needs credit on the account. 1 to 16.
      * Absent: every request to the hosts; replacing a secret without rules
      * clears them. */
     rules?: SecretRule[];

package/dist/runloop/index.js

@@ -172,8 +172,12 @@ export class Devboxes {
             vcpu: p.custom_cpu_cores ?? size?.[0],
             memoryMiB: p.custom_gb_memory ? p.custom_gb_memory * 1024 : size?.[1],
             diskMiB: p.custom_disk_size ? p.custom_disk_size * 1024 : size?.[2],
-            timeoutSeconds: p.keep_alive_time_seconds ?? 3600,
-            idlePauseSeconds: 0,
+            // keep_alive_time_seconds is the customer's limit, with no idle pause
+            // before it. None is no time limit (0300): it runs while it works and
+            // pauses when idle.
+            ...(p.keep_alive_time_seconds === undefined || p.keep_alive_time_seconds === null
+                ? {}
+                : { timeoutSeconds: p.keep_alive_time_seconds, idlePauseSeconds: 0 }),
             onLeaseEnd: "stop",
         }, input.environment_variables ?? undefined, async (sandbox) => {
             for (const [path, content] of Object.entries(input.file_mounts ?? {})) {

package/dist/sandbox.d.ts

@@ -105,12 +105,15 @@ export declare class Sandbox implements AsyncDisposable {
      * lists. Its snapshots, usage and audit entries stay. Deleting it again
      * answers the same. */
     delete(options?: RequestOptions): Promise<DeletedSandbox>;
-    /** 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. */
     wake(options?: RequestOptions & {
         wait?: boolean;
         timeoutSeconds?: number;
     }): Promise<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. */
     extend(seconds: number, options?: RequestOptions): Promise<this>;
     /** Changes its name, labels, automatic wake, idle pause or persistence;
      * fields left out stay as they are. `persistent: true` keeps it running
@@ -120,33 +123,36 @@ export declare class Sandbox implements AsyncDisposable {
      * 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. */
-    switchImage(image: string, options: RequestOptions & {
-        keep: "workspace";
+     * 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. */
+    switchImage(image: string, options?: RequestOptions & {
+        keep?: "workspace";
     }): Promise<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. */
+     * 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. */
     resize(size: {
         vcpu?: number;
         memoryMiB?: number;
-    }, options: RequestOptions & {
-        restart: true;
+    }, options?: RequestOptions & {
+        restart?: true;
     }): Promise<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?: KeepAliveOptions): () => void;
@@ -154,7 +160,9 @@ export declare class Sandbox implements AsyncDisposable {
     setRetention(days: number, options?: RequestOptions): Promise<this>;
     /** 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. */
     snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
     /** Copies of this sandbox as it is now (files, memory, running processes),
      * each its own sandbox, answered once they run. A running sandbox is paused