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

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @mastra/e2b
 
+## 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,25 +735,43 @@ 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();
@@ -768,7 +791,7 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 		} 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}`);
@@ -849,7 +872,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 +1153,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.