@aerol-ai/aerolvm-sdk 0.1.2 → 0.1.4

package/dist/MicroVM.js

@@ -1,6 +1,6 @@
 import { APIClient } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
-const defaultAPIURL = "http://127.0.0.1:8080";
+const defaultAPIURL = "http://127.0.0.1:21212";
 const authRequiredErrorMessage = "PAT token is required. Set patToken or SB_PAT_TOKEN.";
 export class MicroVM {
     apiUrl;

package/dist/internal/client.js

@@ -442,6 +442,35 @@ async function decodeError(response) {
 }
 const STREAM_PREFIX_STDOUT = 0x01;
 const STREAM_PREFIX_STDERR = 0x02;
+// Pull whatever diagnostic detail the runtime gave us off a WebSocket "error"
+// event. Node 22's native WebSocket fires an ErrorEvent with `.error` /
+// `.message`; browsers' base WebSocket fires a bare Event. Returns "" when
+// nothing useful is there so callers can fall back to a generic label.
+function describeWSError(event) {
+    if (!event || typeof event !== "object")
+        return "";
+    const e = event;
+    if (e.error instanceof Error && e.error.message)
+        return e.error.message;
+    if (typeof e.error === "string" && e.error !== "")
+        return e.error;
+    if (typeof e.message === "string" && e.message !== "")
+        return e.message;
+    return "";
+}
+function describeWSClose(event) {
+    if (!event || typeof event !== "object")
+        return "";
+    const e = event;
+    const parts = [];
+    if (typeof e.code === "number")
+        parts.push(`code=${e.code}`);
+    if (typeof e.reason === "string" && e.reason !== "")
+        parts.push(`reason=${JSON.stringify(e.reason)}`);
+    if (typeof e.wasClean === "boolean")
+        parts.push(`wasClean=${e.wasClean}`);
+    return parts.join(" ");
+}
 function openExecStream(baseURL, patToken, sandboxID, options) {
     const wsURL = baseURL.replace(/^http/, "ws") + `/v1/sandboxes/${encodeURIComponent(sandboxID)}/toolbox/process/exec/stream`;
     const WS = globalThis.WebSocket;
@@ -453,6 +482,10 @@ function openExecStream(baseURL, patToken, sandboxID, options) {
     // `sandbox.bearer, <token>`.
     const ws = new WS(wsURL, ["sandbox.bearer", patToken]);
     ws.binaryType = "arraybuffer";
+    // Captured by the "error" listener and consumed by "close" so we report the
+    // root cause (e.g. "Unexpected server response: 502") rather than the
+    // generic "stream closed before exit" that would otherwise win the race.
+    let lastErrorDetail = "";
     let exitResolve;
     let exitReject;
     const done = new Promise((resolve, reject) => {
@@ -513,11 +546,19 @@ function openExecStream(baseURL, patToken, sandboxID, options) {
             options.onStderr?.(payload);
         }
     });
-    ws.addEventListener("close", () => {
-        failWith("stream closed before exit");
+    ws.addEventListener("close", (event) => {
+        const closeDetail = describeWSClose(event);
+        const parts = [lastErrorDetail, closeDetail].filter((s) => s !== "");
+        const suffix = parts.length > 0 ? ` (${parts.join("; ")})` : "";
+        failWith(`stream closed before exit${suffix}`);
     });
-    ws.addEventListener("error", () => {
-        failWith("websocket error");
+    ws.addEventListener("error", (event) => {
+        const detail = describeWSError(event);
+        if (detail !== "") {
+            lastErrorDetail = detail;
+        }
+        options.onError?.(detail !== "" ? detail : "websocket error");
+        failWith(detail !== "" ? `websocket error: ${detail}` : "websocket error");
     });
     const sendBinary = (data) => {
         const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
@@ -552,6 +593,7 @@ function openSessionAttach(baseURL, patToken, sandboxID, sessionID, options) {
         exitReject = reject;
     });
     let settled = false;
+    let lastErrorDetail = "";
     const finishWith = (info) => {
         if (settled)
             return;
@@ -602,13 +644,21 @@ function openSessionAttach(baseURL, patToken, sandboxID, sessionID, options) {
             options.onStderr?.(payload);
         }
     });
-    ws.addEventListener("close", () => {
+    ws.addEventListener("close", (event) => {
         if (!settled) {
-            failWith("session stream closed before exit");
+            const closeDetail = describeWSClose(event);
+            const parts = [lastErrorDetail, closeDetail].filter((s) => s !== "");
+            const suffix = parts.length > 0 ? ` (${parts.join("; ")})` : "";
+            failWith(`session stream closed before exit${suffix}`);
         }
     });
-    ws.addEventListener("error", () => {
-        failWith("websocket error");
+    ws.addEventListener("error", (event) => {
+        const detail = describeWSError(event);
+        if (detail !== "") {
+            lastErrorDetail = detail;
+        }
+        options.onError?.(detail !== "" ? detail : "websocket error");
+        failWith(detail !== "" ? `websocket error: ${detail}` : "websocket error");
     });
     const sendBinary = (data) => {
         const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;

package/dist/types.d.ts

@@ -32,6 +32,34 @@ export interface Lifecycle {
     destroyAtAge?: number;
 }
 export type UpdateLifecycleOptions = Lifecycle;
+export type GPUVendor = "nvidia" | "amd" | "apple";
+export interface GPUOptions {
+    /**
+     * GPU hardware vendor. Required when gpus is set.
+     * - "nvidia": NVIDIA GPUs via nvidia-container-runtime. Requires
+     *   nvidia-container-toolkit on the host.
+     * - "amd": AMD GPUs via ROCm (/dev/kfd + /dev/dri). Requires ROCm
+     *   drivers on the host.
+     * - "apple": Apple Silicon GPU via Docker Desktop's experimental Metal
+     *   support. Only functional on macOS with Docker Desktop.
+     *
+     * GPU access is not supported with runtime="gvisor" — the API returns
+     * an error if both gpus and runtime="gvisor" are set.
+     */
+    vendor: GPUVendor;
+    /**
+     * Number of GPUs to allocate. Use -1 to request all GPUs on the host.
+     * Defaults to 1 when omitted. Ignored for AMD (all AMD GPUs are exposed
+     * via /dev/kfd and /dev/dri).
+     */
+    count?: number;
+    /**
+     * Pin the sandbox to specific GPU device indices or UUIDs.
+     * For NVIDIA: indices ("0", "1") or UUIDs ("GPU-abc123...").
+     * For AMD and Apple: ignored.
+     */
+    deviceIDs?: string[];
+}
 export interface CreateOptions {
     image: string;
     /** Number of CPU cores to allocate. Fractional values are supported (e.g. 0.5 = half a core). */
@@ -52,8 +80,15 @@ export interface CreateOptions {
      * privileged containers and ignores per-sandbox disk quotas. `"kata"` is
      * reserved for future Kata Containers support and is rejected by the API
      * today.
+     *
+     * GPU access is not supported with `"gvisor"`.
      */
     runtime?: "docker" | "gvisor" | "kata";
+    /**
+     * Attach GPU resources to the sandbox. Omit for CPU-only workloads.
+     * Not compatible with runtime="gvisor".
+     */
+    gpus?: GPUOptions;
 }
 export interface ResizeOptions {
     /** Number of CPU cores. Fractional values supported (e.g. 0.5). */
@@ -122,6 +157,8 @@ export interface Sandbox {
      * a pre-migration row that resolves to the host default at start time.
      */
     runtime: "" | "docker" | "gvisor" | "kata";
+    /** GPU configuration this sandbox was created with. Absent means no GPU. */
+    gpus?: GPUOptions;
 }
 export interface ExecRequest {
     command: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",