@archildata/api-types 0.0.7 → 0.0.9

package/index.d.ts

@@ -431,6 +431,53 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/sandboxes/{sid}/pause": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pause a sandbox
+         * @description Snapshot the CPU & memory state, then stop the VM. The sandbox reports
+         *     `pausing` until the snapshot commit marker is durable and the VM exits,
+         *     then reports `paused`. Any in-flight execs are cancelled. A sandbox
+         *     that is still `pending` must reach `running` before it can be paused.
+         *     To restore the snapshot, call `/resume`.
+         */
+        post: operations["pauseSandbox"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/sandboxes/{sid}/resume": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Resume a sandbox
+         * @description Restores a paused sandbox's committed CPU and memory snapshot.
+         *     Resuming a running sandbox or a pending resume is idempotent. Only a
+         *     `paused` sandbox can begin a new resume; `stopped`, `exited`, `failed`,
+         *     `stopping`, `pausing`, or a pending cold start returns 409.
+         */
+        post: operations["resumeSandbox"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/sandboxes/{sid}/start": {
         parameters: {
             query?: never;
@@ -441,10 +488,12 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Start or restart a sandbox
-         * @description Cold-boots the sandbox from its persisted configuration and disks. RAM
-         *     and process state are not restored. Starting a pending or running
-         *     sandbox is idempotent; a sandbox that is still stopping returns 409.
+         * Cold-start a sandbox
+         * @description Cold-boots from the persisted configuration and disks. If the sandbox
+         *     was paused, its memory snapshot is consumed and discarded before the
+         *     new VM runs; disk state remains. Starting a running sandbox or a pending
+         *     cold start is idempotent. A sandbox that is stopping, pausing, or
+         *     pending a resume returns 409.
          */
         post: operations["startSandbox"];
         delete?: never;
@@ -463,9 +512,11 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Stop a sandbox
-         * @description Shuts down the sandbox VM without taking a memory snapshot. The sandbox
-         *     identity, configuration, and disks remain available for a later start.
+         * Stop a sandbox without saving memory
+         * @description Shuts down the VM without creating a memory snapshot. When the sandbox
+         *     is paused, this invalidates its committed snapshot and changes it to
+         *     `stopped`. The sandbox's identity, configuration, and disk state remain
+         *     available for a later cold start.
          */
         post: operations["stopSandbox"];
         delete?: never;
@@ -529,7 +580,7 @@ export interface components {
             };
         };
         /** @enum {string} */
-        SandboxState: "pending" | "running" | "stopping" | "stopped" | "exited" | "failed";
+        SandboxState: "pending" | "running" | "pausing" | "paused" | "stopping" | "stopped" | "exited" | "failed";
         Sandbox: {
             /** Format: uuid */
             sandbox_id: string;
@@ -539,6 +590,13 @@ export interface components {
             /** @description Full lifetime budget applied independently to each powered-on session. */
             max_ttl_seconds: number;
             max_concurrent_execs: number;
+            /** @description OCI reference requested when the sandbox was created. */
+            base_image: string;
+            /**
+             * @description Sandbox CPU architecture.
+             * @enum {string}
+             */
+            platform?: "arm64" | "amd64";
             endpoints?: components["schemas"]["SandboxEndpoint"][];
             /** Format: date-time */
             created_at: string;
@@ -594,7 +652,7 @@ export interface components {
             mem_size_mib?: number;
             kernel?: string;
             /**
-             * @description Base image for the sandbox root. Currently only `ubuntu:26.04` is supported.
+             * @description Public Linux OCI image reference. Docker shorthand and tags are accepted; the selected platform manifest is pinned at creation.
              * @default ubuntu:26.04
              */
             base_image: string;
@@ -1438,6 +1496,15 @@ export interface components {
                 "application/json": components["schemas"]["ErrorResponse"];
             };
         };
+        /** @description The lifecycle transition is temporarily blocked and can be retried */
+        RetryableUnavailable: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
     };
     parameters: {
         /** @description Disk ID (format `dsk-{16 hex chars}`) */
@@ -2248,6 +2315,101 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    pauseSandbox: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Sandbox UUID */
+                sid: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The sandbox was already inactive */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_Sandbox"];
+                };
+            };
+            /** @description The sandbox pause is in progress */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_Sandbox"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            /** @description The sandbox is still starting, or a plain stop is already in progress */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["RetryableUnavailable"];
+        };
+    };
+    resumeSandbox: {
+        parameters: {
+            query?: {
+                /** @description Hold the request for a completed start or exec result */
+                wait?: components["parameters"]["Wait"];
+            };
+            header?: never;
+            path: {
+                /** @description Sandbox UUID */
+                sid: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The sandbox was already running */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_Sandbox"];
+                };
+            };
+            /** @description The sandbox resume is pending */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_Sandbox"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            /** @description The sandbox is not paused, is shutting down, or a cold start is already in progress */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["RetryableUnavailable"];
+        };
+    };
     startSandbox: {
         parameters: {
             query?: {
@@ -2284,7 +2446,7 @@ export interface operations {
             400: components["responses"]["ValidationError"];
             401: components["responses"]["Unauthorized"];
             404: components["responses"]["NotFound"];
-            /** @description The previous VM is still stopping */
+            /** @description The previous VM is stopping or pausing, or a resume is already in progress */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -2294,6 +2456,7 @@ export interface operations {
                 };
             };
             500: components["responses"]["InternalError"];
+            503: components["responses"]["RetryableUnavailable"];
         };
     };
     stopSandbox: {
@@ -2329,7 +2492,17 @@ export interface operations {
             400: components["responses"]["ValidationError"];
             401: components["responses"]["Unauthorized"];
             404: components["responses"]["NotFound"];
+            /** @description A pause is already in progress */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
             500: components["responses"]["InternalError"];
+            503: components["responses"]["RetryableUnavailable"];
         };
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archildata/api-types",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "API types for the Archil control plane",
   "type": "module",
   "types": "index.d.ts",