@mastra/e2b 0.6.0 → 0.7.0

package/dist/index.js

@@ -568,11 +568,34 @@ function validateMountPath(mountPath) {
   }
 }
 var SAFE_MARKER_NAME = /^mount-[a-z0-9]+$/;
-var E2BSandbox = class extends MastraSandbox {
+var E2BSandbox = class _E2BSandbox extends MastraSandbox {
   id;
   name = "E2BSandbox";
   provider = "e2b";
   status = "pending";
+  /**
+   * Networking capability: public HTTPS URLs for sandbox ports.
+   * E2B exposes every port via `getHost(port)` — no upfront declaration needed.
+   *
+   * When not attached in this process, the URL is resolved by looking up the
+   * existing sandbox by identity (without resuming it) and deriving the host
+   * (`{port}-{sandboxId}.{domain}`), so other processes can resolve
+   * deployments without waking a paused sandbox.
+   */
+  networking = {
+    getPortUrl: async (port) => {
+      try {
+        if (this._sandbox) {
+          return `https://${this._sandbox.getHost(port)}`;
+        }
+        const info = await this.lookupExistingSandboxInfo();
+        if (!info) return null;
+        return `https://${port}-${info.sandboxId}.${this.sandboxDomain}`;
+      } catch {
+        return null;
+      }
+    }
+  };
   _sandbox = null;
   _createdAt = null;
   _isRetrying = false;
@@ -583,6 +606,7 @@ var E2BSandbox = class extends MastraSandbox {
   network;
   connectionOpts;
   _instructionsOverride;
+  _constructorOptions;
   /** Resolved template ID after building (if needed) */
   _resolvedTemplateId;
   /** Promise for template preparation (started in constructor) */
@@ -606,11 +630,34 @@ var E2BSandbox = class extends MastraSandbox {
       ...options.accessToken && { accessToken: options.accessToken }
     };
     this._instructionsOverride = options.instructions;
+    this._constructorOptions = { ...options };
     this._templatePreparePromise = this.resolveTemplate().catch((err) => {
       this.logger.debug(`${LOG_PREFIX} Template preparation error (will retry on start):`, err);
       return "";
     });
   }
+  /**
+   * Construct a sibling `E2BSandbox` that inherits this sandbox's
+   * configuration (credentials, template, network, metadata, instructions)
+   * with per-instance overrides.
+   *
+   * Performs no I/O — the sandbox clone provisions (or reconnects to an
+   * existing E2B sandbox with the same logical `id`) on its own `start()`.
+   * Use it when one configured sandbox acts as the template for a fleet of
+   * independent sandboxes (e.g. one per project).
+   *
+   * `options.idleTimeoutMinutes` maps to the E2B sandbox `timeout` (ms);
+   * `options.sandboxId` is ignored because E2B reconnects by logical `id`.
+   */
+  clone(options = {}) {
+    const { id: _id, ...base } = this._constructorOptions;
+    return new _E2BSandbox({
+      ...base,
+      ...options.id !== void 0 && { id: options.id },
+      ...options.env !== void 0 && { env: options.env },
+      ...options.idleTimeoutMinutes !== void 0 && { timeout: options.idleTimeoutMinutes * 6e4 }
+    });
+  }
   /**
    * Get the underlying E2B Sandbox instance for direct access to E2B APIs.
    *
@@ -708,22 +755,32 @@ var E2BSandbox = class extends MastraSandbox {
     this._createdAt = /* @__PURE__ */ new Date();
   }
   /**
-   * Stop the E2B sandbox.
-   * Unmounts all filesystems and releases the sandbox reference.
+   * Stop the E2B sandbox by pausing it (snapshot-stop).
+   *
+   * Pausing freezes the whole VM — filesystem, memory, and running processes —
+   * and stops billing immediately. The next `start()` reconnects and resumes it,
+   * with background processes still running. Filesystem mounts are unmounted
+   * first (FUSE mounts don't survive pause) and reconciled again on start.
+   *
    * Status management is handled by the base class.
    */
   async stop() {
-    try {
-      const procs = await this.processes.list();
-      await Promise.all(procs.map((p) => this.processes.kill(p.pid)));
-    } catch {
-    }
     for (const mountPath of [...this.mounts.entries.keys()]) {
       try {
         await this.unmount(mountPath);
       } catch {
       }
     }
+    if (this._sandbox) {
+      await this._sandbox.pause();
+      this.logger.debug(`${LOG_PREFIX} Paused sandbox ${this._sandbox.sandboxId} for: ${this.id}`);
+    } else {
+      const info = await this.lookupExistingSandboxInfo();
+      if (info?.state === "running") {
+        await Sandbox.pause(info.sandboxId, this.connectionOpts);
+        this.logger.debug(`${LOG_PREFIX} Paused detached sandbox ${info.sandboxId} for: ${this.id}`);
+      }
+    }
     this._sandbox = null;
   }
   /**
@@ -744,11 +801,14 @@ var E2BSandbox = class extends MastraSandbox {
         } catch {
         }
       }
-      try {
-        await this._sandbox.kill();
-      } catch {
-      }
+      await this._sandbox.kill();
       this._sandbox = null;
+    } else {
+      const info = await this.lookupExistingSandboxInfo();
+      if (info) {
+        await Sandbox.kill(info.sandboxId, this.connectionOpts);
+        this.logger.debug(`${LOG_PREFIX} Killed detached sandbox ${info.sandboxId} for: ${this.id}`);
+      }
     }
     this.mounts.clear();
   }
@@ -768,6 +828,21 @@ var E2BSandbox = class extends MastraSandbox {
       }
     };
   }
+  // ---------------------------------------------------------------------------
+  // File Upload
+  // ---------------------------------------------------------------------------
+  /**
+   * Bulk-write files into the sandbox filesystem via the SDK's native upload.
+   */
+  async writeFiles(files) {
+    await this.ensureRunning();
+    await this.e2b.files.write(
+      files.map((f) => ({
+        path: f.path,
+        data: typeof f.content === "string" ? f.content : new Blob([new Uint8Array(f.content)])
+      }))
+    );
+  }
   /**
    * Get instructions describing this E2B sandbox.
    * Used by agents to understand the execution environment.
@@ -1002,11 +1077,15 @@ var E2BSandbox = class extends MastraSandbox {
   generateId() {
     return `e2b-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   }
+  /** Domain used to derive public sandbox hosts (self-hosted E2B or e2b.app). */
+  get sandboxDomain() {
+    return this.connectionOpts.domain ?? process.env.E2B_DOMAIN ?? "e2b.app";
+  }
   /**
-   * Find an existing sandbox with matching mastra-sandbox-id metadata.
-   * Returns the connected sandbox if found, null otherwise.
+   * Look up an existing sandbox with matching mastra-sandbox-id metadata
+   * WITHOUT connecting or resuming it. Returns its list info or null.
    */
-  async findExistingSandbox() {
+  async lookupExistingSandboxInfo() {
     try {
       const paginator = Sandbox.list({
         ...this.connectionOpts,
@@ -1022,13 +1101,28 @@ var E2BSandbox = class extends MastraSandbox {
         this.logger.debug(
           `${LOG_PREFIX} Found existing sandbox for ${this.id}: ${existingSandbox.sandboxId} (state: ${existingSandbox.state})`
         );
-        return await Sandbox.connect(existingSandbox.sandboxId, this.connectionOpts);
+        return existingSandbox;
       }
     } catch (e) {
       this.logger.debug(`${LOG_PREFIX} Error querying for existing sandbox:`, e);
     }
     return null;
   }
+  /**
+   * Find an existing sandbox with matching mastra-sandbox-id metadata.
+   * Returns the connected sandbox if found, null otherwise.
+   * Connecting to a paused sandbox resumes it.
+   */
+  async findExistingSandbox() {
+    const info = await this.lookupExistingSandboxInfo();
+    if (!info) return null;
+    try {
+      return await Sandbox.connect(info.sandboxId, this.connectionOpts);
+    } catch (e) {
+      this.logger.debug(`${LOG_PREFIX} Error connecting to existing sandbox:`, e);
+      return null;
+    }
+  }
   /**
    * Resolve the template specification to a template ID.
    *