withruntime 0.11.1 → 0.12.0

package/dist/e2b/sandbox.d.ts

@@ -9,14 +9,35 @@ export declare const DEFAULT_SHAPE: {
     readonly vcpu: 2;
     readonly memoryMiB: 512;
 };
-/** E2B's default sandbox timeout, 300 s. Not sent: a sandbox created with no
- * timeoutMs has no time limit on Runtime, running while it works and pausing
- * when idle (0300). Kept for code that imports it. */
+/** E2B's default sandbox timeout, 300 s. A sandbox created without timeoutMs
+ * gets it, and is paused when it runs out rather than killed, since nobody
+ * asked for it to end: nothing in it is lost, and the next call wakes it. On
+ * a pilot account the server keeps every sandbox running instead (0254). */
 export declare const DEFAULT_TIMEOUT_MS = 300000;
+/** The label that keeps the template a sandbox was made from, so getInfo
+ * and list name it whichever client asks; it is not shown in `metadata`. */
+export declare const TEMPLATE_LABEL = "e2b-template";
 export type SandboxState = "running" | "paused";
+/** What a pause or snapshot keeps (E2B 2.55): `"full"` keeps memory and
+ * files, `"filesystem"` only files, so what starts from it boots afresh. */
+export type SnapshotMode = "full" | "filesystem";
 export type SandboxOnTimeout = "pause" | "kill" | {
-    action: "pause" | "kill";
+    action: "pause";
+    mode?: SnapshotMode;
+    /** @deprecated E2B 2.55: use `mode`. */
     keepMemory?: boolean;
+} | {
+    action: "kill";
+};
+/** E2B's pause options: `mode`, or the deprecated `keepMemory`. */
+export type SandboxPauseOpts = SandboxApiOpts & {
+    mode?: SnapshotMode;
+    /** @deprecated E2B 2.55: use `mode`. */
+    keepMemory?: boolean;
+};
+export type CreateSnapshotOpts = SandboxApiOpts & {
+    name?: string;
+    mode?: SnapshotMode;
 };
 export type SandboxLifecycle = {
     onTimeout: SandboxOnTimeout;
@@ -92,10 +113,10 @@ export type SandboxListOpts = SandboxApiOpts & {
     limit?: number;
     nextToken?: string;
 };
-/** Test hook: renew every kept lease now, as the five-minute timer would. */
-export declare function renewLeases(): Promise<void>;
-/** Test hook: the end each kept sandbox is kept until. */
-export declare function keptLeases(): Map<string, number>;
+/** The Runtime image name an E2B template name stands for: E2B's
+ * `team/name:tag` without the team, since a Runtime account's images are its
+ * own. `name`, `name:tag` and `name@version` are Runtime image names too. */
+export declare function imageNameFor(template: string): string;
 export declare class Sandbox {
     #private;
     protected readonly requestTimeoutMs: number;
@@ -112,8 +133,7 @@ export declare class Sandbox {
     protected get client(): Runtime;
     /** Creates a sandbox from `template` (default "base", Runtime's stock image)
      * with E2B's default machine, 2 vCPU and 512 MiB, and waits until it runs.
-     * Funding is left to Runtime: the free trial while the account has trial
-     * time, then prepaid credit, exactly as withruntime's own create. */
+     * Funding is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
     static create<S extends typeof Sandbox>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>;
     static create<S extends typeof Sandbox>(this: S, template: string, opts?: SandboxOpts): Promise<InstanceType<S>>;
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
@@ -123,31 +143,29 @@ export declare class Sandbox {
     connect(opts?: SandboxConnectOpts): Promise<this>;
     /** Running and paused sandboxes, a page at a time, as E2B's paginator. */
     static list(opts?: SandboxListOpts): SandboxPaginator;
-    /** Stops the sandbox. False when it was not found or had already ended. */
+    /** Deletes the sandbox for good, as E2B's kill destroys it: its disk,
+     * memory and shared ports go. False when it was not found or was already
+     * deleted. */
     static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>;
     kill(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
-    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours; past an
-     * hour the lease is moved on while this process runs. Runtime cannot end a
-     * lease early, so an end sooner than the lease's is refused. A sandbox
-     * created with no timeout has no end to move, and nothing changes. */
+    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours, as E2B
+     * does; the server keeps the deadline. Runtime cannot bring an end
+     * sooner, so that is refused. A sandbox with no time limit (one on a pilot
+     * account, kept running by the server) has no end to move, and nothing
+     * changes. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise<void>;
     setTimeout(timeoutMs: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>;
     static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>;
     getInfo(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<SandboxInfo>;
+    /** Whether the sandbox answers calls, as E2B's health check says: true
+     * while it runs, and while Runtime has paused it for being idle, since the
+     * next call wakes it. False once paused on request, ended or deleted. */
     isRunning(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
     /** Pauses the sandbox, keeping memory and files. False when it was paused. */
-    static pause(sandboxId: string, opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
-    static betaPause(sandboxId: string, opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
-    pause(opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
-    betaPause(opts?: SandboxApiOpts & {
-        keepMemory?: boolean;
-    }): Promise<boolean>;
+    static pause(sandboxId: string, opts?: SandboxPauseOpts): Promise<boolean>;
+    static betaPause(sandboxId: string, opts?: SandboxPauseOpts): Promise<boolean>;
+    pause(opts?: SandboxPauseOpts): Promise<boolean>;
+    betaPause(opts?: SandboxPauseOpts): Promise<boolean>;
     /** Copies of this sandbox, memory and all. While Runtime's forks are
      * switched off this throws NotSupportedError with Runtime's own words. */
     static fork<S extends typeof Sandbox>(this: S, sandboxId: string, opts?: SandboxApiOpts & {
@@ -158,14 +176,11 @@ export declare class Sandbox {
         count?: number;
         timeoutMs?: number;
     }): Promise<Array<this | Error>>;
-    /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
-     * with Sandbox.create(snapshotId). */
-    createSnapshot(opts?: SandboxApiOpts & {
-        name?: string;
-    }): Promise<SnapshotInfo>;
-    static createSnapshot(sandboxId: string, opts?: SandboxApiOpts & {
-        name?: string;
-    }): Promise<SnapshotInfo>;
+    /** Keeps the sandbox's whole machine as a Runtime snapshot, or with
+     * `mode: "filesystem"` its disk alone, from which a sandbox boots afresh;
+     * start from it with Sandbox.create(snapshotId). */
+    createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     static deleteSnapshot(snapshotId: string, opts?: SandboxApiOpts): Promise<boolean>;
     /** E2B's getHost, answered at once as E2B answers it:
      * `<port>-<id>.runtimehost.com`. A Runtime preview's address is made from