@mastra/e2b 0.10.0-alpha.4 → 0.10.0-alpha.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mastra/e2b
 
+## 0.10.0-alpha.5
+
+### Patch Changes
+
+- Improved `E2BSandbox` extensibility by adding protected SDK creation, connection, and template resolution hooks. Providers built on E2B can now select a specialized SDK sandbox without changing existing E2B behavior. ([#21707](https://github.com/mastra-ai/mastra/pull/21707))
+
 ## 0.10.0-alpha.4
 
 ### Minor Changes

package/dist/index.cjs

@@ -777,17 +777,19 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 			resolvedTemplateId = await this.resolveTemplate();
 		}
 		this.logger.debug(`${LOG_PREFIX} Creating new sandbox for: ${this.id} with template: ${resolvedTemplateId}`);
+		const createOpts = {
+			...this.connectionOpts,
+			lifecycle: this.lifecycle,
+			metadata: {
+				...this.metadata,
+				"mastra-sandbox-id": this.id
+			},
+			...this.network && { network: this.network },
+			timeoutMs: this.timeout
+		};
+		let sdkSandbox;
 		try {
-			this._sandbox = await e2b.Sandbox.create(resolvedTemplateId, {
-				...this.connectionOpts,
-				lifecycle: this.lifecycle,
-				metadata: {
-					...this.metadata,
-					"mastra-sandbox-id": this.id
-				},
-				...this.network && { network: this.network },
-				timeoutMs: this.timeout
-			});
+			sdkSandbox = await this.createSdkSandbox(resolvedTemplateId, createOpts);
 		} catch (createError) {
 			const errorStr = String(createError);
 			if (errorStr.includes("404") && errorStr.includes("not found") && !this.templateSpec) {
@@ -795,19 +797,11 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 				this._resolvedTemplateId = void 0;
 				const rebuiltTemplateId = await this.buildDefaultTemplate();
 				this.logger.debug(`${LOG_PREFIX} Retrying sandbox creation with rebuilt template: ${rebuiltTemplateId}`);
-				this._sandbox = await e2b.Sandbox.create(rebuiltTemplateId, {
-					...this.connectionOpts,
-					lifecycle: this.lifecycle,
-					metadata: {
-						...this.metadata,
-						"mastra-sandbox-id": this.id
-					},
-					...this.network && { network: this.network },
-					timeoutMs: this.timeout
-				});
+				sdkSandbox = await this.createSdkSandbox(rebuiltTemplateId, createOpts);
 			} else throw createError;
 		}
-		this.logger.debug(`${LOG_PREFIX} Created sandbox ${this._sandbox.sandboxId} for logical ID: ${this.id}`);
+		this._sandbox = sdkSandbox;
+		this.logger.debug(`${LOG_PREFIX} Created sandbox ${sdkSandbox.sandboxId} for logical ID: ${this.id}`);
 		this._createdAt = /* @__PURE__ */ new Date();
 	}
 	/**
@@ -1207,19 +1201,39 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 		const info = await this.lookupExistingSandboxInfo();
 		if (!info) return null;
 		try {
-			return await e2b.Sandbox.connect(info.sandboxId, this.connectionOpts);
+			return await this.connectSdkSandbox(info.sandboxId, this.connectionOpts);
 		} catch (e) {
 			this.logger.debug(`${LOG_PREFIX} Error connecting to existing sandbox:`, e);
 			return null;
 		}
 	}
 	/**
+	* Create a new SDK sandbox from a resolved template ID.
+	*
+	* Override point for providers layered on the E2B SDK whose `Sandbox`
+	* class extends `e2b`'s (e.g. `@e2b/desktop`): override to call their
+	* `Sandbox.create`. Connection options are already spread into `opts`.
+	*/
+	async createSdkSandbox(templateId, opts) {
+		return e2b.Sandbox.create(templateId, opts);
+	}
+	/**
+	* Connect to (and resume) an existing SDK sandbox by its E2B sandbox ID.
+	* Override point — see {@link createSdkSandbox}.
+	*/
+	async connectSdkSandbox(sandboxId, opts) {
+		return e2b.Sandbox.connect(sandboxId, opts);
+	}
+	/**
 	* Resolve the template specification to a template ID.
 	*
 	* - String: Use as-is (template ID)
 	* - TemplateBuilder: Build and return the template ID
 	* - Function: Apply to base mountable template, then build
 	* - undefined: Use default mountable template (cached)
+	*
+	* Override point: subclasses with a different default template (e.g.
+	* desktop sandboxes) override this and {@link buildDefaultTemplate}.
 	*/
 	async resolveTemplate() {
 		if (this._resolvedTemplateId) return this._resolvedTemplateId;
@@ -1258,6 +1272,9 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 	}
 	/**
 	* Build the default mountable template (bypasses exists check).
+	*
+	* Override point: called from the template-not-found retry path in
+	* `start()` when no explicit template was configured.
 	*/
 	async buildDefaultTemplate() {
 		const { template, id } = createDefaultMountableTemplate();