@molecule/api-code-sandbox-e2b 1.2.0 → 1.2.2

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-16T01:25:40.978Z
+Generated: 2026-08-16T14:04:34.100Z
 -->
 
 # @molecule/api-code-sandbox-e2b
@@ -441,7 +441,7 @@ export function setupCodeSandboxE2b(): void {
 Peer dependencies:
 
 - `@molecule/api-bond` ^1.0.1
-- `@molecule/api-code-sandbox` ^1.0.1
+- `@molecule/api-code-sandbox` ^1.2.0
 - `@molecule/api-i18n` ^1.0.1
 
 ### Environment Variables

package/dist/provider.d.ts

@@ -237,6 +237,20 @@ export declare class E2BSandboxProvider implements SandboxProvider {
      * @returns The observed egress verdict.
      */
     verifyEgress(): Promise<EgressVerdict>;
+    /**
+     * Destroy an egress-probe sandbox, retrying once.
+     *
+     * @param id - The probe sandbox id.
+     * @returns Null when it was destroyed, else a sentence naming the leaked sandbox.
+     */
+    private destroyProbe;
+    /**
+     * Run the egress checks inside an already-created probe sandbox.
+     *
+     * @param handle - The probe sandbox.
+     * @returns The observed verdict; any failure is `inconclusive`.
+     */
+    private probeEgress;
 }
 /**
  * Create an E2B provider with the given configuration.

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAErB,aAAa,EAKb,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,eAAe,EAGf,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAGV,SAAS,EACT,oBAAoB,EAMrB,MAAM,YAAY,CAAA;AAkvBnB;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,SAAQ;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IACjF,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsB;IAEtD;;;;;OAKG;gBACS,MAAM,GAAE,SAAc,EAAE,cAAc,CAAC,EAAE,oBAAoB;IAYzE;;;;OAIG;YACW,MAAM;IASpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IA+BrD;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAoB9C;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkC7D;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAgB/C;;;;OAIG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;OASG;YACW,aAAa;IAM3B;;;;;OAKG;YACW,UAAU;IASxB;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAmBtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B9E;;;;;;;;;OASG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoBtE;;;;;;;;;OASG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAmB/E;;;;;;;;;;OAUG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;CAyD7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,GAAE,SAAc,EACtB,cAAc,CAAC,EAAE,oBAAoB,GACpC,kBAAkB,CAEpB;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,eAAkC,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAErB,aAAa,EAKb,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,eAAe,EAGf,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAGV,SAAS,EACT,oBAAoB,EAMrB,MAAM,YAAY,CAAA;AAkvBnB;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,SAAQ;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IACjF,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsB;IAEtD;;;;;OAKG;gBACS,MAAM,GAAE,SAAc,EAAE,cAAc,CAAC,EAAE,oBAAoB;IAYzE;;;;OAIG;YACW,MAAM;IASpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IA4CrD;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAoB9C;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkC7D;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAgB/C;;;;OAIG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;OASG;YACW,aAAa;IAM3B;;;;;OAKG;YACW,UAAU;IASxB;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAmBtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B9E;;;;;;;;;OASG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoBtE;;;;;;;;;OASG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAmB/E;;;;;;;;;;OAUG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;IAoB5C;;;;;OAKG;YACW,YAAY;IAa1B;;;;;OAKG;YACW,WAAW;CAsC1B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,GAAE,SAAc,EACtB,cAAc,CAAC,EAAE,oBAAoB,GACpC,kBAAkB,CAEpB;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,eAAkC,CAAA"}

package/dist/provider.js

@@ -800,7 +800,18 @@ export class E2BSandboxProvider {
         });
         // Apply the egress allow-list immediately, before any user code runs.
         if (this.config.defaultAllowOut.length > 0) {
-            await handle.applyNetwork(this.config.defaultAllowOut);
+            try {
+                await handle.applyNetwork(this.config.defaultAllowOut);
+            }
+            catch (error) {
+                // The sandbox exists on E2B but the caller never receives its handle, so
+                // nothing else can ever destroy it: it would run until its timeout and
+                // then sit paused (billed storage) forever. Kill it before rethrowing.
+                await this.destroy(sbx.sandboxId).catch((destroyError) => {
+                    throw new Error(`E2B sandbox ${sbx.sandboxId} was created but its egress policy failed to apply, and destroying it failed too — it is orphaned: ${destroyError instanceof Error ? destroyError.message : String(destroyError)}`, { cause: error });
+                });
+                throw error;
+            }
         }
         return handle;
     }
@@ -1180,7 +1191,7 @@ export class E2BSandboxProvider {
      * @returns The observed egress verdict.
      */
     async verifyEgress() {
-        let handle = null;
+        let handle;
         try {
             handle = await this.create({ projectId: `egress-probe-${Date.now()}`, env: {} });
         }
@@ -1191,6 +1202,40 @@ export class E2BSandboxProvider {
                 remediation: 'Check E2B_API_KEY and account capacity.',
             };
         }
+        const verdict = await this.probeEgress(handle);
+        // The probe sandbox is destroyed on EVERY path. A failed destroy is retried,
+        // and one that still fails is reported in the verdict's detail: the sandbox
+        // was created to pause at its timeout, so a silently leaked probe is billed
+        // storage forever.
+        const leaked = await this.destroyProbe(handle.id);
+        return leaked ? { ...verdict, detail: `${verdict.detail} ${leaked}` } : verdict;
+    }
+    /**
+     * Destroy an egress-probe sandbox, retrying once.
+     *
+     * @param id - The probe sandbox id.
+     * @returns Null when it was destroyed, else a sentence naming the leaked sandbox.
+     */
+    async destroyProbe(id) {
+        let lastError = null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                await this.destroy(id);
+                return null;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        return `(The probe sandbox ${id} could not be destroyed and is left behind: ${lastError instanceof Error ? lastError.message : String(lastError)}.)`;
+    }
+    /**
+     * Run the egress checks inside an already-created probe sandbox.
+     *
+     * @param handle - The probe sandbox.
+     * @returns The observed verdict; any failure is `inconclusive`.
+     */
+    async probeEgress(handle) {
         try {
             // Force a KNOWN deny-default policy for the probe regardless of config.
             await handle.applyNetwork([
@@ -1222,16 +1267,6 @@ export class E2BSandboxProvider {
                 detail: `Egress probe could not run: ${error instanceof Error ? error.message : String(error)}`,
             };
         }
-        finally {
-            // Best-effort cleanup of the throwaway probe sandbox; a failed destroy
-            // must not mask the verdict (E2B auto-pauses idle sandboxes regardless).
-            if (handle) {
-                await this.destroy(handle.id).catch((_error) => {
-                    // intentional noop — probe teardown is best-effort; the sandbox
-                    // auto-pauses and the verdict is what matters.
-                });
-            }
-        }
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-e2b",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "E2B (e2b.dev) code sandbox provider — Firecracker microVMs with golden templates, fork, and pause/resume",
   "type": "module",
   "main": "dist/index.js",
@@ -29,11 +29,11 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@molecule/api-bond": "1.0.1",
-    "@molecule/api-code-sandbox": "1.2.0",
+    "@molecule/api-bond": "1.0.2",
+    "@molecule/api-code-sandbox": "1.2.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "@molecule/api-bond": "^1.0.1",
@@ -50,7 +50,7 @@
     "url": "https://github.com/molecule-dev/molecule.git",
     "directory": "packages/api/bonds/code-sandbox/e2b"
   },
-  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/code-sandbox/e2b",
+  "homepage": "https://www.molecule.dev/packages/api-code-sandbox-e2b",
   "bugs": "https://github.com/molecule-dev/molecule/issues",
   "publishConfig": {
     "access": "public"