withruntime 0.8.4 → 0.10.0

package/dist/transport.js

@@ -1,17 +1,52 @@
-import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
+import { ConnectionError, DELIBERATE, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.8.4";
+export const VERSION = "0.10.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
+/** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
+ * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
+ * on that host, whose addresses a sandbox cannot reach directly. Plain HTTP
+ * 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 const SANDBOX_BASE_URL = "http://runtime.internal";
+/** Every Runtime sandbox has this file; guest-net.py keeps it current. */
+const SANDBOX_MARKER = "/run/runtime/environment.json";
+/** True in a Runtime sandbox. Node and Bun only; a browser is never one. */
+export function inRuntimeSandbox(marker = SANDBOX_MARKER) {
+    try {
+        const host = globalThis.process;
+        return host?.getBuiltinModule?.("node:fs")?.existsSync?.(marker) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Where calls go when no base URL is given: RUNTIME_API_URL, then Runtime's
+ * public API, which `reachable` turns into runtime.internal in a sandbox. */
+export function defaultBaseUrl(env = processEnv(), inSandbox = inRuntimeSandbox) {
+    return reachable(env.RUNTIME_API_URL || DEFAULT_BASE_URL, inSandbox);
+}
+/** The origin calls for `origin` are sent to from here. In a sandbox the
+ * public API is its own host, which it cannot reach directly, so calls for it
+ * go to runtime.internal; every other origin is left as it is. */
+export function reachable(origin, inSandbox = inRuntimeSandbox) {
+    return apiOrigin(origin) === DEFAULT_BASE_URL && inSandbox() ? SANDBOX_BASE_URL : origin;
+}
+function processEnv() {
+    return (globalThis.process?.env ?? {});
+}
 export function apiOrigin(value) {
     const url = new URL(value);
-    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    // runtime.internal is reserved and never resolves outside a sandbox, so a
+    // key sent there in plain HTTP never leaves the sandbox's host.
+    const local = ["localhost", "127.0.0.1", "[::1]", "runtime.internal"].includes(url.hostname);
     if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) ||
+        (url.hostname === "runtime.internal" && (url.protocol !== "http:" || url.port !== "")) ||
         url.username ||
         url.password ||
         url.search ||
         url.hash ||
         url.pathname !== "/")
-        throw new Error("Use an HTTPS API origin (or http://localhost for tests).");
+        throw new Error("Use an HTTPS API origin (or http://runtime.internal inside a sandbox, http://localhost for tests).");
     return url.origin;
 }
 export function encodeQuery(query) {
@@ -30,10 +65,6 @@ export function encodeQuery(query) {
     const text = params.toString();
     return text ? `?${text}` : "";
 }
-/** 503s that are a deliberate state, not a passing one: a product switched
- * off here, or paused on purpose. Retrying cannot change them, so they fail
- * at once with their own words. host_unavailable and busy are still retried. */
-const DELIBERATE = new Set(["fork_unavailable", "previews_unavailable", "unavailable"]);
 const sleep = (ms, signal) => new Promise((resolve, reject) => {
     const timer = setTimeout(done, ms);
     function done() {
@@ -49,18 +80,57 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
     else
         signal?.addEventListener("abort", abort, { once: true });
 });
+/** A credential lookup can finish independently, but must not keep its
+ * caller waiting after cancellation or hold that caller's queue slot. */
+function untilAborted(pending, signal) {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(abortReason(signal));
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener("abort", abort, { once: true });
+        pending.then((value) => {
+            signal.removeEventListener("abort", abort);
+            resolve(value);
+        }, (cause) => {
+            signal.removeEventListener("abort", abort);
+            reject(cause instanceof Error ? cause : new Error("Credential lookup failed.", { cause }));
+        });
+    });
+}
+function abortReason(signal) {
+    return signal?.reason instanceof Error
+        ? signal.reason
+        : new Error("Aborted", { cause: signal?.reason });
+}
 /** At most `maximum` holders at once; the rest wait their turn, first come
  * first served. */
 function slots(maximum) {
     let active = 0;
     const waiting = [];
     return {
-        async take() {
+        async take(signal) {
+            signal?.throwIfAborted();
             if (active < maximum) {
                 active++;
                 return;
             }
-            await new Promise((resolve) => waiting.push(resolve));
+            await new Promise((resolve, reject) => {
+                const ready = () => {
+                    signal?.removeEventListener("abort", abort);
+                    resolve();
+                };
+                const abort = () => {
+                    const at = waiting.indexOf(ready);
+                    if (at >= 0)
+                        waiting.splice(at, 1);
+                    reject(abortReason(signal));
+                };
+                waiting.push(ready);
+                signal?.addEventListener("abort", abort, { once: true });
+            });
         },
         give() {
             const next = waiting.shift();
@@ -99,7 +169,7 @@ export class Transport {
             throw missingKey();
         else
             this.#apiKey = options.apiKey;
-        this.baseUrl = apiOrigin(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.baseUrl = apiOrigin(options.baseUrl ? reachable(options.baseUrl) : defaultBaseUrl());
         // The environment's proxy (HTTPS_PROXY, NO_PROXY) on Node and Bun alike;
         // a fetch passed in is used as it is.
         this.#fetch = options.fetch ?? envFetch;
@@ -139,21 +209,71 @@ export class Transport {
      * the same key every time, and waits out a full house for a call that sets
      * waitForCapacityMs. */
     async send(call) {
-        const apiKey = await this.#key();
-        const write = call.method !== "GET";
-        const key = write ? (call.idempotencyKey ?? crypto.randomUUID()) : undefined;
-        // Time spent waiting for room is added to the call's deadline, not taken
-        // from it: once admitted, a create still has its whole timeoutMs.
+        return this.#send(this.#prepare(call), async (response) => response);
+    }
+    /** Start the deadline before waiting for a connection; keep one key and
+     * signal through every retry and the complete response body. */
+    #prepare(call) {
+        const timeoutMs = call.timeoutMs ?? this.#timeoutMs;
+        const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
+        const deadline = timeoutMs === 0 ? undefined : AbortSignal.timeout(timeoutMs + roomMs);
+        const signal = deadline
+            ? call.signal
+                ? AbortSignal.any([call.signal, deadline])
+                : deadline
+            : call.signal;
+        return {
+            ...call,
+            timeoutMs: 0,
+            ...(signal ? { signal } : {}),
+            ...(call.method !== "GET"
+                ? { idempotencyKey: call.idempotencyKey ?? crypto.randomUUID() }
+                : {}),
+        };
+    }
+    #connectionError(call, cause) {
+        const cancelled = call.signal?.aborted === true;
+        const route = this.#routed && !cancelled
+            ? describeRoute(`${this.baseUrl}${call.path}`, cause)
+            : { via: "" };
+        return new ConnectionError({
+            message: cancelled
+                ? "The call was cancelled or ran past its deadline."
+                : call.method !== "GET"
+                    ? `No answer from Runtime at ${this.baseUrl}${route.via}. The change may have happened; retrying with the same idempotencyKey is safe.`
+                    : `No answer from Runtime at ${this.baseUrl}${route.via}.`,
+            hint: cancelled
+                ? "Raise timeoutMs for a long call, or retry with the same idempotencyKey."
+                : (route.hint ?? "Check the network, and RUNTIME_API_URL if you set it."),
+            code: cancelled ? "timeout" : "connection_error",
+            status: 0,
+            ...(call.idempotencyKey ? { idempotencyKey: call.idempotencyKey } : {}),
+            cause,
+        });
+    }
+    async #send(call, consume) {
+        let apiKey;
+        try {
+            call.signal?.throwIfAborted();
+            apiKey = await untilAborted(this.#key(), call.signal);
+        }
+        catch (cause) {
+            if (call.signal?.aborted)
+                throw this.#connectionError(call, cause);
+            throw cause;
+        }
+        const key = call.method !== "GET" ? call.idempotencyKey : undefined;
         const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
         const roomUntil = performance.now() + roomMs;
         let roomAttempt = 0;
-        const deadline = AbortSignal.timeout((call.timeoutMs ?? this.#timeoutMs) + roomMs);
-        const signal = call.signal ? AbortSignal.any([call.signal, deadline]) : deadline;
+        const signal = call.signal;
         const url = `${this.baseUrl}${call.path}${encodeQuery(call.query)}`;
         const body = call.bytes ?? (call.body === undefined ? undefined : JSON.stringify(call.body));
         const retry = call.retry ?? true;
-        for (let attempt = 0;; attempt++) {
+        let attempt = 0;
+        for (;;) {
             let response;
+            let inCallback = false;
             // Called as a plain function: Cloudflare Workers' fetch throws "Illegal
             // invocation" when called as a method of another object (this.#fetch()).
             const send = this.#fetch;
@@ -161,6 +281,7 @@ export class Transport {
                 // "manual", not "error": Workers accept only "follow" and "manual".
                 // The API never redirects, so a redirect is refused here exactly as
                 // "error" refused it: thrown, retried, then a connection_error.
+                signal?.throwIfAborted();
                 response = await send(url, {
                     method: call.method,
                     headers: this.#headers(call, key, apiKey),
@@ -173,136 +294,132 @@ export class Transport {
                     await response.body?.cancel().catch(() => { });
                     throw new TypeError(`fetch failed: Runtime answered a redirect (${response.status}).`);
                 }
-            }
-            catch (cause) {
-                // A proxy variable the SDK cannot use: retrying cannot change it.
-                if (cause instanceof RuntimeError)
-                    throw cause;
-                if (signal.aborted || !retry || attempt >= this.#maxRetries) {
-                    const route = this.#routed && !signal.aborted ? describeRoute(url, cause) : { via: "" };
+                /* An answer that took longer than the API holds its headers (90 s)
+                 comes as a 200 sent early, and then its JSON: the answer, or
+                 {"error": ...} when the work failed after the status went
+                 (runtime-late-answer, api.md). Either way it is read here, so a
+                 failure is thrown as the error it is, never returned as a success. */
+                let late;
+                if (response.ok && response.headers.get("runtime-late-answer") === "true") {
+                    const text = await response.text();
+                    const failed = lateFailure(text);
+                    if (failed === undefined)
+                        return await consume(new Response(text, { headers: response.headers }));
+                    late = { status: failed, text };
+                }
+                else if (response.ok) {
+                    inCallback = true;
+                    call.onResponse?.(response);
+                    inCallback = false;
+                    return await consume(response);
+                }
+                const status = late?.status ?? response.status;
+                // Runtime never answers 407: it is a proxy refusing the tunnel, which
+                // Bun's fetch hands back as a response rather than an error.
+                if (response.status === 407 && this.#routed) {
+                    await response.body?.cancel();
+                    const route = describeRoute(url, 407);
                     throw new ConnectionError({
-                        message: signal.aborted
-                            ? "The call was cancelled or ran past its deadline."
-                            : write
-                                ? `No answer from Runtime at ${this.baseUrl}${route.via}. The change may have happened; retrying with the same idempotencyKey is safe.`
-                                : `No answer from Runtime at ${this.baseUrl}${route.via}.`,
-                        hint: signal.aborted
-                            ? "Raise timeoutMs for a long call, or retry with the same idempotencyKey."
-                            : (route.hint ?? "Check the network, and RUNTIME_API_URL if you set it."),
-                        code: signal.aborted ? "timeout" : "connection_error",
+                        message: `No answer from Runtime at ${this.baseUrl}${route.via}.`,
+                        code: "connection_error",
                         status: 0,
+                        ...(route.hint ? { hint: route.hint } : {}),
                         ...(key ? { idempotencyKey: key } : {}),
-                        cause,
                     });
                 }
-                await sleep(backoff(attempt), signal);
-                continue;
-            }
-            /* An answer that took longer than the API holds its headers (90 s)
-               comes as a 200 sent early, and then its JSON: the answer, or
-               {"error": ...} when the work failed after the status went
-               (runtime-late-answer, api.md). Either way it is read here, so a
-               failure is thrown as the error it is, never returned as a success. */
-            let late;
-            if (response.ok && response.headers.get("runtime-late-answer") === "true") {
-                const text = await response.text();
-                const failed = lateFailure(text);
-                if (failed === undefined)
-                    return new Response(text, { headers: response.headers });
-                late = { status: failed, text };
+                const text = late?.text ?? (await response.text());
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = { error: { message: text.slice(0, 500) || `HTTP ${status}` } };
+                }
+                const error = errorFor(status, parsed, key);
+                // A full house: wait for a slot or for room, then send the same call
+                // again. A request that can never fit (a fork of more copies than the
+                // trial runs) is not waited for.
+                if (retry &&
+                    roomMs > 0 &&
+                    WAITS_FOR_ROOM.has(error.code) &&
+                    error.details?.field !== "count") {
+                    const left = roomUntil - performance.now();
+                    if (left <= 0)
+                        throw error;
+                    const pause = Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++));
+                    inCallback = true;
+                    call.onCapacityWait?.(error, pause);
+                    inCallback = false;
+                    await sleep(pause, signal);
+                    continue;
+                }
+                const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
+                if (!retry || !retryable || attempt >= this.#maxRetries)
+                    throw error;
+                const header = Number(response.headers.get("retry-after"));
+                const wait = error.retryAfterMs ??
+                    (Number.isFinite(header) && header > 0 ? header * 1000 : backoff(attempt));
+                await sleep(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal);
             }
-            else if (response.ok)
-                return response;
-            const status = late?.status ?? response.status;
-            // Runtime never answers 407: it is a proxy refusing the tunnel, which
-            // Bun's fetch hands back as a response rather than an error.
-            if (response.status === 407 && this.#routed) {
-                await response.body?.cancel();
-                const route = describeRoute(url, 407);
-                throw new ConnectionError({
-                    message: `No answer from Runtime at ${this.baseUrl}${route.via}.`,
-                    code: "connection_error",
-                    status: 0,
-                    ...(route.hint ? { hint: route.hint } : {}),
-                    ...(key ? { idempotencyKey: key } : {}),
+            catch (cause) {
+                // Deliberate API refusals and unusable proxy settings cannot be
+                // fixed by repeating the request. Body failures are transport
+                // failures too: a write replays under its original key.
+                if (inCallback) {
+                    await response?.body?.cancel().catch(() => undefined);
+                    throw cause;
+                }
+                if (cause instanceof RuntimeError)
+                    throw cause;
+                if (signal?.aborted || !retry || attempt >= this.#maxRetries)
+                    throw this.#connectionError(call, cause);
+                await sleep(backoff(attempt), signal).catch((cause) => {
+                    throw this.#connectionError(call, cause);
                 });
             }
-            const text = late?.text ?? (await response.text());
-            let parsed = null;
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                parsed = { error: { message: text.slice(0, 500) || `HTTP ${status}` } };
-            }
-            const error = errorFor(status, parsed, key);
-            // A full house: wait for a slot or for room, then send the same call
-            // again. A request that can never fit (a fork of more copies than the
-            // trial runs) is not waited for.
-            if (retry &&
-                roomMs > 0 &&
-                WAITS_FOR_ROOM.has(error.code) &&
-                error.details?.field !== "count") {
-                const left = roomUntil - performance.now();
-                if (left <= 0)
-                    throw error;
-                const pause = Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++));
-                call.onCapacityWait?.(error, pause);
-                await sleep(pause, signal);
-                continue;
-            }
-            const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
-            if (!retry || !retryable || attempt >= this.#maxRetries)
-                throw error;
-            const header = Number(response.headers.get("retry-after"));
-            const wait = error.retryAfterMs ??
-                (Number.isFinite(header) && header > 0 ? header * 1000 : backoff(attempt));
-            await sleep(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal);
+            attempt++;
         }
     }
-    async json(call) {
-        await this.#slots.take();
+    async #queued(call, consume) {
         try {
-            const text = await (await this.send(call)).text();
-            return (text ? JSON.parse(text) : null);
+            await this.#slots.take(call.signal);
         }
-        finally {
-            this.#slots.give();
+        catch (cause) {
+            throw this.#connectionError(call, cause);
         }
-    }
-    async bytes(call) {
-        await this.#slots.take();
         try {
-            return new Uint8Array(await (await this.send(call)).arrayBuffer());
+            return await this.#send(call, consume);
         }
         finally {
             this.#slots.give();
         }
     }
-    /** A file's bytes, read whole and checked: the API says a body's length
-     * (x-content-length) and, when small, its SHA-256 (x-content-sha256) before
-     * sending it, and a body that falls short or differs is read again, twice,
-     * then refused. Nothing between the API and here reliably turns a stream
-     * cut part way into an error: on 25 September 2026 a 50 MB file came back
-     * 29 MB long, exit 0. */
+    async json(call) {
+        return this.#queued(this.#prepare(call), async (response) => {
+            const text = await response.text();
+            return (text ? JSON.parse(text) : null);
+        });
+    }
+    async bytes(call) {
+        return this.#queued(this.#prepare(call), async (response) => new Uint8Array(await response.arrayBuffer()));
+    }
+    /** A file's bytes, read whole and checked against its promised length and
+     * SHA-256. A short or different body is read again twice, within the same
+     * call deadline. */
     async fileBytes(call) {
+        call = this.#prepare(call);
         for (let attempt = 0;; attempt++) {
-            await this.#slots.take();
-            let failure;
-            try {
-                const response = await this.send(call);
+            const { body, problem } = await this.#queued(call, async (response) => {
                 const body = new Uint8Array(await response.arrayBuffer());
-                const problem = await checkBody(response.headers, body);
-                if (!problem)
-                    return body;
-                failure = problem;
-            }
-            finally {
-                this.#slots.give();
-            }
-            if (attempt >= 2 || call.signal?.aborted)
-                throw failure;
-            await sleep(backoff(attempt), call.signal);
+                return { body, problem: await checkBody(response.headers, body) };
+            });
+            if (!problem)
+                return body;
+            if (attempt >= 2)
+                throw problem;
+            await sleep(backoff(attempt), call.signal).catch((cause) => {
+                throw this.#connectionError(call, cause);
+            });
         }
     }
     /** A file's bytes as they arrive, for files too big to hold. The stream
@@ -336,12 +453,14 @@ export class Transport {
         let buffer = "";
         try {
             for (;;) {
+                call.signal?.throwIfAborted();
                 const { value, done } = await reader.read();
                 if (done)
                     break;
                 buffer += value;
                 let newline = buffer.indexOf("\n");
                 while (newline >= 0) {
+                    call.signal?.throwIfAborted();
                     const line = buffer.slice(0, newline).trim();
                     buffer = buffer.slice(newline + 1);
                     if (line)
@@ -349,6 +468,7 @@ export class Transport {
                     newline = buffer.indexOf("\n");
                 }
             }
+            call.signal?.throwIfAborted();
             if (buffer.trim())
                 yield JSON.parse(buffer);
         }

package/dist/types.d.ts

@@ -39,8 +39,14 @@ export type SandboxInfo = {
     heldMicros: number;
     simulated?: boolean;
     replayed?: boolean;
+    /** The names of its own environment variables (`env`), on a create, an
+     * update and a read of one sandbox. Values are never shown. */
+    envNames?: string[];
     /** On a create from an image with a start command: whether it started,
-     * became ready (readyMs), timed out, or exited first. */
+     * became ready (readyMs), timed out, or exited first. The create's answer
+     * alone carries it, and the Sandbox that create returned keeps it through
+     * later reads; `sandboxes.get` and `list` have none, because the API keeps
+     * no record of it. */
     start?: {
         state: "started" | "ready" | "timeout" | "exited" | "not_running";
         processId?: string;
@@ -54,6 +60,11 @@ export type SandboxInfo = {
 export type CreateSandbox = {
     name?: string;
     labels?: Record<string, string>;
+    /** Environment variables for every command, process, terminal, SSH session
+     * and the image's start command in this sandbox, under each command's own
+     * `env`. At most 32 variables and 32 KiB. Values are never shown again;
+     * answers list only `envNames`. Copies made by fork() keep them. */
+    env?: Record<string, string>;
     /** Omit to use the free trial while it lasts, then prepaid credit. */
     funding?: "trial" | "paid";
     region?: string;
@@ -103,6 +114,13 @@ export type CreateSandbox = {
         path: string;
         mode?: "rw" | "snapshot";
     }[];
+    /** Paid only: join your Tailscale network once running. `authKeySecret`
+     * names a job secret holding the auth key. */
+    tailscale?: {
+        authKeySecret: string;
+        hostname?: string;
+        tags?: string[];
+    };
 };
 export type CommandResult = {
     exitCode: number | null;
@@ -124,8 +142,8 @@ export type ExecOptions = {
     /** Default 60 000, or 24 hours when the output streams (onStdout, onStderr or
      * execStream); up to 24 hours. A timeout is a result (timedOut), not an error. */
     timeoutMs?: number;
-    onStdout?: (text: string) => void;
-    onStderr?: (text: string) => void;
+    onStdout?: (text: string) => unknown;
+    onStderr?: (text: string) => unknown;
     /** Throw CommandError when the exit code is not 0. */
     check?: boolean;
     signal?: AbortSignal;
@@ -141,6 +159,7 @@ export type ProcessInfo = {
     pty: boolean;
     stdinOpen: boolean;
     stdinOffset: number;
+    outputEncoding?: "utf8" | "base64";
     startedAt: string;
     endedAt: string | null;
     timeoutMs: number | null;
@@ -155,6 +174,7 @@ export type OutputEvent = {
     type: "stdout" | "stderr";
     data: string;
     offset: number;
+    base64?: string;
 } | {
     type: "exit";
     exitCode: number | null;
@@ -177,6 +197,13 @@ export type OutputEvent = {
         requestId?: string;
     };
 };
+export type BinaryOutputEvent = Exclude<OutputEvent, {
+    type: "stdout" | "stderr";
+}> | {
+    type: "stdout" | "stderr";
+    data: Uint8Array;
+    offset: number;
+};
 export type FileEntry = {
     name: string;
     path: string;
@@ -184,6 +211,11 @@ export type FileEntry = {
     size: number;
     mode: string;
     modifiedAt: string;
+    uid?: number;
+    gid?: number;
+    owner?: string;
+    group?: string;
+    symlinkTarget?: string;
 };
 /** GET /v1/usage. Money is integer microdollars in strings (1,000,000 = $1),
  * exact past 2^53: available = credited - spent - expired - held. */
@@ -226,6 +258,9 @@ export type FeedbackKind = "bug" | "missing_feature" | "competitor_gap" | "migra
 export type SandboxSettings = {
     name?: string;
     labels?: Record<string, string>;
+    /** Changes its environment: a value sets a variable, null removes it, and
+     * the rest stay. Commands started afterwards get the change. */
+    env?: Record<string, string | null>;
     /** A request to a paused sandbox wakes it. */
     autoWake?: boolean;
     /** Pause after this many seconds with no activity, counted from now; 0
@@ -236,6 +271,20 @@ export type SandboxSettings = {
     /** Lifetime cap in microdollars; null removes it. */
     maxTotalCostMicros?: number | null;
 };
+/** A deleted sandbox, as `delete()` answers it the first time and every time
+ * after. It reads nowhere else afterwards. */
+export type DeletedSandbox = {
+    id: string;
+    kind: "sandbox";
+    name: string | null;
+    labels: Record<string, string>;
+    status: "deleted";
+    /** "stopping" until its machine has stopped, usually well under a second. */
+    state: string;
+    deletedAt: string;
+    endedAt: string | null;
+    replayed?: boolean;
+};
 /** How `sandbox.keepAlive()` extends the lease. */
 export type KeepAliveOptions = {
     /** How often it checks, in seconds. Default 60. */

package/dist/vercel/command.d.ts

@@ -57,7 +57,7 @@ export declare class Command {
         signal?: AbortSignal;
     }): Promise<string>;
     /** Sends a signal, SIGTERM by default. */
-    kill(signal?: Signal, _opts?: {
+    kill(signal?: Signal, opts?: {
         abortSignal?: AbortSignal;
     }): Promise<void>;
 }