@aerol-ai/aerolvm-sdk 0.1.1 → 0.1.3

package/dist/MicroVM.d.ts

@@ -19,6 +19,7 @@ export declare class MicroVM {
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<Sandbox>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<Sandbox>;
+    reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
     mounts(sandboxID: string): Promise<MountSpecRedacted[]>;
     execStream(sandboxID: string, options: ExecStreamOptions): ExecStreamHandle;

package/dist/MicroVM.js

@@ -51,6 +51,9 @@ export class MicroVM {
         const sandbox = await this.client.updateLifecycle(id, lifecycle);
         return this.wrap(sandbox.toJSON());
     }
+    async reconcile() {
+        await this.client.reconcile();
+    }
     async health() {
         return this.client.health();
     }

package/dist/internal/client.d.ts

@@ -33,6 +33,7 @@ export declare class APIClient {
     downloadFile(id: string, targetPath: string): Promise<Uint8Array>;
     exposePort(id: string, port: number): Promise<string>;
     unexposePort(id: string, port: number): Promise<void>;
+    reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
     private wrap;

package/dist/internal/client.js

@@ -99,6 +99,9 @@ export class APIClient {
     async unexposePort(id, port) {
         await this.doJSON("DELETE", `/v1/sandboxes/${id}/ports/${port}`);
     }
+    async reconcile() {
+        await this.doJSON("POST", "/v1/admin/reconcile");
+    }
     async health() {
         const response = await this.doJSON("GET", "/health");
         return fromApiHealthStatus(response);
@@ -439,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;
@@ -450,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) => {
@@ -510,11 +546,19 @@ function openExecStream(baseURL, patToken, sandboxID, options) {
             options.onStderr?.(payload);
         }
     });
-    ws.addEventListener("close", () => {
-        finishWith({ code: 0 });
+    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;
@@ -530,7 +574,6 @@ function openExecStream(baseURL, patToken, sandboxID, options) {
         },
         close() {
             ws.send(JSON.stringify({ type: "close" }));
-            ws.close();
         },
         done,
     };
@@ -550,6 +593,7 @@ function openSessionAttach(baseURL, patToken, sandboxID, sessionID, options) {
         exitReject = reject;
     });
     let settled = false;
+    let lastErrorDetail = "";
     const finishWith = (info) => {
         if (settled)
             return;
@@ -600,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,8 @@
     "build": "tsc -p tsconfig.json",
     "example:create": "npm run build && node dist/examples/createSandbox.js",
     "example:create:src": "npx tsx src/examples/createSandbox.ts",
+    "example:delete": "npm run build && node dist/examples/deleteSandbox.js",
+    "example:delete:src": "npx tsx src/examples/deleteSandbox.ts",
     "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js"
   },
   "devDependencies": {