sandbox0 0.7.6 → 0.7.7

package/README.md

@@ -85,6 +85,25 @@ for (const mount of sandbox.bootstrapMounts) {
 }
 ```
 
+## Wait For Lifecycle Changes
+
+Pause is accepted before its rootfs checkpoint is fully committed. Use the
+waiting helpers when the next operation depends on committed lifecycle state:
+
+```typescript
+const paused = await client.sandboxes.pauseAndWait(sandbox.id, {
+  timeoutMs: 120_000,
+  signal: abortController.signal,
+});
+
+const resumed = await client.sandboxes.resumeAndWait(paused.id);
+console.log(resumed.status, resumed.runtimeGeneration);
+```
+
+`waitForLifecycle()` is available for other committed-state conditions. Aborting
+a wait stops polling locally; it does not undo a pause or resume already accepted
+by Sandbox0.
+
 ## Links
 
 - [Documentation](https://sandbox0.ai/docs)

package/dist/apispec/src/apis/ObservabilityApi.d.ts

@@ -48,12 +48,12 @@ export interface ApiV1SandboxesIdObservabilityMetricsGetRequest {
  */
 export declare class ObservabilityApi extends runtime.BaseAPI {
     /**
-     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and does not replace the metering usage truth stored in PostgreSQL.
+     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and reads tables that are separate from the metering usage ledger.
      * Query historical sandbox observability events
      */
     apiV1SandboxesIdObservabilityEventsGetRaw(requestParameters: ApiV1SandboxesIdObservabilityEventsGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SuccessSandboxObservabilityEventsResponse>>;
     /**
-     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and does not replace the metering usage truth stored in PostgreSQL.
+     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and reads tables that are separate from the metering usage ledger.
      * Query historical sandbox observability events
      */
     apiV1SandboxesIdObservabilityEventsGet(requestParameters: ApiV1SandboxesIdObservabilityEventsGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SuccessSandboxObservabilityEventsResponse>;
@@ -68,12 +68,12 @@ export declare class ObservabilityApi extends runtime.BaseAPI {
      */
     apiV1SandboxesIdObservabilityLogsGet(requestParameters: ApiV1SandboxesIdObservabilityLogsGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SuccessSandboxObservabilityLogsResponse>;
     /**
-     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and PostgreSQL metering usage truth.
+     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and metering usage truth.
      * Query historical sandbox metric samples
      */
     apiV1SandboxesIdObservabilityMetricsGetRaw(requestParameters: ApiV1SandboxesIdObservabilityMetricsGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SuccessSandboxObservabilityMetricsResponse>>;
     /**
-     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and PostgreSQL metering usage truth.
+     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and metering usage truth.
      * Query historical sandbox metric samples
      */
     apiV1SandboxesIdObservabilityMetricsGet(requestParameters: ApiV1SandboxesIdObservabilityMetricsGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SuccessSandboxObservabilityMetricsResponse>;

package/dist/apispec/src/apis/ObservabilityApi.js

@@ -18,7 +18,7 @@ import { SuccessSandboxObservabilityEventsResponseFromJSON, SuccessSandboxObserv
  */
 export class ObservabilityApi extends runtime.BaseAPI {
     /**
-     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and does not replace the metering usage truth stored in PostgreSQL.
+     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and reads tables that are separate from the metering usage ledger.
      * Query historical sandbox observability events
      */
     async apiV1SandboxesIdObservabilityEventsGetRaw(requestParameters, initOverrides) {
@@ -69,7 +69,7 @@ export class ObservabilityApi extends runtime.BaseAPI {
         return new runtime.JSONApiResponse(response, (jsonValue) => SuccessSandboxObservabilityEventsResponseFromJSON(jsonValue));
     }
     /**
-     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and does not replace the metering usage truth stored in PostgreSQL.
+     * Queries the asynchronous per-sandbox observability projection for lifecycle, network audit, and runtime stats events. This endpoint does not expose backend SQL and reads tables that are separate from the metering usage ledger.
      * Query historical sandbox observability events
      */
     async apiV1SandboxesIdObservabilityEventsGet(requestParameters, initOverrides) {
@@ -133,7 +133,7 @@ export class ObservabilityApi extends runtime.BaseAPI {
         return await response.value();
     }
     /**
-     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and PostgreSQL metering usage truth.
+     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and metering usage truth.
      * Query historical sandbox metric samples
      */
     async apiV1SandboxesIdObservabilityMetricsGetRaw(requestParameters, initOverrides) {
@@ -184,7 +184,7 @@ export class ObservabilityApi extends runtime.BaseAPI {
         return new runtime.JSONApiResponse(response, (jsonValue) => SuccessSandboxObservabilityMetricsResponseFromJSON(jsonValue));
     }
     /**
-     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and PostgreSQL metering usage truth.
+     * Queries the asynchronous per-sandbox metric sample projection. This endpoint is separate from platform service metrics and metering usage truth.
      * Query historical sandbox metric samples
      */
     async apiV1SandboxesIdObservabilityMetricsGet(requestParameters, initOverrides) {

package/dist/apispec/src/apis/SandboxRootfsApi.d.ts

@@ -53,11 +53,13 @@ export declare class SandboxRootfsApi extends runtime.BaseAPI {
      */
     apiV1SandboxRootfsSnapshotsSnapshotIdGet(requestParameters: ApiV1SandboxRootfsSnapshotsSnapshotIdGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SuccessSandboxRootFSSnapshotResponse>;
     /**
-     * Fork sandbox from paused rootfs
+     * Forks the source sandbox writable rootfs into a new paused sandbox. A paused source is forked from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the fork operation completes.
+     * Fork sandbox rootfs
      */
     apiV1SandboxesIdForkPostRaw(requestParameters: ApiV1SandboxesIdForkPostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SuccessForkSandboxResponse>>;
     /**
-     * Fork sandbox from paused rootfs
+     * Forks the source sandbox writable rootfs into a new paused sandbox. A paused source is forked from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the fork operation completes.
+     * Fork sandbox rootfs
      */
     apiV1SandboxesIdForkPost(requestParameters: ApiV1SandboxesIdForkPostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SuccessForkSandboxResponse>;
     /**
@@ -77,10 +79,12 @@ export declare class SandboxRootfsApi extends runtime.BaseAPI {
      */
     apiV1SandboxesIdSnapshotsGet(requestParameters: ApiV1SandboxesIdSnapshotsGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SuccessSandboxRootFSSnapshotListResponse>;
     /**
+     * Creates an immutable snapshot record from the source sandbox writable rootfs. A paused source is snapshotted from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the snapshot operation completes.
      * Create sandbox rootfs snapshot
      */
     apiV1SandboxesIdSnapshotsPostRaw(requestParameters: ApiV1SandboxesIdSnapshotsPostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SuccessSandboxRootFSSnapshotResponse>>;
     /**
+     * Creates an immutable snapshot record from the source sandbox writable rootfs. A paused source is snapshotted from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the snapshot operation completes.
      * Create sandbox rootfs snapshot
      */
     apiV1SandboxesIdSnapshotsPost(requestParameters: ApiV1SandboxesIdSnapshotsPostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SuccessSandboxRootFSSnapshotResponse>;

package/dist/apispec/src/apis/SandboxRootfsApi.d.ts.map

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

package/dist/apispec/src/apis/SandboxRootfsApi.js

@@ -84,7 +84,8 @@ export class SandboxRootfsApi extends runtime.BaseAPI {
         return await response.value();
     }
     /**
-     * Fork sandbox from paused rootfs
+     * Forks the source sandbox writable rootfs into a new paused sandbox. A paused source is forked from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the fork operation completes.
+     * Fork sandbox rootfs
      */
     async apiV1SandboxesIdForkPostRaw(requestParameters, initOverrides) {
         if (requestParameters['id'] == null) {
@@ -112,7 +113,8 @@ export class SandboxRootfsApi extends runtime.BaseAPI {
         return new runtime.JSONApiResponse(response, (jsonValue) => SuccessForkSandboxResponseFromJSON(jsonValue));
     }
     /**
-     * Fork sandbox from paused rootfs
+     * Forks the source sandbox writable rootfs into a new paused sandbox. A paused source is forked from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the fork operation completes.
+     * Fork sandbox rootfs
      */
     async apiV1SandboxesIdForkPost(requestParameters, initOverrides) {
         const response = await this.apiV1SandboxesIdForkPostRaw(requestParameters, initOverrides);
@@ -190,6 +192,7 @@ export class SandboxRootfsApi extends runtime.BaseAPI {
         return await response.value();
     }
     /**
+     * Creates an immutable snapshot record from the source sandbox writable rootfs. A paused source is snapshotted from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the snapshot operation completes.
      * Create sandbox rootfs snapshot
      */
     async apiV1SandboxesIdSnapshotsPostRaw(requestParameters, initOverrides) {
@@ -218,6 +221,7 @@ export class SandboxRootfsApi extends runtime.BaseAPI {
         return new runtime.JSONApiResponse(response, (jsonValue) => SuccessSandboxRootFSSnapshotResponseFromJSON(jsonValue));
     }
     /**
+     * Creates an immutable snapshot record from the source sandbox writable rootfs. A paused source is snapshotted from its current rootfs head. A running source is briefly barriered and checkpointed first; the source sandbox remains running after the snapshot operation completes.
      * Create sandbox rootfs snapshot
      */
     async apiV1SandboxesIdSnapshotsPost(requestParameters, initOverrides) {

package/dist/apispec/src/models/CreateSandboxRootFSSnapshotRequest.d.ts

@@ -10,6 +10,8 @@
  * Do not edit the class manually.
  */
 /**
+ * Optional snapshot metadata. The source sandbox may be running or paused;
+ * running sources are checkpointed before the snapshot record is created.
  *
  * @export
  * @interface CreateSandboxRootFSSnapshotRequest

package/dist/apispec/src/models/CreateSandboxRootFSSnapshotRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CreateSandboxRootFSSnapshotRequest.d.ts","sourceRoot":"","sources":["../../../../src/apispec/src/models/CreateSandboxRootFSSnapshotRequest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAGH;;;;GAIG;AACH,MAAM,WAAW,kCAAkC;IAC/C;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,4CAA4C,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kCAAkC,CAEvH;AAED,wBAAgB,0CAA0C,CAAC,IAAI,EAAE,GAAG,GAAG,kCAAkC,CAExG;AAED,wBAAgB,+CAA+C,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,EAAE,OAAO,GAAG,kCAAkC,CAU3I;AAED,wBAAgB,wCAAwC,CAAC,IAAI,EAAE,GAAG,GAAG,kCAAkC,CAEtG;AAED,wBAAgB,6CAA6C,CAAC,KAAK,CAAC,EAAE,kCAAkC,GAAG,IAAI,EAAE,mBAAmB,GAAE,OAAe,GAAG,GAAG,CAW1J"}
+{"version":3,"file":"CreateSandboxRootFSSnapshotRequest.d.ts","sourceRoot":"","sources":["../../../../src/apispec/src/models/CreateSandboxRootFSSnapshotRequest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAGH;;;;;;GAMG;AACH,MAAM,WAAW,kCAAkC;IAC/C;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,4CAA4C,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kCAAkC,CAEvH;AAED,wBAAgB,0CAA0C,CAAC,IAAI,EAAE,GAAG,GAAG,kCAAkC,CAExG;AAED,wBAAgB,+CAA+C,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,EAAE,OAAO,GAAG,kCAAkC,CAU3I;AAED,wBAAgB,wCAAwC,CAAC,IAAI,EAAE,GAAG,GAAG,kCAAkC,CAEtG;AAED,wBAAgB,6CAA6C,CAAC,KAAK,CAAC,EAAE,kCAAkC,GAAG,IAAI,EAAE,mBAAmB,GAAE,OAAe,GAAG,GAAG,CAW1J"}

package/dist/apispec/src/models/CreateSandboxVolumeS3Config.d.ts

@@ -34,29 +34,29 @@ export interface CreateSandboxVolumeS3Config {
      */
     prefix?: string;
     /**
-     * Optional region override. Defaults to the storage-proxy S3 region when omitted.
+     * AWS region for the target bucket. Required for provider aws unless endpoint_url is provided.
      * @type {string}
      * @memberof CreateSandboxVolumeS3Config
      */
     region?: string;
     /**
-     * Optional endpoint override. Required for ali and r2.
+     * Optional endpoint override. Required for ali and r2. For aws, endpoint_url can be used instead of region for S3-compatible endpoints.
      * @type {string}
      * @memberof CreateSandboxVolumeS3Config
      */
     endpointUrl?: string;
     /**
-     * Optional access key override. Must be provided together with secret_key.
+     * Access key for this S3 backend volume. Required with secret_key. Stored encrypted and omitted from API responses.
      * @type {string}
      * @memberof CreateSandboxVolumeS3Config
      */
-    accessKey?: string;
+    accessKey: string;
     /**
-     * Optional secret key override. Must be provided together with access_key.
+     * Secret key for this S3 backend volume. Required with access_key. Stored encrypted and omitted from API responses.
      * @type {string}
      * @memberof CreateSandboxVolumeS3Config
      */
-    secretKey?: string;
+    secretKey: string;
     /**
      * Optional temporary credential session token.
      * @type {string}

package/dist/apispec/src/models/CreateSandboxVolumeS3Config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CreateSandboxVolumeS3Config.d.ts","sourceRoot":"","sources":["../../../../src/apispec/src/models/CreateSandboxVolumeS3Config.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAGH;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,uCAAuC,CAAC;IACnD;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAGD;;GAEG;AACH,eAAO,MAAM,uCAAuC;;;;CAI1C,CAAC;AACX,MAAM,MAAM,uCAAuC,GAAG,OAAO,uCAAuC,CAAC,MAAM,OAAO,uCAAuC,CAAC,CAAC;AAG3J;;GAEG;AACH,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,2BAA2B,CAGzG;AAED,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,GAAG,GAAG,2BAA2B,CAE1F;AAED,wBAAgB,wCAAwC,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,EAAE,OAAO,GAAG,2BAA2B,CAe7H;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,GAAG,GAAG,2BAA2B,CAExF;AAED,wBAAgB,sCAAsC,CAAC,KAAK,CAAC,EAAE,2BAA2B,GAAG,IAAI,EAAE,mBAAmB,GAAE,OAAe,GAAG,GAAG,CAgB5I"}
+{"version":3,"file":"CreateSandboxVolumeS3Config.d.ts","sourceRoot":"","sources":["../../../../src/apispec/src/models/CreateSandboxVolumeS3Config.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAGH;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,uCAAuC,CAAC;IACnD;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAGD;;GAEG;AACH,eAAO,MAAM,uCAAuC;;;;CAI1C,CAAC;AACX,MAAM,MAAM,uCAAuC,GAAG,OAAO,uCAAuC,CAAC,MAAM,OAAO,uCAAuC,CAAC,CAAC;AAG3J;;GAEG;AACH,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,2BAA2B,CAKzG;AAED,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,GAAG,GAAG,2BAA2B,CAE1F;AAED,wBAAgB,wCAAwC,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,EAAE,OAAO,GAAG,2BAA2B,CAe7H;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,GAAG,GAAG,2BAA2B,CAExF;AAED,wBAAgB,sCAAsC,CAAC,KAAK,CAAC,EAAE,2BAA2B,GAAG,IAAI,EAAE,mBAAmB,GAAE,OAAe,GAAG,GAAG,CAgB5I"}

package/dist/apispec/src/models/CreateSandboxVolumeS3Config.js

@@ -25,6 +25,10 @@ export const CreateSandboxVolumeS3ConfigProviderEnum = {
 export function instanceOfCreateSandboxVolumeS3Config(value) {
     if (!('bucket' in value) || value['bucket'] === undefined)
         return false;
+    if (!('accessKey' in value) || value['accessKey'] === undefined)
+        return false;
+    if (!('secretKey' in value) || value['secretKey'] === undefined)
+        return false;
     return true;
 }
 export function CreateSandboxVolumeS3ConfigFromJSON(json) {
@@ -40,8 +44,8 @@ export function CreateSandboxVolumeS3ConfigFromJSONTyped(json, ignoreDiscriminat
         'prefix': json['prefix'] == null ? undefined : json['prefix'],
         'region': json['region'] == null ? undefined : json['region'],
         'endpointUrl': json['endpoint_url'] == null ? undefined : json['endpoint_url'],
-        'accessKey': json['access_key'] == null ? undefined : json['access_key'],
-        'secretKey': json['secret_key'] == null ? undefined : json['secret_key'],
+        'accessKey': json['access_key'],
+        'secretKey': json['secret_key'],
         'sessionToken': json['session_token'] == null ? undefined : json['session_token'],
     };
 }

package/dist/apispec/src/models/ForkSandboxRequest.d.ts

@@ -12,6 +12,8 @@
 import type { ForkSandboxConfig } from './ForkSandboxConfig.js';
 /**
  * Optional fork overrides. Omit config to inherit the source sandbox configuration.
+ * The source sandbox may be running or paused; running sources are checkpointed
+ * before the paused child sandbox is created.
  *
  * @export
  * @interface ForkSandboxRequest

package/dist/apispec/src/models/ForkSandboxRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForkSandboxRequest.d.ts","sourceRoot":"","sources":["../../../../src/apispec/src/models/ForkSandboxRequest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAQ7D;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kBAAkB,CAEvF;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,GAAG,GAAG,kBAAkB,CAExE;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,EAAE,OAAO,GAAG,kBAAkB,CAQ3G;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,GAAG,GAAG,kBAAkB,CAEtE;AAED,wBAAgB,6BAA6B,CAAC,KAAK,CAAC,EAAE,kBAAkB,GAAG,IAAI,EAAE,mBAAmB,GAAE,OAAe,GAAG,GAAG,CAS1H"}
+{"version":3,"file":"ForkSandboxRequest.d.ts","sourceRoot":"","sources":["../../../../src/apispec/src/models/ForkSandboxRequest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAQ7D;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kBAAkB,CAEvF;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,GAAG,GAAG,kBAAkB,CAExE;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,GAAG,EAAE,mBAAmB,EAAE,OAAO,GAAG,kBAAkB,CAQ3G;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,GAAG,GAAG,kBAAkB,CAEtE;AAED,wBAAgB,6BAA6B,CAAC,KAAK,CAAC,EAAE,kBAAkB,GAAG,IAAI,EAAE,mBAAmB,GAAE,OAAe,GAAG,GAAG,CAS1H"}

package/dist/errors.d.ts

@@ -1,9 +1,12 @@
+import type { Sandbox } from "./apispec/src/models/index.js";
+export declare const CLAIM_START_THROTTLED_CODE = "claim_start_throttled";
 export declare class APIError extends Error {
     statusCode: number;
     code?: string;
     details?: unknown;
     requestId?: string;
     body?: string;
+    retryAfter?: number;
     constructor(params: {
         statusCode: number;
         message: string;
@@ -11,8 +14,20 @@ export declare class APIError extends Error {
         details?: unknown;
         requestId?: string;
         body?: string;
+        retryAfter?: number;
     });
 }
+export declare class SandboxWaitTimeoutError extends Error {
+    readonly sandboxId: string;
+    readonly timeoutMs: number;
+    readonly lastSandbox?: Sandbox;
+    constructor(params: {
+        sandboxId: string;
+        timeoutMs: number;
+        lastSandbox?: Sandbox;
+    });
+}
+export declare function isClaimStartThrottled(error: unknown): error is APIError;
 export declare function apiErrorFromResponse(response: Response): Promise<APIError>;
 export declare function wrapApiCall<T>(fn: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,qBAAa,QAAS,SAAQ,KAAK;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,MAAM,EAAE;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf;CASF;AAUD,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgChF;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CASrE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAGzE,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE,qBAAa,QAAS,SAAQ,KAAK;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;gBAER,MAAM,EAAE;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;CAUF;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;gBAEnB,MAAM,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB;CAOF;AAuBD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAIvE;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkChF;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CASrE"}

package/dist/errors.js

@@ -1,10 +1,12 @@
 import { runtime } from "./apispec_compat.js";
+export const CLAIM_START_THROTTLED_CODE = "claim_start_throttled";
 export class APIError extends Error {
     statusCode;
     code;
     details;
     requestId;
     body;
+    retryAfter;
     constructor(params) {
         super(params.message);
         this.name = "APIError";
@@ -13,6 +15,19 @@ export class APIError extends Error {
         this.details = params.details;
         this.requestId = params.requestId;
         this.body = params.body;
+        this.retryAfter = params.retryAfter;
+    }
+}
+export class SandboxWaitTimeoutError extends Error {
+    sandboxId;
+    timeoutMs;
+    lastSandbox;
+    constructor(params) {
+        super(`timed out waiting for sandbox ${params.sandboxId} after ${params.timeoutMs}ms`);
+        this.name = "SandboxWaitTimeoutError";
+        this.sandboxId = params.sandboxId;
+        this.timeoutMs = params.timeoutMs;
+        this.lastSandbox = params.lastSandbox;
     }
 }
 function getRequestId(response) {
@@ -20,9 +35,27 @@ function getRequestId(response) {
         response.headers.get("x-requestid") ??
         undefined);
 }
+function getRetryAfter(response) {
+    const value = response.headers.get("retry-after");
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        return undefined;
+    }
+    const seconds = Number.parseInt(trimmed, 10);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+export function isClaimStartThrottled(error) {
+    return error instanceof APIError
+        && error.statusCode === 429
+        && error.code === CLAIM_START_THROTTLED_CODE;
+}
 export async function apiErrorFromResponse(response) {
     const statusCode = response.status;
     const requestId = getRequestId(response);
+    const retryAfter = getRetryAfter(response);
     let bodyText = "";
     let code = "unexpected_response";
     let message = response.statusText || "request failed";
@@ -50,6 +83,7 @@ export async function apiErrorFromResponse(response) {
         details,
         requestId,
         body: bodyText || undefined,
+        retryAfter,
     });
 }
 export async function wrapApiCall(fn) {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Client, type ClientOptions, DEFAULT_BASE_URL } from "./client.js";
 export { Sandbox } from "./sandbox.js";
-export { APIError } from "./errors.js";
+export { APIError, SandboxWaitTimeoutError } from "./errors.js";
 export { verifyWebhookSignature } from "./webhook_signature.js";
 export * from "./template_helpers.js";
 export * from "./models.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,oBAAoB,CAAC;AAC5B,OAAO,iBAAiB,CAAC;AACzB,OAAO,mBAAmB,CAAC;AAC3B,OAAO,oBAAoB,CAAC;AAC5B,OAAO,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,oBAAoB,CAAC;AAC5B,OAAO,iBAAiB,CAAC;AACzB,OAAO,mBAAmB,CAAC;AAC3B,OAAO,oBAAoB,CAAC;AAC5B,OAAO,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 export { Client, DEFAULT_BASE_URL } from "./client.js";
 export { Sandbox } from "./sandbox.js";
-export { APIError } from "./errors.js";
+export { APIError, SandboxWaitTimeoutError } from "./errors.js";
 export { verifyWebhookSignature } from "./webhook_signature.js";
 export * from "./template_helpers.js";
 export * from "./models.js";

package/dist/models.d.ts

@@ -1,4 +1,4 @@
-import type { ObservabilityEventSource, SandboxAppServiceView, SandboxObservabilityEventType, SandboxObservabilityEventsResponse, SandboxObservabilityLogStream, SandboxObservabilityLogsResponse, SandboxObservabilityMetricsResponse, SandboxObservabilityOutcome, SandboxObservabilityWatchLine, SandboxSummary } from "./apispec/src/models/index.js";
+import type { ObservabilityEventSource, SandboxAppServiceView, SandboxObservabilityEventType, SandboxObservabilityEventsResponse, SandboxObservabilityLogStream, SandboxObservabilityLogsResponse, SandboxObservabilityMetricsResponse, SandboxObservabilityOutcome, SandboxObservabilityWatchLine, Sandbox, SandboxSummary } from "./apispec/src/models/index.js";
 export interface RunResult {
     sandboxId: string;
     contextId: string;
@@ -101,4 +101,13 @@ export interface SandboxListResult {
     count: number;
     hasMore: boolean;
 }
+export interface SandboxLifecycleWaitOptions {
+    /** Maximum polling duration. Defaults to 60 seconds. */
+    timeoutMs?: number;
+    /** Delay between observations. Defaults to 500 milliseconds. */
+    pollIntervalMs?: number;
+    /** Stops waiting locally. It does not roll back a lifecycle request already accepted by the server. */
+    signal?: AbortSignal;
+}
+export type SandboxLifecyclePredicate = (sandbox: Sandbox) => boolean | Promise<boolean>;
 //# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

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

package/dist/resources/sandboxes.d.ts

@@ -1,5 +1,5 @@
 import type { ClaimMountRequest, CreateSandboxRootFSSnapshotRequest, ForkSandboxRequest, ForkSandboxResponse, PauseSandboxResponse, RestoreSandboxRootFSRequest, RestoreSandboxRootFSResponse, SandboxRefreshRequest, RefreshResponse, ResumeSandboxResponse, Sandbox, SandboxConfig, SandboxRootFSSnapshot, SandboxStatus, SandboxUpdateRequest, SuccessMessageResponse, SuccessDeletedResponse } from "../apispec/src/models/index.js";
-import type { SandboxListOptions, SandboxListResult } from "../models.js";
+import type { 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";
@@ -16,12 +16,24 @@ export declare class Sandboxes {
     list(options?: SandboxListOptions): Promise<SandboxListResult>;
     open(template: string, options?: SandboxConfig | ClaimSandboxOptions): Promise<SandboxSession>;
     get(sandboxId: string): Promise<Sandbox>;
+    private getWithSignal;
+    /**
+     * Polls committed sandbox details until the predicate matches.
+     *
+     * Abort stops the local wait but cannot undo a lifecycle request that the
+     * server has already accepted.
+     */
+    waitForLifecycle(sandboxId: string, predicate: SandboxLifecyclePredicate, options?: SandboxLifecycleWaitOptions): Promise<Sandbox>;
     update(sandboxId: string, request: SandboxUpdateRequest): Promise<Sandbox>;
     updateMemory(sandboxId: string, memory: string): Promise<Sandbox>;
     delete(sandboxId: string): Promise<SuccessMessageResponse>;
     status(sandboxId: string): Promise<SandboxStatus>;
     pause(sandboxId: string): 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>;
+    /** Requests a resume and waits for the committed running generation. */
+    resumeAndWait(sandboxId: string, options?: SandboxLifecycleWaitOptions): Promise<Sandbox>;
     refresh(sandboxId: string, request?: SandboxRefreshRequest): Promise<RefreshResponse>;
     createRootFSSnapshot(sandboxId: string, request?: CreateSandboxRootFSSnapshotRequest): Promise<SandboxRootFSSnapshot>;
     listRootFSSnapshots(sandboxId: string): Promise<SandboxRootFSSnapshot[]>;

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

@@ -1 +1 @@
-{"version":3,"file":"sandboxes.d.ts","sourceRoot":"","sources":["../../src/resources/sandboxes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAEjB,kCAAkC,EAClC,kBAAkB,EAClB,mBAAmB,EAEnB,oBAAoB,EACpB,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyCD,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAErC,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GAAG,mBAAmB,GAC5C,OAAO,CAAC,aAAa,CAAC;IAmBnB,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkB9D,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GAAG,mBAAmB,GAC5C,OAAO,CAAC,cAAc,CAAC;IAOpB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOxC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAO1D,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAOjD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAOvD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOzD,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAUrB,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kCAAkC,GAC3C,OAAO,CAAC,qBAAqB,CAAC;IAU3B,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAQxE,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IASrE,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IASzE,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,4BAA4B,CAAC;IAUlC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAUzF,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa;CAG1C"}
+{"version":3,"file":"sandboxes.d.ts","sourceRoot":"","sources":["../../src/resources/sandboxes.ts"],"names":[],"mappings":"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"}

package/dist/resources/sandboxes.js

@@ -1,7 +1,9 @@
 import { ensureData, ensureModel } from "../response.js";
-import { wrapApiCall } from "../errors.js";
+import { SandboxWaitTimeoutError, wrapApiCall } from "../errors.js";
 import { Sandbox as SandboxHandle } from "../sandbox.js";
 import { SandboxSession } from "../sessions.js";
+const DEFAULT_LIFECYCLE_TIMEOUT_MS = 60_000;
+const DEFAULT_LIFECYCLE_POLL_INTERVAL_MS = 500;
 function isClaimSandboxOptions(value) {
     return !!value && typeof value === "object" && ("config" in value ||
         "mounts" in value ||
@@ -74,9 +76,39 @@ export class Sandboxes {
         });
     }
     async get(sandboxId) {
-        const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdGet({ id: sandboxId }));
+        return this.getWithSignal(sandboxId);
+    }
+    async getWithSignal(sandboxId, signal) {
+        const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdGet({ id: sandboxId }, signal ? { signal } : undefined));
         return ensureData(response, "get sandbox returned empty response");
     }
+    /**
+     * Polls committed sandbox details until the predicate matches.
+     *
+     * Abort stops the local wait but cannot undo a lifecycle request that the
+     * server has already accepted.
+     */
+    async waitForLifecycle(sandboxId, predicate, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_LIFECYCLE_TIMEOUT_MS;
+        const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_LIFECYCLE_POLL_INTERVAL_MS;
+        validateWaitDuration("timeoutMs", timeoutMs, true);
+        validateWaitDuration("pollIntervalMs", pollIntervalMs, false);
+        const startedAt = Date.now();
+        let lastSandbox;
+        while (true) {
+            throwIfAborted(options.signal);
+            lastSandbox = await this.getWithSignal(sandboxId, options.signal);
+            throwIfAborted(options.signal);
+            if (await predicate(lastSandbox)) {
+                return lastSandbox;
+            }
+            const remainingMs = timeoutMs - (Date.now() - startedAt);
+            if (remainingMs <= 0) {
+                throw new SandboxWaitTimeoutError({ sandboxId, timeoutMs, lastSandbox });
+            }
+            await sleepWithSignal(Math.min(pollIntervalMs, remainingMs), options.signal);
+        }
+    }
     async update(sandboxId, request) {
         const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdPut({
             id: sandboxId,
@@ -103,10 +135,29 @@ export class Sandboxes {
         const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdPausePost({ id: sandboxId }));
         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);
+        await this.pause(sandboxId);
+        return this.waitForLifecycle(sandboxId, (sandbox) => sandbox.status === "paused" && sandbox.paused, options);
+    }
     async resume(sandboxId) {
         const response = await wrapApiCall(() => this.client.apispec.sandboxes.apiV1SandboxesIdResumePost({ id: sandboxId }));
         return ensureData(response, "resume sandbox returned empty response");
     }
+    /** Requests a resume and waits for the committed running generation. */
+    async resumeAndWait(sandboxId, options) {
+        throwIfAborted(options?.signal);
+        const before = await this.getWithSignal(sandboxId, options?.signal);
+        throwIfAborted(options?.signal);
+        await this.resume(sandboxId);
+        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);
+    }
     async refresh(sandboxId, request) {
         const params = request
             ? { id: sandboxId, sandboxRefreshRequest: request }
@@ -156,3 +207,56 @@ export class Sandboxes {
         return new SandboxHandle({ id: sandboxId, client: this.client });
     }
 }
+function validateWaitDuration(name, value, allowZero) {
+    if (!Number.isFinite(value) || (allowZero ? value < 0 : value <= 0)) {
+        const requirement = allowZero ? "a finite number >= 0" : "a finite number > 0";
+        throw new RangeError(`${name} must be ${requirement}`);
+    }
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted) {
+        return;
+    }
+    throw abortReason(signal);
+}
+function abortReason(signal) {
+    if (signal.reason !== undefined) {
+        return signal.reason;
+    }
+    const error = new Error("sandbox lifecycle wait was aborted");
+    error.name = "AbortError";
+    return error;
+}
+function sleepWithSignal(durationMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        let settled = false;
+        let timer;
+        const onAbort = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            signal?.removeEventListener("abort", onAbort);
+            reject(signal ? abortReason(signal) : new Error("sandbox lifecycle wait was aborted"));
+        };
+        timer = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, durationMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) {
+            onAbort();
+        }
+    });
+}

package/package.json

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