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

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":"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"}

package/dist/provider.js

@@ -551,6 +551,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").
@@ -777,6 +796,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 +826,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 +1232,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 +1246,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.5",
   "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"