withruntime 0.11.0 → 0.11.2

package/dist/e2b/users.js

@@ -62,6 +62,28 @@ export function commandAs(user, script, cwdGiven) {
 export function shellAs(user, cwdGiven) {
     return commandAs(user, "exec /bin/bash -i -l", cwdGiven);
 }
+/** A running command as E2B lists it, from the command line Runtime keeps
+ * (its words joined by spaces, at most 256 characters): `/bin/bash -l -c
+ * <script>` for a command, `/bin/bash -i -l` for a PTY, as E2B starts them,
+ * whether it runs as the sandbox user or through `commandAs`. Anything else,
+ * started outside this package, is its first word and the rest. */
+export function listedAs(command) {
+    const wrapped = AS_USER.exec(command);
+    if (wrapped) {
+        const inner = command.slice(wrapped[0].length);
+        if (inner === "exec /bin/bash -i -l")
+            return { cmd: "/bin/bash", args: ["-i", "-l"] };
+        return { cmd: "/bin/bash", args: ["-l", "-c", inner] };
+    }
+    if (command.startsWith("bash -c "))
+        return { cmd: "/bin/bash", args: ["-l", "-c", command.slice(8)] };
+    if (command === "/bin/bash -i -l")
+        return { cmd: "/bin/bash", args: ["-i", "-l"] };
+    const [cmd = "", ...args] = command.split(" ");
+    return { cmd, args };
+}
+/** What `commandAs` puts before the script, as the joined command line shows it. */
+const AS_USER = /^sudo -n -E -H -u [^ ]+ -- \/bin\/bash -c (?:cd ~ 2>\/dev\/null\n)?/;
 /** One `sh -c` script as `user`, with its arguments passed apart, never
  * pasted into the script. */
 function script(user, text, ...args) {

package/dist/errors.d.ts

@@ -6,9 +6,15 @@
  * packages/cloud/src/api/respond.ts) and retrying cannot change them.
  * host_unavailable and busy pass, and are retried. */
 export declare const DELIBERATE: ReadonlySet<string>;
+/** Refusals that guarantee nothing ran: a sandbox running as many commands
+ * as it can (`guest_busy`), and the API's own limits, which answer before any
+ * work starts (`busy`, `rate_limited`). Sending such a call again is always
+ * safe, so the SDK does, with backoff, until the call's deadline (five
+ * minutes when it has none), however many retries it allows otherwise. */
+export declare const NOTHING_RAN: ReadonlySet<string>;
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: the trial's slots, an email domain's trial slots, the account's
- * quota and the region's capacity. `sandboxes.create` waits them out, retrying
+ * frees room: an account without credit's eight at once and its total, an
+ * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export declare const WAITS_FOR_ROOM: ReadonlySet<string>;
 export declare class RuntimeError extends Error {
@@ -32,8 +38,8 @@ export declare class RuntimeError extends Error {
         cause?: unknown;
     });
     /** Retrying this exact call (the SDK keeps the key) is safe and may work.
-     * True for no_capacity and trial_busy as well, which clear by themselves when
-     * a host frees room or a trial sandbox stops. `sandboxes.create` already
+     * True for no_capacity and no_credit_running_limit as well, which clear by themselves when
+     * a host frees room or a sandbox without credit stops. `sandboxes.create` already
      * waits for those (see `waitForCapacityMs`), so seeing one from a create
      * means the wait ran out or was switched off. */
     get retryable(): boolean;

package/dist/errors.js

@@ -16,16 +16,24 @@ export const DELIBERATE = new Set([
     "identity_unavailable",
     "env_unavailable",
 ]);
-/** Refusals that pass on their own: a host frees room, a trial slot frees. */
-const PASSING = new Set(["no_capacity", "trial_busy"]);
+/** Refusals that guarantee nothing ran: a sandbox running as many commands
+ * as it can (`guest_busy`), and the API's own limits, which answer before any
+ * work starts (`busy`, `rate_limited`). Sending such a call again is always
+ * safe, so the SDK does, with backoff, until the call's deadline (five
+ * minutes when it has none), however many retries it allows otherwise. */
+export const NOTHING_RAN = new Set(["guest_busy", "busy", "rate_limited"]);
+/** Refusals that pass on their own: a host frees room, a sandbox of an
+ * account without credit stops. */
+const PASSING = new Set(["no_capacity", "no_credit_running_limit", "no_credit_total_limit"]);
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: the trial's slots, an email domain's trial slots, the account's
- * quota and the region's capacity. `sandboxes.create` waits them out, retrying
+ * frees room: an account without credit's eight at once and its total, an
+ * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export const WAITS_FOR_ROOM = new Set([
-    "trial_busy",
-    "trial_domain_limit",
-    "trial_capacity",
+    "no_credit_running_limit",
+    "no_credit_total_limit",
+    "no_credit_domain_limit",
+    "no_credit_capacity_full",
     "quota_exceeded",
     "no_capacity",
     // A volume whose last sandbox is stopping: free within seconds.
@@ -57,14 +65,14 @@ export class RuntimeError extends Error {
             this.retryAfterMs = init.retryAfterMs;
     }
     /** Retrying this exact call (the SDK keeps the key) is safe and may work.
-     * True for no_capacity and trial_busy as well, which clear by themselves when
-     * a host frees room or a trial sandbox stops. `sandboxes.create` already
+     * True for no_capacity and no_credit_running_limit as well, which clear by themselves when
+     * a host frees room or a sandbox without credit stops. `sandboxes.create` already
      * waits for those (see `waitForCapacityMs`), so seeing one from a create
      * means the wait ran out or was switched off. */
     get retryable() {
         if (DELIBERATE.has(this.code))
             return false;
-        // A fork asking for more copies than the trial runs at once never fits.
+        // A fork asking for more copies than an account without credit runs at once never fits.
         if (PASSING.has(this.code))
             return this.details?.field !== "count";
         return [0, 429, 502, 503, 504].includes(this.status);

package/dist/identity.js

@@ -1,4 +1,5 @@
 import { RuntimeError } from "./errors.js";
+import { sandboxMarker } from "./transport.js";
 async function requestCredentials() {
     let url = process.env.RUNTIME_ID_TOKEN_REQUEST_URL;
     let token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
@@ -7,7 +8,7 @@ async function requestCredentials() {
         try {
             // Loaded here, so the SDK still loads where there is no file system.
             const { readFile } = await import("node:fs/promises");
-            const env = JSON.parse(await readFile("/run/runtime/environment.json", "utf8"));
+            const env = JSON.parse(await readFile(sandboxMarker.path, "utf8"));
             url = env.RUNTIME_ID_TOKEN_REQUEST_URL;
             token = env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
         }

package/dist/index.d.ts

@@ -35,7 +35,8 @@ export type * from "./types.js";
  * does the same with an explicit client. */
 export declare class Sandbox extends SandboxClass {
     /** Creates a sandbox (every field optional) and waits until it is running.
-     * `keepAlive: true` (or its options) extends its lease in the background
+     * With no `timeoutSeconds` it runs while it works and pauses when idle.
+     * `keepAlive: true` (or its options) carries one with a time limit past it
      * until you stop it; see `sandbox.keepAlive()`. */
     static create(input?: CreateSandbox & {
         wait?: boolean;

package/dist/index.js

@@ -14,7 +14,8 @@ export * from "./errors.js";
  * does the same with an explicit client. */
 export class Sandbox extends SandboxClass {
     /** Creates a sandbox (every field optional) and waits until it is running.
-     * `keepAlive: true` (or its options) extends its lease in the background
+     * With no `timeoutSeconds` it runs while it works and pauses when idle.
+     * `keepAlive: true` (or its options) carries one with a time limit past it
      * until you stop it; see `sandbox.keepAlive()`. */
     static async create(input = {}, options = {}) {
         const { client, ...rest } = options;

package/dist/machine.d.ts

@@ -0,0 +1,180 @@
+import { RuntimeError } from "./errors.js";
+import { Page } from "./page.js";
+import type { Snapshot, SnapshotOptions } from "./snapshots.js";
+import type { RequestOptions, Transport } from "./transport.js";
+import type { KeepAliveOptions } from "./types.js";
+/** One machine product: the API serves it at /v1/<plural>, and its errors
+ * call one of it by `noun`. */
+export type MachineProduct = {
+    readonly plural: string;
+    readonly noun: string;
+};
+/** What every machine's record carries for the verbs shared here. */
+export type MachineState = "starting" | "running" | "pausing" | "paused" | "resuming" | "stopping" | "stopped";
+export type MachineInfo = {
+    id: string;
+    state: MachineState;
+    expiresAt: string;
+    endsAt?: string | null;
+    start?: unknown;
+};
+/** Any other call's request options, as the caller gave them: `timeoutMs` is
+ * the call's whole deadline, and 0 turns it off. */
+export declare function requestOnly(options: RequestOptions): RequestOptions;
+/** DELETE /v1/<plural>/{id}, for `machine.delete()` and the product's
+ * `delete(id)`. */
+export declare function deleteMachine<Deleted>(product: MachineProduct, t: Transport, id: string, options?: RequestOptions): Promise<Deleted>;
+/** One page of a product's list, and the pages after it. */
+export declare function machinePage<M, Info>(product: MachineProduct, t: Transport, wrap: (t: Transport, info: Info) => M, body: {
+    data: Info[];
+    nextCursor: string | null;
+}, query: Record<string, unknown>, options?: RequestOptions): Page<M>;
+/** One machine: its record and the verbs every machine product shares. */
+export declare abstract class Machine<Info extends MachineInfo, Settings extends object, Deleted> implements AsyncDisposable {
+    #private;
+    constructor(product: MachineProduct, transport: Transport, info: Info);
+    get id(): string;
+    /** What the API last said about this sandbox. `refresh()` asks again. */
+    get info(): Info;
+    get state(): Info["state"];
+    refresh(options?: RequestOptions): Promise<this>;
+    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
+    waitFor(state: "running" | "paused" | "stopped", options?: {
+        timeoutSeconds?: number;
+    } & RequestOptions): Promise<this>;
+    stop(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    pause(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    /** Deletes it for good: stops it if it runs or is paused, deletes its disk
+     * and paused memory, revokes its previews and ports, and removes it from
+     * lists. Its snapshots, usage and audit entries stay. Deleting it again
+     * answers the same. */
+    delete(options?: RequestOptions): Promise<Deleted>;
+    /** 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 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
+     * while credit lasts (paid only). */
+    update(settings: Settings, options?: RequestOptions): Promise<this>;
+    /** Moves it to another image (id, name, name:tag or name@version), keeping
+     * 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; 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 (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 2 vCPU and 4 GiB without credit, or
+     * 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;
+    }): Promise<this>;
+    /** 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;
+    /** Days a paused sandbox is kept before deletion (1 to 365). */
+    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. Past
+     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
+     * the error names the snapshot. */
+    snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
+    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
+    restart(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    [Symbol.asyncDispose](): Promise<void>;
+    toJSON(): Info;
+}
+/** How a product's `create` waits when every slot without credit, 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;
+};
+/** A machine product's collection: `runtime.<product>`. */
+export declare abstract class Machines<M extends Machine<Info, object, Deleted>, Info extends MachineInfo, Create extends {
+    name?: string;
+    getOrCreate?: boolean;
+}, Deleted> {
+    #private;
+    constructor(product: MachineProduct, t: Transport, wrap: (t: Transport, info: Info) => M);
+    /** Creates a sandbox and waits until it is running. Every field is optional:
+     * with none you get the included usage while it lasts, the default region and a
+     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
+     * When every slot without credit 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?: Create & {
+        wait?: boolean;
+    }, options?: CreateOptions): Promise<M>;
+    /** 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<Create, "name" | "getOrCreate"> & {
+        wait?: boolean;
+    }, options?: CreateOptions): Promise<M>;
+    get(id: string, options?: RequestOptions): Promise<M>;
+    /** 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<Deleted>;
+    /** 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?: Info["state"][];
+        includeStopped?: boolean;
+        /** Every label must match. */
+        labels?: Record<string, string>;
+        name?: string;
+        limit?: number;
+    }, options?: RequestOptions): Promise<Page<M>>;
+    /** 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;
+        }[];
+    }>;
+}