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

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @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
+
+- Added deterministic reattach to E2B sandboxes by provider sandbox ID. Pass the persisted E2B sandbox ID via the new `sandboxId` option (or `clone({ sandboxId })`) and `start()` connects to that exact sandbox — resuming it if paused — instead of discovering by logical id metadata. Only a typed "sandbox gone" error falls back to the usual lookup-or-create path; auth, quota, rate-limit, timeout, and network errors now propagate instead of silently creating a duplicate sandbox. The resolved provider ID is exposed via the new `sandbox.sandboxId` property so it can be persisted across restarts. ([#22316](https://github.com/mastra-ai/mastra/pull/22316))
+
+  ```ts
+  const sandbox = new E2BSandbox({ id: 'my-workspace', sandboxId: persistedId });
+  await sandbox.start();
+  await save(sandbox.sandboxId); // persist for the next process
+  ```
+
+  Fixes https://github.com/mastra-ai/mastra/issues/22300
+
+### Patch Changes
+
+- Starting a sandbox now reports whether it created a fresh sandbox or reconnected to an existing one, so an `onStart` handler can run first-time setup only when it's actually needed: ([#21984](https://github.com/mastra-ai/mastra/pull/21984))
+
+  ```typescript
+  new E2BSandbox({
+    id: 'session-1',
+    onStart: async ({ outcome }) => {
+      if (outcome === 'created') await cloneRepo();
+    },
+  });
+  ```
+
+- Updated dependencies [[`4ff3ee2`](https://github.com/mastra-ai/mastra/commit/4ff3ee2bff7ed07528b4817f8f49639031c72a4d), [`c24754c`](https://github.com/mastra-ai/mastra/commit/c24754c1fb6fe144e5051e536e98c8a18b0214ac), [`45dd6ee`](https://github.com/mastra-ai/mastra/commit/45dd6ee089bd7df0d0c98a10098e483fd388e04a), [`32d3583`](https://github.com/mastra-ai/mastra/commit/32d358332cb8ac2306b83b73cf3536e74dbd435e), [`aca2869`](https://github.com/mastra-ai/mastra/commit/aca2869b2031982f3c4a2f52525c9be7cf123ef8)]:
+  - @mastra/core@1.62.0-alpha.11
+
 ## 0.10.0-alpha.3
 
 ### Patch Changes

package/dist/index.cjs

@@ -650,6 +650,7 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 	network;
 	lifecycle;
 	connectionOpts;
+	_preferredSandboxId;
 	_instructionsOverride;
 	_constructorOptions;
 	/** Resolved template ID after building (if needed) */
@@ -674,6 +675,7 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 			...options.apiKey && { apiKey: options.apiKey },
 			...options.accessToken && { accessToken: options.accessToken }
 		};
+		this._preferredSandboxId = options.sandboxId;
 		this._instructionsOverride = options.instructions;
 		this._constructorOptions = { ...options };
 		this._templatePreparePromise = this.resolveTemplate().catch((err) => {
@@ -692,13 +694,16 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 	* 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`.
+	* `options.sandboxId` reattaches the clone to that exact E2B sandbox on
+	* `start()`. The parent's own preferred provider sandbox ID is never
+	* inherited — physical identity is per-instance.
 	*/
 	clone(options = {}) {
-		const { id: _id, ...base } = this._constructorOptions;
+		const { id: _id, sandboxId: _sandboxId, ...base } = this._constructorOptions;
 		return new E2BSandbox({
 			...base,
 			...options.id !== void 0 && { id: options.id },
+			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
 			...options.env !== void 0 && { env: options.env },
 			...options.idleTimeoutMinutes !== void 0 && { timeout: options.idleTimeoutMinutes * 6e4 }
 		});
@@ -730,61 +735,73 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 		return this._sandbox;
 	}
 	/**
-	* Start the E2B sandbox.
-	* Handles template preparation, existing sandbox reconnection, and new sandbox creation.
+	* The E2B provider sandbox ID resolved after connect or create.
 	*
-	* Status management and mount processing are handled by the base class.
+	* Persist this to reattach deterministically later via the `sandboxId`
+	* option (or `clone({ sandboxId })`). Undefined until the sandbox has been
+	* started (attached) in this process.
 	*/
-	async start() {
-		if (this._sandbox) return;
-		const [existingSandbox, templateId] = await Promise.all([this.findExistingSandbox(), this._templatePreparePromise || this.resolveTemplate()]);
-		if (existingSandbox) {
-			this._sandbox = existingSandbox;
-			this._createdAt = /* @__PURE__ */ new Date();
-			this.logger.debug(`${LOG_PREFIX} Reconnected to existing sandbox for: ${this.id}`);
-			const expectedPaths = Array.from(this.mounts.entries.keys());
-			this.logger.debug(`${LOG_PREFIX} Running mount reconciliation...`);
-			await this.reconcileMounts(expectedPaths);
-			this.logger.debug(`${LOG_PREFIX} Mount reconciliation complete`);
-			return;
-		}
-		let resolvedTemplateId = templateId;
+	get sandboxId() {
+		return this._sandbox?.sandboxId;
+	}
+	/**
+	* Acquisition primitives (base-orchestrated start): the base derives
+	* `outcome: 'created'` only when a brand-new sandbox VM was created;
+	* reconnecting (including resuming a paused sandbox) is `outcome: 'connected'`.
+	*
+	* `find` returns an already-connected E2B handle: `Sandbox.connect`
+	* resumes paused sandboxes, and its failures are deliberately swallowed
+	* (unusable handle → create fresh) — that forgiveness is this provider's
+	* policy, so it lives here rather than in `connect`. The exception is the
+	* `sandboxId` reattach inside {@link acquireExistingSandbox}, which is
+	* fail-closed: only a "sandbox gone" error falls through to discovery.
+	*/
+	async find() {
+		if (this._sandbox) return this._sandbox;
+		return await this.acquireExistingSandbox() ?? void 0;
+	}
+	async connect(existingSandbox) {
+		if (existingSandbox === this._sandbox) return;
+		this._sandbox = existingSandbox;
+		this._createdAt = /* @__PURE__ */ new Date();
+		this.logger.debug(`${LOG_PREFIX} Reconnected to existing sandbox for: ${this.id}`);
+		const expectedPaths = Array.from(this.mounts.entries.keys());
+		this.logger.debug(`${LOG_PREFIX} Running mount reconciliation...`);
+		await this.reconcileMounts(expectedPaths);
+		this.logger.debug(`${LOG_PREFIX} Mount reconciliation complete`);
+	}
+	async create() {
+		let resolvedTemplateId = await (this._templatePreparePromise || this.resolveTemplate());
 		if (!resolvedTemplateId) {
 			this.logger.debug(`${LOG_PREFIX} Template preparation failed earlier, retrying...`);
 			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) {
-				this.logger.debug(`${LOG_PREFIX} Template not found, rebuilding: ${templateId}`);
+				this.logger.debug(`${LOG_PREFIX} Template not found, rebuilding: ${resolvedTemplateId}`);
 				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();
 	}
 	/**
@@ -849,7 +866,10 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 				path,
 				filesystem: entry.filesystem?.provider ?? entry.config?.type ?? "unknown"
 			})),
-			metadata: { ...this.metadata }
+			metadata: {
+				...this.metadata,
+				...this._sandbox && { sandboxId: this._sandbox.sandboxId }
+			}
 		};
 	}
 	/**
@@ -1127,6 +1147,52 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 		return null;
 	}
 	/**
+	* Acquire an existing sandbox: try the preferred provider sandbox ID first
+	* (deterministic reattach), then fall back to logical-id metadata discovery.
+	*/
+	async acquireExistingSandbox() {
+		if (this._preferredSandboxId) {
+			const preferred = await this.connectToPreferredSandbox(this._preferredSandboxId);
+			if (preferred) return preferred;
+		}
+		return this.findExistingSandbox();
+	}
+	/**
+	* Deterministically reattach to a sandbox by its E2B provider ID.
+	*
+	* Fail-closed: only a typed "sandbox gone" error (not found / killed /
+	* not running) returns null so the caller can fall through to logical-id
+	* discovery or creation. Any other error (auth, quota, rate limit,
+	* timeout, network) propagates so a duplicate sandbox is never created.
+	*
+	* Ownership is validated before connecting: a sandbox tagged with a
+	* different `mastra-sandbox-id` is refused (without resuming it).
+	* Sandboxes without the tag (created outside Mastra) are attachable.
+	*/
+	async connectToPreferredSandbox(preferredSandboxId) {
+		let info;
+		try {
+			info = await e2b.Sandbox.getInfo(preferredSandboxId, this.connectionOpts);
+		} catch (e) {
+			if (this.isSandboxDeadError(e)) {
+				this.logger.debug(`${LOG_PREFIX} Preferred sandbox ${preferredSandboxId} is gone, falling back to logical-id discovery:`, e);
+				return null;
+			}
+			throw e;
+		}
+		const owner = info.metadata?.["mastra-sandbox-id"];
+		if (owner !== void 0 && owner !== this.id) throw new Error(`${LOG_PREFIX} Provider sandbox ${preferredSandboxId} belongs to logical sandbox id "${owner}", refusing to attach it to "${this.id}"`);
+		try {
+			return await e2b.Sandbox.connect(preferredSandboxId, this.connectionOpts);
+		} catch (e) {
+			if (this.isSandboxDeadError(e)) {
+				this.logger.debug(`${LOG_PREFIX} Preferred sandbox ${preferredSandboxId} vanished before connect, falling back:`, e);
+				return null;
+			}
+			throw e;
+		}
+	}
+	/**
 	* 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.
@@ -1135,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;
@@ -1186,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();