@molecule/api-code-sandbox-e2b 1.2.7 → 1.2.9

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-10-05T07:29:02.107Z
+Generated: 2026-10-09T06:56:17.299Z
 -->
 
 # @molecule/api-code-sandbox-e2b
@@ -396,11 +396,14 @@ interface EgressProbeCodes {
 
 E2B implementation of {@link SandboxProvider}.
 
-Only the required surface (`create`/`get`/`list`/`destroy`) plus the boot-path
-optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
-land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
-the control plane treats "unsupported" as `inconclusive` and refuses to boot
-in prod, which is the correct safe default until egress observation is proven.
+The required surface (`create`/`get`/`list`/`destroy`) plus the optionals the
+control plane uses are all wired here: `describe`, volumes
+(`createVolume`/`removeVolume`/`volumeExists`/`listVolumes`), snapshots
+(`commitTemplate`/`getTemplate`/`listTemplates`/`removeTemplate`) and
+`verifyEgress`. `verifyEgress` proves deny-by-default by OBSERVING a
+throwaway probe sandbox, and answers `inconclusive` whenever it cannot look —
+a failed create, a dead probe — so "could not observe" never wears the shape
+of the safe verdict.
 
 ### Functions
 

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-code-sandbox-e2b` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-code-sandbox-e2b is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -160,6 +160,7 @@
  *
  * @module
  */
+export * from './browser-guard.js';
 export * from './provider.js';
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiKG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiKG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -160,5 +160,6 @@
  *
  * @module
  */
+export * from './browser-guard.js';
 export * from './provider.js';
 export * from './types.js';

package/dist/provider.d.ts

@@ -13,11 +13,14 @@ import type { E2BConfig, E2BSandboxClientLike } from './types.js';
 /**
  * E2B implementation of {@link SandboxProvider}.
  *
- * Only the required surface (`create`/`get`/`list`/`destroy`) plus the boot-path
- * optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
- * land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
- * the control plane treats "unsupported" as `inconclusive` and refuses to boot
- * in prod, which is the correct safe default until egress observation is proven.
+ * The required surface (`create`/`get`/`list`/`destroy`) plus the optionals the
+ * control plane uses are all wired here: `describe`, volumes
+ * (`createVolume`/`removeVolume`/`volumeExists`/`listVolumes`), snapshots
+ * (`commitTemplate`/`getTemplate`/`listTemplates`/`removeTemplate`) and
+ * `verifyEgress`. `verifyEgress` proves deny-by-default by OBSERVING a
+ * throwaway probe sandbox, and answers `inconclusive` whenever it cannot look —
+ * a failed create, a dead probe — so "could not observe" never wears the shape
+ * of the safe verdict.
  */
 export declare class E2BSandboxProvider implements SandboxProvider {
     readonly name = "e2b";

package/dist/provider.d.ts.map

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

package/dist/provider.js

@@ -26,6 +26,58 @@ const DEFAULT_SPAWN_TIMEOUT_MS = 60 * 60 * 1000;
  * this instead of the caller's whole timeout.
  */
 const SETTLE_PROBE_MS = 1_500;
+/**
+ * How long to wait for the handle to REPORT the exit code after the started pid
+ * is confirmed gone. envd closes the output stream right behind a real exit, so
+ * a finished command's `end` event — the only thing that carries its exit code —
+ * lands within this window; only a stream held by a stranded descendant
+ * outlives it.
+ */
+const EXIT_REPORT_GRACE_MS = 2_000;
+/**
+ * The exit code reported when a command's outcome cannot be observed at all:
+ * the started pid is gone but the stream it was reading is still held, so the
+ * SDK never delivers the `end` event that carries the real code. 128+SIGKILL
+ * (137), the conventional status of a killed process — because "unknown" must
+ * read as failure, never as the fabricated `0` that once reported a killed
+ * build (partial `dist/` and all) as a successful one.
+ */
+const EXIT_CODE_UNKNOWN = 137;
+/**
+ * How many sandbox connects {@link E2BSandboxProvider.list} keeps in flight at
+ * once. Each handle costs a full connect round trip — on the real SDK, a live
+ * websocket to the sandbox's envd — and `list()` is what a control-plane sweep
+ * polls, so putting ALL N running sandboxes in flight at once spends N sockets
+ * and file descriptors per poll and walks straight into the API's concurrency
+ * limits. A bounded window keeps the sweep concurrent (O(⌈N/16⌉) round trips
+ * deep, not N) without the per-poll fan-out growing with the fleet.
+ */
+const LIST_CONNECT_CONCURRENCY = 16;
+/**
+ * Maps `items` through `fn` with at most `limit` calls in flight, preserving
+ * order in the result. The first rejection propagates (the remaining
+ * in-flight calls still run to completion, their results discarded) — the
+ * same fail-fast `Promise.all` gives, without its unbounded concurrency.
+ *
+ * @param items - The items to map.
+ * @param limit - Maximum concurrent `fn` calls.
+ * @param fn - The async mapping.
+ * @returns The results, in `items` order.
+ */
+async function mapWithConcurrency(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            out[index] = await fn(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
 /** Default lifetime for a PTY session; same reasoning as {@link DEFAULT_SPAWN_TIMEOUT_MS}. */
 const DEFAULT_PTY_TIMEOUT_MS = 60 * 60 * 1000;
 /**
@@ -39,6 +91,32 @@ const ALL_TRAFFIC = '0.0.0.0/0';
 /** Hosts the egress probe treats as the canonical allow/deny witnesses. */
 const EGRESS_PROBE_ALLOW = 'registry.npmjs.org';
 const EGRESS_PROBE_DENY = 'example.com';
+/**
+ * Race a promise against a one-shot timer, CLEARING the timer the moment the
+ * race settles — win, lose, or reject. The bare `Promise.race` leaves the
+ * losing timer armed: resolving into an already-settled race is a no-op, but
+ * the timer itself stays on the event loop for its whole window, so every
+ * call whose command finishes first kept an otherwise-done short-lived
+ * process (test worker, CLI script) alive up to the window per call.
+ *
+ * @param promise - The promise to wait on.
+ * @param ms - The timeout window in milliseconds.
+ * @returns The promise's value, or null when the window elapsed first.
+ */
+async function raceWithClearedTimer(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /**
  * Adapt the real `e2b` SDK `Sandbox` class to {@link E2BSandboxClientLike}.
  * Imported lazily so the SDK is only required when the bond is actually used.
@@ -91,6 +169,14 @@ async function defaultClient(apiKey) {
                             volumeMounts: it.volumeMounts,
                         });
             };
+            // A rejected listing (the promise-of-array SDK shape) must THROW, never
+            // degrade to `[]`: every consumer of this listing reads emptiness as
+            // absence (`list()`: no live sandboxes; `listVolumes()`: every volume
+            // unattached; `listTemplates()`: no template in use). The trailing
+            // `.catch(() => result)` is inert to that — a catch handler that
+            // returns the SAME rejected promise re-rejects the await below, so the
+            // failure always reaches the caller (pinned in
+            // __tests__/client-list-shapes.test.ts).
             const r = await Promise.resolve(result).catch(() => result);
             if (Array.isArray(r)) {
                 push(r);
@@ -109,6 +195,26 @@ async function defaultClient(apiKey) {
             else if (r && Array.isArray(r.sandboxes)) {
                 push(r.sandboxes);
             }
+            else {
+                // An UNRECOGNIZED shape (a minor SDK change — a new pager wrapper, an
+                // `{ items: [...] }` envelope, a bare null) must THROW, never fall
+                // through to `[]`: every consumer of this listing reads EMPTINESS as
+                // ABSENCE (`list()`: no live sandboxes; `listVolumes()`: every volume
+                // unattached; `getTemplate`/`listTemplates()`: no template in use —
+                // and an eviction/reclamation sweep deletes on that answer, destroying
+                // resources live sandboxes are still using). An unreadable listing is
+                // a failure to LOOK, and this bond's contracts never deliver that as
+                // "looked, and nothing exists".
+                let seen;
+                try {
+                    seen = JSON.stringify(r) ?? String(r);
+                }
+                catch (_error) {
+                    // Unserializable (a cyclic wrapper) — the type is the diagnosable part.
+                    seen = typeof r;
+                }
+                throw new Error(`e2b: Sandbox.list() returned a shape this adapter cannot read (${seen.slice(0, 200)}) — refusing to answer an empty listing, since every consumer of it reads emptiness as absence`);
+            }
             return out;
         },
     };
@@ -309,6 +415,14 @@ class E2BSandbox {
      * running and the caller's own timeout is the right bound. Never a guess from
      * the shape of the command.
      *
+     * But "over" is not "succeeded": the SDK delivers the exit code on the
+     * stream's `end` event, and the descendant holding the stream keeps that
+     * event from ever arriving. A gone pid therefore gets a bounded grace window
+     * for the handle to report the real code, and a handle that never does is
+     * reported as {@link EXIT_CODE_UNKNOWN} — failure — because an outcome that
+     * cannot be observed (a build OOM-killed mid-run) must never be fabricated
+     * into success.
+     *
      * @param handle - The started command.
      * @returns The command's result.
      */
@@ -317,10 +431,7 @@ class E2BSandbox {
         const finished = handle.wait().finally(() => {
             settled = true;
         });
-        const raced = await Promise.race([
-            finished,
-            new Promise((resolve) => setTimeout(() => resolve(null), SETTLE_PROBE_MS)),
-        ]);
+        const raced = await raceWithClearedTimer(finished, SETTLE_PROBE_MS);
         if (raced)
             return raced;
         if (settled)
@@ -328,11 +439,26 @@ class E2BSandbox {
         const alive = await this.isProcessAlive(handle.pid);
         if (alive)
             return finished;
-        // The process is gone; whatever still holds the stream is not it.
+        // The process is gone; whatever still holds the stream is not it. The real
+        // exit code rides the stream's `end` event, so give the handle a bounded
+        // window to deliver it — when the process truly finished, envd closes the
+        // stream right behind it and the result lands here.
+        const reported = await raceWithClearedTimer(finished, EXIT_REPORT_GRACE_MS);
+        if (reported)
+            return reported;
+        if (typeof handle.exitCode === 'number') {
+            return { stdout: handle.stdout ?? '', stderr: handle.stderr ?? '', exitCode: handle.exitCode };
+        }
+        // Still nothing: the exit code is UNKNOWN. Reporting `0` here used to
+        // fabricate success for exactly this shape — a killed build whose stranded
+        // daemon held the stream shipped its partial `dist/` as a finished site —
+        // so fail closed instead, with a line that says why the code is missing.
+        const unknownNote = `e2b: exit code unknown — the started process (pid ${handle.pid}) is gone but its ` +
+            'output stream is still held, so its real outcome cannot be observed; reporting failure';
         return {
             stdout: handle.stdout ?? '',
-            stderr: handle.stderr ?? '',
-            exitCode: handle.exitCode ?? 0,
+            stderr: handle.stderr ? `${handle.stderr}\n${unknownNote}` : unknownNote,
+            exitCode: EXIT_CODE_UNKNOWN,
         };
     }
     /**
@@ -642,6 +768,36 @@ class E2BSandbox {
         // Returning a no-op unsubscribe keeps callers that register-and-forget safe.
         return () => { };
     }
+    /**
+     * Run a short, self-contained command to completion and return its result as
+     * data. The SDK's inline `commands.run()` (no `background`) THROWS
+     * `CommandExitError` on a non-zero exit — it never returns one — so an
+     * `r.exitCode !== 0` check after a bare `await run()` is dead code in
+     * production: the caller saw a bare `CommandExitError` ("exit status N") with
+     * no stage name and no stderr, and only the test fakes (which return the
+     * result) made those checks look live. Mapping the thrown `.result` back to
+     * data here — the same mapping `exec()`'s catch applies — makes the callers'
+     * exit-code checks real on both shapes.
+     *
+     * @param cmd - The shell command to run.
+     * @param timeoutMs - Deadline for the command in milliseconds.
+     * @returns stdout, stderr and the exit code (even when non-zero).
+     */
+    async runCommand(cmd, timeoutMs) {
+        try {
+            return await this.sbx.commands.run(cmd, { timeoutMs });
+        }
+        catch (error) {
+            // A non-zero exit arrives as CommandExitError carrying `.result` — map it
+            // to data so the caller's exit-code check owns the failure. Anything else
+            // (timeout, connection loss) is a genuine infrastructure failure and must
+            // propagate untouched.
+            const res = error?.result;
+            if (res && typeof res.exitCode === 'number')
+                return res;
+            throw error;
+        }
+    }
     /**
      * Extract a POSIX tar stream into the sandbox at `path`.
      *
@@ -672,7 +828,7 @@ class E2BSandbox {
             pending = [];
             pendingBytes = 0;
             await this.sbx.files.write(piecePath, new Blob([piece]));
-            const r = await this.sbx.commands.run(`cat ${piecePath} ${pieces === 0 ? '>' : '>>'} ${tarPath} && rm -f ${piecePath}`, { timeoutMs: 120_000 });
+            const r = await this.runCommand(`cat ${piecePath} ${pieces === 0 ? '>' : '>>'} ${tarPath} && rm -f ${piecePath}`, 120_000);
             if (r.exitCode !== 0) {
                 throw new Error(`importFiles: spooling the archive failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
             }
