withruntime 0.11.0 → 0.11.2

package/dist/vercel/filesystem.js

@@ -119,7 +119,9 @@ export class FileSystem {
         const result = await this.#call(syscall, path, () => this.#ctx.run(argv, options));
         if (result.exitCode === 0)
             return result.stdout;
-        if (/No such file or directory/.test(result.stderr))
+        // dash, the sh of Debian and Ubuntu (a Runtime sandbox's), says "cannot
+        // create ...: Directory nonexistent" for a missing parent.
+        if (/No such file or directory|Directory nonexistent/.test(result.stderr))
             throw fsError("ENOENT", syscall, path);
         if (syscall === "unlink" || syscall === "rm")
             throw fsError("EACCES", syscall, path);

package/dist/vercel/sandbox.d.ts

@@ -9,7 +9,9 @@ import { Snapshot } from "./snapshot.js";
  * 2026). Runtime gives 2 vCPU and 4096 MiB. */
 export declare const DEFAULT_VCPUS = 2;
 export declare const MEMORY_MIB_PER_VCPU = 2048;
-/** Vercel's default timeout, 5 minutes. */
+/** Vercel's default timeout, 5 minutes. Not sent: a sandbox created with no
+ * timeout has no time limit on Runtime, running while it works and pausing
+ * when idle (0300). Kept for code that imports it. */
 export declare const DEFAULT_TIMEOUT_MS = 300000;
 /** Vercel's working directory; `/workspace` on Runtime. */
 export declare const HOME = "/vercel/sandbox";
