sandbox0 0.10.2 → 0.10.3

package/dist/resources/sandboxes.d.ts

@@ -1,5 +1,5 @@
 import type { CreateSandboxRootFSSnapshotRequest, ForkSandboxRequest, ForkSandboxResponse, PauseSandboxResponse, RebaseSandboxRootFSRequest, RebaseSandboxRootFSResponse, RestoreSandboxRootFSRequest, RestoreSandboxRootFSResponse, SandboxRefreshRequest, RefreshResponse, ResumeSandboxResponse, Sandbox, SandboxConfig, SandboxRootFSSnapshot, SandboxStatus, SandboxUpdateRequest, SuccessMessageResponse, SuccessDeletedResponse } from "../apispec/src/models/index.js";
-import type { SandboxLifecyclePredicate, SandboxLifecycleWaitOptions, SandboxListOptions, SandboxListResult } from "../models.js";
+import type { SandboxExecutionStateOptions, SandboxLifecyclePredicate, SandboxLifecycleWaitOptions, SandboxListOptions, SandboxListResult } from "../models.js";
 import type { Client } from "../client.js";
 import { Sandbox as SandboxHandle } from "../sandbox.js";
 import { SandboxSession } from "../sessions.js";
@@ -8,6 +8,10 @@ export interface ClaimSandboxOptions {
     snapshotId?: string;
     memory?: string;
 }
+export interface ForkSandboxOptions {
+    /** Stable retry key. Reusing it for another source is safely namespaced. */
+    idempotencyKey?: string;
+}
 export declare class Sandboxes {
     private readonly client;
     constructor(client: Client);
@@ -26,10 +30,10 @@ export declare class Sandboxes {
     update(sandboxId: string, request: SandboxUpdateRequest): Promise<Sandbox>;
     delete(sandboxId: string): Promise<SuccessMessageResponse>;
     status(sandboxId: string): Promise<SandboxStatus>;
-    pause(sandboxId: string): Promise<PauseSandboxResponse>;
+    pause(sandboxId: string, options?: SandboxExecutionStateOptions): Promise<PauseSandboxResponse>;
     /** Requests a pause and waits for its durable checkpoint to commit. */
     pauseAndWait(sandboxId: string, options?: SandboxLifecycleWaitOptions): Promise<Sandbox>;
-    resume(sandboxId: string): Promise<ResumeSandboxResponse>;
+    resume(sandboxId: string, options?: SandboxExecutionStateOptions): Promise<ResumeSandboxResponse>;
     /** Requests a resume and waits for the committed running generation. */
     resumeAndWait(sandboxId: string, options?: SandboxLifecycleWaitOptions): Promise<Sandbox>;
     refresh(sandboxId: string, request?: SandboxRefreshRequest): Promise<RefreshResponse>;
@@ -39,7 +43,7 @@ export declare class Sandboxes {
     deleteRootFSSnapshot(snapshotId: string): Promise<SuccessDeletedResponse>;
     restoreRootFS(sandboxId: string, request: RestoreSandboxRootFSRequest): Promise<RestoreSandboxRootFSResponse>;
     rebaseRootFS(sandboxId: string, request: RebaseSandboxRootFSRequest): Promise<RebaseSandboxRootFSResponse>;
-    fork(sandboxId: string, request?: ForkSandboxRequest): Promise<ForkSandboxResponse>;
+    fork(sandboxId: string, request?: ForkSandboxRequest, options?: ForkSandboxOptions): Promise<ForkSandboxResponse>;
     sandbox(sandboxId: string): SandboxHandle;
 }
 //# sourceMappingURL=sandboxes.d.ts.map

package/dist/resources/sandboxes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandboxes.d.ts","sourceRoot":"","sources":["../../src/resources/sandboxes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandboxes.d.ts","sourceRoot":"","sources":["../../src/resources/sandboxes.ts"],"names":[],"mappings":"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"}

package/dist/resources/sandboxes.js

@@ -1,5 +1,5 @@
 import { ensureData, ensureModel } from "../response.js";
-import { SandboxWaitTimeoutError, wrapApiCall } from "../errors.js";
+import { SandboxWaitTimeoutError, SandboxLifecycleFailedError, wrapApiCall } from "../errors.js";
 import { Sandbox as SandboxHandle } from "../sandbox.js";
 import { SandboxSession } from "../sessions.js";
 import { sleepWithSignal, throwIfAborted, validateWaitDuration, } from "../wait.js";
@@ -122,18 +122,29 @@ export class Sandboxes {
         const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdStatusGet({ id: sandboxId }));
         return ensureData(response, "get sandbox status returned empty response");
     }
-    async pause(sandboxId) {
-        const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdPausePost({ id: sandboxId }));
+    async pause(sandboxId, options) {
+        const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdPausePost({
+            id: sandboxId,
+            sandboxExecutionStateRequest: options === undefined ? undefined : { memory: options.memory ?? false },
+        }));
         return ensureData(response, "pause sandbox returned empty response");
     }
     /** Requests a pause and waits for its durable checkpoint to commit. */
     async pauseAndWait(sandboxId, options) {
         throwIfAborted(options?.signal, "sandbox lifecycle wait was aborted");
-        await this.pause(sandboxId);
-        return this.waitForLifecycle(sandboxId, (sandbox) => sandbox.status === "paused" && sandbox.paused, options);
+        await this.pause(sandboxId, options);
+        const sandbox = await this.waitForLifecycle(sandboxId, (sandbox) => (sandbox.status === "paused" && sandbox.paused) ||
+            (options?.memory === true && sandbox.status === "failed"), options);
+        if (options?.memory && sandbox.status === "failed") {
+            throw new SandboxLifecycleFailedError(sandboxId, "memory pause", sandbox);
+        }
+        return sandbox;
     }
