@molecule/api-code-sandbox-e2b 1.2.4 → 1.2.6

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-04T08:07:55.241Z
+Generated: 2026-10-04T09:45:27.540Z
 -->
 
 # @molecule/api-code-sandbox-e2b
@@ -603,5 +603,12 @@ default is `onTimeout: 'kill'`, so a sandbox nothing touched for its lifetime
 would be destroyed with its files. This bond creates every sandbox with
 `lifecycle: { onTimeout: { action: 'pause', keepMemory: true } }`; the memory
 snapshot is what lets `resume()` truthfully report `processesPreserved: true`.
+The one exception is the throwaway `verifyEgress()` probe, created with
+`lifecycle: { onTimeout: 'kill' }`: a pause writes a full snapshot to the
+host's disk, and nobody resumes a probe. Every pause and every
+`commitTemplate()` is a new snapshot build on a self-hosted box's disk, so
+a pause-on-timeout sandbox you do not need back is disk you pay for — keep a
+sandbox you intend to keep warm alive with `keepAlive(ms)`, and destroy one
+you are done with rather than letting it time out.
 Extending the deadline is `keepAlive(ms)` — call it from a real activity
 signal (an open editor's heartbeat), never as a side effect of polling.

package/dist/index.d.ts

@@ -144,6 +144,13 @@
  * would be destroyed with its files. This bond creates every sandbox with
  * `lifecycle: { onTimeout: { action: 'pause', keepMemory: true } }`; the memory
  * snapshot is what lets `resume()` truthfully report `processesPreserved: true`.
+ * The one exception is the throwaway `verifyEgress()` probe, created with
+ * `lifecycle: { onTimeout: 'kill' }`: a pause writes a full snapshot to the
+ * host's disk, and nobody resumes a probe. Every pause and every
+ * `commitTemplate()` is a new snapshot build on a self-hosted box's disk, so
+ * a pause-on-timeout sandbox you do not need back is disk you pay for — keep a
+ * sandbox you intend to keep warm alive with `keepAlive(ms)`, and destroy one
+ * you are done with rather than letting it time out.
  * Extending the deadline is `keepAlive(ms)` — call it from a real activity
  * signal (an open editor's heartbeat), never as a side effect of polling.
  *

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -144,6 +144,13 @@
  * would be destroyed with its files. This bond creates every sandbox with
  * `lifecycle: { onTimeout: { action: 'pause', keepMemory: true } }`; the memory
  * snapshot is what lets `resume()` truthfully report `processesPreserved: true`.
+ * The one exception is the throwaway `verifyEgress()` probe, created with
+ * `lifecycle: { onTimeout: 'kill' }`: a pause writes a full snapshot to the
+ * host's disk, and nobody resumes a probe. Every pause and every
+ * `commitTemplate()` is a new snapshot build on a self-hosted box's disk, so
+ * a pause-on-timeout sandbox you do not need back is disk you pay for — keep a
+ * sandbox you intend to keep warm alive with `keepAlive(ms)`, and destroy one
+ * you are done with rather than letting it time out.
  * Extending the deadline is `keepAlive(ms)` — call it from a real activity
  * signal (an open editor's heartbeat), never as a side effect of polling.
  *

package/dist/provider.d.ts

@@ -64,6 +64,22 @@ export declare class E2BSandboxProvider implements SandboxProvider {
      * @returns A live sandbox handle.
      */
     create(config: SandboxConfig): Promise<Sandbox>;
+    /**
+     * {@link create} with the sandbox's timeout action chosen by the caller.
+     *
+     * `'pause'` is E2B's `lifecycle: { onTimeout: { action: 'pause', keepMemory:
+     * true } }` — the data-safe default for anything that may hold a project
+     * (see {@link create}). `'kill'` is `lifecycle: { onTimeout: 'kill' }` — for a
+     * THROWAWAY sandbox this bond destroys itself (the egress probe): pausing one
+     * at its deadline would write a full memory + filesystem snapshot to the
+     * host's disk for a sandbox nobody will ever resume. E2B cannot change a
+     * sandbox's `onTimeout` after create, so the choice is made here, once.
+     *
+     * @param config - As for {@link create}.
+     * @param onTimeout - What E2B does at the sandbox's deadline.
+     * @returns A live sandbox handle.
+     */
+    private createSandbox;
     /**
      * Resolve an existing sandbox by id.
      *

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":"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;AA+yBnB;;;;;;;;;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;IAIrD;;;;;;;;;;;;;;OAcG;YACW,aAAa;IAkD3B;;;;;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;IAwB5C;;;;;OAKG;YACW,YAAY;IAa1B;;;;;OAKG;YACW,WAAW;CA6B1B;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CA8B1E;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

@@ -128,6 +128,8 @@ function bareSnapshotName(snapshot) {
     const withoutTag = full.includes(':') ? full.slice(0, full.lastIndexOf(':')) : full;
     return withoutTag.includes('/') ? withoutTag.slice(withoutTag.lastIndexOf('/') + 1) : withoutTag;
 }
+/** How much of an incoming archive `importFiles` holds before spooling it into the sandbox. */
+const IMPORT_PIECE_BYTES = 8 * 1024 * 1024;
 /**
  * Single-quote a value for POSIX `sh` so an arbitrary path is one argument.
  *
@@ -551,6 +553,25 @@ class E2BSandbox {
     async writeFile(path, content) {
         await this.sbx.files.write(path, content);
     }
+    /**
+     * Read a file's exact bytes through envd's file API (never command stdout,
+     * which envd truncates for large outputs).
+     *
+     * @param path - Absolute path inside the sandbox.
+     * @returns The file's bytes.
+     */
+    async readFileBytes(path) {
+        return this.sbx.files.read(path, { format: 'bytes' });
+    }
+    /**
+     * Write exact bytes to a file through envd's file API, replacing it.
+     *
+     * @param path - Absolute path inside the sandbox.
+     * @param data - The bytes to write.
+     */
+    async writeFileBytes(path, data) {
+        await this.sbx.files.write(path, data);
+    }
     /**
      * List a directory. Throws when the path does not exist (an empty array
      * means "exists and is empty", never "missing").
@@ -634,14 +655,47 @@ class E2BSandbox {
      * @param archive - POSIX tar byte stream to extract there.
      */
     async importFiles(path, archive) {
-        const chunks = [];
-        for await (const chunk of archive)
-            chunks.push(chunk);
-        const tarPath = `/tmp/mol-import-${Date.now().toString(36)}.tar`;
-        await this.sbx.files.write(tarPath, new Blob([Buffer.concat(chunks)]));
-        const r = await this.sbx.commands.run(`mkdir -p ${shellQuote(path)} && tar xf ${tarPath} -C ${shellQuote(path)} --no-same-owner --no-same-permissions && rm -f ${tarPath}`, { timeoutMs: 300_000 });
-        if (r.exitCode !== 0) {
-            throw new Error(`importFiles: tar extract failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
+        // Spooled into the sandbox in bounded pieces: the archive is never held
+        // whole in this process (an uploaded tarball can inflate to gigabytes, and
+        // this process is shared by every tenant).
+        const tag = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const tarPath = `/tmp/mol-import-${tag}.tar`;
+        const piecePath = `${tarPath}.piece`;
+        let pending = [];
+        let pendingBytes = 0;
+        let pieces = 0;
+        const flush = async () => {
+            if (pendingBytes === 0)
+                return;
+            const piece = Buffer.concat(pending);
+            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 });
+            if (r.exitCode !== 0) {
+                throw new Error(`importFiles: spooling the archive failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
+            }
+            pieces++;
+        };
+        try {
+            for await (const chunk of archive) {
+                pending.push(chunk);
+                pendingBytes += chunk.length;
+                if (pendingBytes >= IMPORT_PIECE_BYTES)
+                    await flush();
+            }
+            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 (r.exitCode !== 0) {
+                throw new Error(`importFiles: tar extract failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
+            }
+        }
+        finally {
+            await this.sbx.commands
+                .run(`rm -f ${tarPath} ${piecePath}`, { timeoutMs: 30_000 })
+                .catch(() => undefined);
         }
     }
     /**
@@ -777,6 +831,24 @@ export class E2BSandboxProvider {
      * @returns A live sandbox handle.
      */
     async create(config) {
+        return this.createSandbox(config, 'pause');
+    }
+    /**
+     * {@link create} with the sandbox's timeout action chosen by the caller.
+     *
+     * `'pause'` is E2B's `lifecycle: { onTimeout: { action: 'pause', keepMemory:
+     * true } }` — the data-safe default for anything that may hold a project
+     * (see {@link create}). `'kill'` is `lifecycle: { onTimeout: 'kill' }` — for a
+     * THROWAWAY sandbox this bond destroys itself (the egress probe): pausing one
+     * at its deadline would write a full memory + filesystem snapshot to the
+     * host's disk for a sandbox nobody will ever resume. E2B cannot change a
+     * sandbox's `onTimeout` after create, so the choice is made here, once.
+     *
+     * @param config - As for {@link create}.
+     * @param onTimeout - What E2B does at the sandbox's deadline.
+     * @returns A live sandbox handle.
+     */
+    async createSandbox(config, onTimeout) {
         const client = await this.client();
         const templateId = config.templateId ?? this.config.templateId;
         if (config.volumeName && !config.volumeMountPath) {
@@ -789,7 +861,9 @@ export class E2BSandboxProvider {
             timeoutMs: this.config.defaultTimeoutMs,
             envs: config.env ?? {},
             metadata: { projectId: config.projectId, ...(config.labels ?? {}) },
-            lifecycle: { onTimeout: { action: 'pause', keepMemory: true } },
+            lifecycle: onTimeout === 'kill'
+                ? { onTimeout: 'kill' }
+                : { onTimeout: { action: 'pause', keepMemory: true } },
             ...(config.volumeName
                 ? { volumeMounts: { [config.volumeMountPath]: config.volumeName } }
                 : {}),
@@ -1193,7 +1267,9 @@ export class E2BSandboxProvider {
     async verifyEgress() {
         let handle;
         try {
-            handle = await this.create({ projectId: `egress-probe-${Date.now()}`, env: {} });
+            // Kill, not pause, at its deadline: a leaked probe must not leave a
+            // snapshot on the host's disk (see createSandbox).
+            handle = await this.createSandbox({ projectId: `egress-probe-${Date.now()}`, env: {} }, 'kill');
         }
         catch (error) {
             return {
@@ -1205,8 +1281,7 @@ export class E2BSandboxProvider {
         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.
+        // is killed at its own deadline, but until then it runs metered.
         const leaked = await this.destroyProbe(handle.id);
         return leaked ? { ...verdict, detail: `${verdict.detail} ${leaked}` } : verdict;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-e2b",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "E2B (e2b.dev) code sandbox provider — Firecracker microVMs with golden templates, fork, and pause/resume",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@molecule/api-bond": "1.0.2",
-    "@molecule/api-code-sandbox": "1.2.1",
+    "@molecule/api-code-sandbox": "1.3.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.11"