@@ -40,9 +42,10 @@ export interface CreateSandboxParams extends Credentials {
     /** Shared at public HTTPS addresses (Runtime previews); `domain(port)`
      * answers from them. */
     ports?: number[];
-    /** Milliseconds. Default 300 000, at least 60 s. Over an hour, the
-     * sandbox's hour-long lease is extended while this object lives, up to the
-     * timeout (`sandbox.timeout`). */
+    /** Milliseconds, at least 60 s: when it stops. Leave it out for no time
+     * limit: it runs while it works and pauses when idle. Over an hour, the
+     * hour-long limit is extended while this object lives, up to the timeout
+     * (`sandbox.timeout`). */
     timeout?: number;
     resources?: {
         vcpus: number;
@@ -135,15 +138,16 @@ export declare class Sandbox {
     get cwd(): string;
     get status(): "pending" | "running" | "stopping" | "stopped";
     /** Milliseconds from the start of the session: the timeout given at
-     * create, with every extension, or the lease of a sandbox found by name. */
+     * create, with every extension, or the time limit of a sandbox found by
+     * name. 0 for one with no time limit, which runs while it works. */
     get timeout(): number;
     get expiresAt(): Date;
     get tags(): Record<string, string>;
     get sourceSnapshotId(): string | undefined;
     /** Creates a sandbox and waits until it runs. Vercel's defaults: 2 vCPUs,
-     * 2048 MiB per vCPU, a 5-minute timeout, persistent. Funding is left to
-     * Runtime: the free trial while the account has trial time, then prepaid
-     * credit, exactly as withruntime's own create. */
+     * 2048 MiB per vCPU, persistent. With no `timeout` it has no time limit: it
+     * runs while it works and pauses when idle. A `timeout` is kept as given. Funding is left to
+     * Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
     static create(params?: CreateSandboxParams): Promise<Sandbox & AsyncDisposable>;
     /** A sandbox by name (or Runtime id), woken if it is paused unless
      * `resume: false`. */
@@ -269,9 +273,10 @@ export declare class Sandbox {
         signal?: AbortSignal;
     }): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
-    /** Moves the end `duration` milliseconds later. The lease moves at once
-     * as far as it may (an hour ahead of now); past that it is extended while
-     * this object lives. */
+    /** Moves the end `duration` milliseconds later. The time limit moves at
+     * once as far as it may (an hour ahead of now); past that it is extended
+     * while this object lives. A sandbox with no time limit has no end to
+     * move, and nothing changes. */
     extendTimeout(duration: number, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -281,7 +286,8 @@ export declare class Sandbox {
     }): Promise<NetworkPolicy>;
     /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
      * `networkPolicy` and `snapshotExpiration`. Anything else is refused before
-     * anything changes. */
+     * anything changes. A `timeout` on a sandbox with no time limit changes
+     * nothing: it runs while it works. */
     update(params: {
         timeout?: number;
         ports?: number[];

package/dist/vercel/sandbox.js

@@ -13,7 +13,9 @@ import { Snapshot } from "./snapshot.js";
  * 2026). Runtime gives 2 vCPU and 4096 MiB. */
 export const DEFAULT_VCPUS = 2;
 export const MEMORY_MIB_PER_VCPU = 2048;
-/** Vercel's default timeout, 5 minutes. */
+/** Vercel's default timeout, 5 minutes. Not sent: a sandbox created with no
+ * timeout has no time limit on Runtime, running while it works and pausing
+ * when idle (0300). Kept for code that imports it. */
 export const DEFAULT_TIMEOUT_MS = 300_000;
 const MIN_LEASE_SECONDS = 60;
 /** Extend a long timeout's lease when less than this is left. */
@@ -235,7 +237,8 @@ export class Sandbox {
         return statusOf(this.#rt.state);
     }
     /** Milliseconds from the start of the session: the timeout given at
-     * create, with every extension, or the lease of a sandbox found by name. */
+     * create, with every extension, or the time limit of a sandbox found by
+     * name. 0 for one with no time limit, which runs while it works. */
     get timeout() {
         return this.#timeoutMs ?? this.#rt.info.timeoutSeconds * 1000;
     }
@@ -255,9 +258,9 @@ export class Sandbox {
     }
     // ---- create, get, list ------------------------------------------------
     /** Creates a sandbox and waits until it runs. Vercel's defaults: 2 vCPUs,
-     * 2048 MiB per vCPU, a 5-minute timeout, persistent. Funding is left to
-     * Runtime: the free trial while the account has trial time, then prepaid
-     * credit, exactly as withruntime's own create. */
+     * 2048 MiB per vCPU, persistent. With no `timeout` it has no time limit: it
+     * runs while it works and pauses when idle. A `timeout` is kept as given. Funding is left to
+     * Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
     static async create(params = {}) {
         refuseCreate(params);
         const client = clientFor(params);
@@ -268,7 +271,8 @@ export class Sandbox {
         const source = await guard(() => resolveImage(client, params));
         const input = {
             ...(source.snapshot ? {} : { vcpu: vcpus, memoryMiB: vcpus * MEMORY_MIB_PER_VCPU }),
-            timeoutSeconds: leaseSeconds(params.timeout ?? DEFAULT_TIMEOUT_MS),
+            // No timeout, no time limit: it runs while it works (0300).
+            ...(params.timeout === undefined ? {} : { timeoutSeconds: leaseSeconds(params.timeout) }),
             onLeaseEnd: persistent ? "pause" : "stop",
             ...(params.name ? { name: params.name } : {}),
             ...(params.tags && Object.keys(params.tags).length ? { labels: params.tags } : {}),
@@ -280,7 +284,7 @@ export class Sandbox {
         const sandbox = new Sandbox({
             runtime,
             client,
-            params: { ...params, persistent, timeout: params.timeout ?? DEFAULT_TIMEOUT_MS },
+            params: { ...params, persistent },
         });
         try {
             await sandbox.#setUp(params);
@@ -643,20 +647,25 @@ export class Sandbox {
             return;
         await this.stop().catch(() => undefined);
     }
-    /** Moves the end `duration` milliseconds later. The lease moves at once
-     * as far as it may (an hour ahead of now); past that it is extended while
-     * this object lives. */
+    /** Moves the end `duration` milliseconds later. The time limit moves at
+     * once as far as it may (an hour ahead of now); past that it is extended
+     * while this object lives. A sandbox with no time limit has no end to
+     * move, and nothing changes. */
     async extendTimeout(duration, opts = {}) {
         if (!Number.isFinite(duration) || duration <= 0)
             throw new RangeError(`duration must be a positive number of milliseconds, not ${duration}.`);
         await this.#withResume(async (runtime) => {
+            if (runtime.info.endsAt === null)
+                return;
             this.#timeoutMs = this.timeout + duration;
             await this.#leaseToTimeout(runtime, opts);
         }, opts);
     }
     /** Extends the lease now toward the timeout, an hour ahead at most. */
     async #leaseToTimeout(runtime, opts) {
-        const seconds = extensionSeconds(Date.parse(runtime.info.expiresAt), this.#until(), Date.now(), Infinity);
+        if (runtime.info.endsAt === null)
+            return;
+        const seconds = extensionSeconds(Date.parse(runtime.info.endsAt ?? runtime.info.expiresAt), this.#until(), Date.now(), Infinity);
         if (seconds >= 1)
             await runtime.extend(seconds, signalOf(opts));
     }
@@ -669,7 +678,8 @@ export class Sandbox {
     }
     /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
      * `networkPolicy` and `snapshotExpiration`. Anything else is refused before
-     * anything changes. */
+     * anything changes. A `timeout` on a sandbox with no time limit changes
+     * nothing: it runs while it works. */
     async update(params, opts = {}) {
         opts.signal?.throwIfAborted();
         const allowed = new Set(["timeout", "ports", "networkPolicy", "snapshotExpiration"]);
@@ -683,13 +693,15 @@ export class Sandbox {
         if (params.ports !== undefined)
             validatePorts(params.ports);
         const wanted = params.ports === undefined ? undefined : new Set(params.ports);
-        if (params.timeout !== undefined) {
+        // A sandbox with no time limit has none to change (0300).
+        if (params.timeout !== undefined && this.#rt.info.endsAt !== null) {
             const timeout = checkTimeout(params.timeout);
             // A shorter timeout is kept when the lease has not reached it yet: the
             // lease then stops being extended there. Runtime cannot end a lease
             // earlier than it was given.
-            if (this.#sessionStart + timeout < Date.parse(this.#rt.info.expiresAt) - 1000)
-                throw new NotSupportedError("A timeout that ends earlier than the current lease", `The lease runs to ${this.#rt.info.expiresAt}; call stop() when the work is done, or pass a timeout that ends after it.`);
+            const end = this.#rt.info.endsAt ?? this.#rt.info.expiresAt;
+            if (this.#sessionStart + timeout < Date.parse(end) - 1000)
+                throw new NotSupportedError("A timeout that ends earlier than the current lease", `The lease runs to ${end}; call stop() when the work is done, or pass a timeout that ends after it.`);
             const longer = timeout > this.timeout;
             this.#timeoutMs = timeout;
             if (longer)

package/dist/wait.d.ts

@@ -0,0 +1,12 @@
+import type { RequestOptions } from "./transport.js";
+/** A wait that an abort ends at once, rejecting with the signal's reason. */
+export declare function pause(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function abortError(signal: AbortSignal): Error;
+/**
+ * Calls `attempt` until it stops answering one of `codes` (something is
+ * still installing), within one budget: the caller's `timeoutMs`, else ten
+ * minutes. Each try gets what is left of it; a wait between tries ends at once
+ * on abort, and no try starts once the budget cannot cover the wait the API
+ * asked for: the installing error is thrown instead.
+ */
+export declare function whileInstalling<T>(codes: readonly string[], options: RequestOptions | undefined, attempt: (options: RequestOptions) => Promise<T>): Promise<T>;

package/dist/wait.js

@@ -0,0 +1,47 @@
+/** A wait that an abort ends at once, rejecting with the signal's reason. */
+export function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(abortError(signal));
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        function stop() {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        }
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}
+export function abortError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+}
+/** How long a start waits for a first install (Chromium, the desktop) when
+ * the caller sets no deadline. */
+const INSTALL_WAIT_MS = 600_000;
+/**
+ * Calls `attempt` until it stops answering one of `codes` (something is
+ * still installing), within one budget: the caller's `timeoutMs`, else ten
+ * minutes. Each try gets what is left of it; a wait between tries ends at once
+ * on abort, and no try starts once the budget cannot cover the wait the API
+ * asked for: the installing error is thrown instead.
+ */
+export async function whileInstalling(codes, options, attempt) {
+    const deadline = performance.now() + (options?.timeoutMs || INSTALL_WAIT_MS);
+    for (;;) {
+        if (options?.signal?.aborted)
+            throw abortError(options.signal);
+        const left = Math.max(1, Math.ceil(deadline - performance.now()));
+        try {
+            return await attempt(options?.timeoutMs ? { ...options, timeoutMs: left } : { ...options });
+        }
+        catch (error) {
+            const code = error.code;
+            const wait = error.retryAfterMs ?? 10_000;
+            if (!code || !codes.includes(code) || performance.now() + wait > deadline)
+                throw error;
+            await pause(wait, options?.signal);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",