-    async resume(sandboxId) {
-        const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdResumePost({ id: sandboxId }));
+    async resume(sandboxId, options) {
+        const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdResumePost({
+            id: sandboxId,
+            sandboxExecutionStateRequest: options === undefined ? undefined : { memory: options.memory ?? false },
+        }));
         return ensureData(response, "resume sandbox returned empty response");
     }
     /** Requests a resume and waits for the committed running generation. */
@@ -141,13 +152,17 @@ export class Sandboxes {
         throwIfAborted(options?.signal, "sandbox lifecycle wait was aborted");
         const before = await this.getWithSignal(sandboxId, options?.signal);
         throwIfAborted(options?.signal, "sandbox lifecycle wait was aborted");
-        await this.resume(sandboxId);
+        await this.resume(sandboxId, options);
         const minimumRuntimeGeneration = before.paused || before.status === "paused"
             ? before.runtimeGeneration + 1
             : before.runtimeGeneration;
-        return this.waitForLifecycle(sandboxId, (sandbox) => (sandbox.status === "running"
-            && !sandbox.paused
-            && sandbox.runtimeGeneration >= minimumRuntimeGeneration), options);
+        const sandbox = await this.waitForLifecycle(sandboxId, (sandbox) => (sandbox.runtimeGeneration >= minimumRuntimeGeneration
+            && ((sandbox.status === "running" && !sandbox.paused)
+                || (options?.memory === true && sandbox.status === "failed"))), options);
+        if (options?.memory && sandbox.status === "failed") {
+            throw new SandboxLifecycleFailedError(sandboxId, "memory resume", sandbox);
+        }
+        return sandbox;
     }
     async refresh(sandboxId, request) {
         const params = request
@@ -194,9 +209,13 @@ export class Sandboxes {
         }));
         return ensureData(response, "rebase sandbox rootfs returned empty response");
     }
-    async fork(sandboxId, request) {
+    async fork(sandboxId, request, options = {}) {
+        if (request?.memory && (!options.idempotencyKey?.trim() || new TextEncoder().encode(options.idempotencyKey).length > 255)) {
+            throw new Error("memory fork requires a stable idempotencyKey of at most 255 bytes");
+        }
         const response = await wrapApiCall(() => this.client.apispec.sandboxRootfs.apiV1SandboxesIdForkPost({
             id: sandboxId,
+            idempotencyKey: options.idempotencyKey,
             forkSandboxRequest: request ?? {},
         }));
         return ensureData(response, "fork sandbox returned empty response");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandbox0",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Sandbox0 JavaScript/TypeScript SDK",
   "license": "Apache-2.0",
   "author": "Sandbox0 Team",