@@ -694,9 +850,18 @@ class E2BSandbox {
                 }
             }
             await flush();
-            if (pieces === 0)
-                await this.sbx.commands.run(`: > ${tarPath}`, { timeoutMs: 30_000 });
-            const r = await this.sbx.commands.run(`mkdir -p ${shellQuote(path)} && tar xf ${tarPath} -C ${shellQuote(path)} --no-same-owner --no-same-permissions`, { timeoutMs: 300_000 });
+            if (pieces === 0) {
+                // An archive that yielded nothing still gets its (empty) tar created
+                // so the extract below fails as BAD ARCHIVE DATA, not as a missing
+                // file — and through runCommand, so ITS failure (a full disk is the
+                // usual cause) reports its stage and stderr like the spool/extract
+                // failures do, never the SDK's bare exit-status error.
+                const created = await this.runCommand(`: > ${tarPath}`, 30_000);
+                if (created.exitCode !== 0) {
+                    throw new Error(`importFiles: creating the empty archive failed (${created.exitCode}): ${created.stderr.slice(0, 300)}`);
+                }
+            }
+            const r = await this.runCommand(`mkdir -p ${shellQuote(path)} && tar xf ${tarPath} -C ${shellQuote(path)} --no-same-owner --no-same-permissions`, 300_000);
             if (r.exitCode !== 0) {
                 throw new Error(`importFiles: tar extract failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
             }
@@ -736,7 +901,7 @@ class E2BSandbox {
         const tarPath = `/tmp/mol-export-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.tar`;
         let bytes;
         try {
-            const r = await this.sbx.commands.run(`tar cf ${tarPath} -C ${shellQuote(parent)} ${shellQuote(name)}`, { timeoutMs: 300_000 });
+            const r = await this.runCommand(`tar cf ${tarPath} -C ${shellQuote(parent)} ${shellQuote(name)}`, 300_000);
             if (r.exitCode !== 0) {
                 throw new Error(`exportFiles: tar create failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
             }
@@ -774,11 +939,14 @@ class E2BSandbox {
 /**
  * E2B implementation of {@link SandboxProvider}.
  *
- * Only the required surface (`create`/`get`/`list`/`destroy`) plus the boot-path
- * optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
- * land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
- * the control plane treats "unsupported" as `inconclusive` and refuses to boot
- * in prod, which is the correct safe default until egress observation is proven.
+ * The required surface (`create`/`get`/`list`/`destroy`) plus the optionals the
+ * control plane uses are all wired here: `describe`, volumes
+ * (`createVolume`/`removeVolume`/`volumeExists`/`listVolumes`), snapshots
+ * (`commitTemplate`/`getTemplate`/`listTemplates`/`removeTemplate`) and
+ * `verifyEgress`. `verifyEgress` proves deny-by-default by OBSERVING a
+ * throwaway probe sandbox, and answers `inconclusive` whenever it cannot look —
+ * a failed create, a dead probe — so "could not observe" never wears the shape
+ * of the safe verdict.
  */
 export class E2BSandboxProvider {
     name = 'e2b';
@@ -989,18 +1157,23 @@ export class E2BSandboxProvider {
         const client = await this.client();
         const running = await client.list({});
         const items = Array.isArray(running) ? running : (running.sandboxes ?? []);
-        const handles = [];
-        for (const it of items) {
+        // All the per-sandbox connects are issued through a bounded-concurrency
+        // window, not one awaited after the next: each `get()` is a full connect
+        // round trip, and a fleet sweep over N running sandboxes must not
+        // serialize N of them (O(N) latency on a method the control plane polls) —
+        // while still not putting all N sockets in flight at once (see
+        // {@link LIST_CONNECT_CONCURRENCY}). Same semantics as the serial loop —
+        // a paused sandbox is skipped, a gone sandbox contributes no handle, any
+        // other failure still throws — in ⌈N/16⌉ round-trip depth instead of N.
+        const handles = await mapWithConcurrency(items, LIST_CONNECT_CONCURRENCY, async (it) => {
             // A PAUSED sandbox is deliberately skipped: building its handle means
             // connecting, and connecting resumes it. Enumerating an account would
             // otherwise wake — and start billing — every hibernated project on it.
             if (it.state === 'paused')
-                continue;
-            const h = await this.get(it.sandboxId);
-            if (h)
-                handles.push(h);
-        }
-        return handles;
+                return null;
+            return this.get(it.sandboxId);
+        });
+        return handles.filter((h) => h !== null);
     }
     /**
      * Destroy a sandbox, freeing its resources.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-e2b",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "E2B (e2b.dev) code sandbox provider — Firecracker microVMs with golden templates, fork, and pause/resume",
   "type": "module",
   "main": "dist/index.js",