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

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @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
+
+- Honor the sandbox runtime environment (`setEnv()`/`getEnv()` from `@mastra/core`) in every workspace sandbox provider. Environment variables set after construction now reach subsequent commands on all providers: ([#22250](https://github.com/mastra-ai/mastra/pull/22250))
+
+  - Process-manager-routed providers (E2B, Blaxel, Cloudflare, Daytona, Docker, Modal, Vercel microVM spawns) inherit the merge from the core spawn wrapper; their duplicated per-manager env plumbing is removed.
+  - Providers with their own exec transports (AgentCore, Apple Container, Railway, Vercel microVM and serverless `executeCommand`, Platform's private-network, WebSocket lease, and E2B lease paths) now merge `getEnv()` under per-call env.
+
+  Constructor `env` continues to behave as before: it seeds the sandbox runtime environment, and providers that bake env into the VM or container at creation time (Docker, Modal, Railway, Apple Container, Vercel, Platform) still do so. Per-call `env` on `executeCommand` still takes precedence for that command only.
+
+  Removed exported types (minor bump for these two packages): `BlaxelProcessManagerOptions` from `@mastra/blaxel` and `RailwayProcessManagerOptions` from `@mastra/railway`. Both existed only to pass `env` into a process manager constructed by hand; the core spawn wrapper now owns that merge, so the option and its type are gone.
+
+- Updated dependencies [[`aa3a85d`](https://github.com/mastra-ai/mastra/commit/aa3a85daf094c683bb97efdf4b6a696d2e474af5), [`d29d06f`](https://github.com/mastra-ai/mastra/commit/d29d06fe00bbd35b4571150ea04c59d2ed783c71), [`e6516df`](https://github.com/mastra-ai/mastra/commit/e6516dfcdae4f4ac0e7971d84359a81385ee602f), [`0b2a3d1`](https://github.com/mastra-ai/mastra/commit/0b2a3d1783875c5b97b7b36ab3d03d7360e0dde7), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`57de7d6`](https://github.com/mastra-ai/mastra/commit/57de7d644ba7146edb4e9e6111ec4fa98c3a59e9), [`e8e299c`](https://github.com/mastra-ai/mastra/commit/e8e299cc6abdfc39947e2fec25803493015d3882), [`edfc548`](https://github.com/mastra-ai/mastra/commit/edfc548886bc7bae17b681f8b6b41a47eb32bcd2), [`a8a4871`](https://github.com/mastra-ai/mastra/commit/a8a4871215f51da95c47129602157ce5372f634a), [`5165cdc`](https://github.com/mastra-ai/mastra/commit/5165cdcdcf50e144bb8113278535196cc9b07065), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`9ee8120`](https://github.com/mastra-ai/mastra/commit/9ee8120ce17f76b9f617489e05a283353742690a), [`d975e92`](https://github.com/mastra-ai/mastra/commit/d975e924d4936f46c386bd3dee39c671720289f6), [`1cfa878`](https://github.com/mastra-ai/mastra/commit/1cfa8784d8da0dfaa0317e5048bc48b6084a5ea5), [`c118318`](https://github.com/mastra-ai/mastra/commit/c1183181c9804303db4b511c2e2648f8b714712b), [`fc07c64`](https://github.com/mastra-ai/mastra/commit/fc07c6465043e08e99193a6751a01c56ffc2e7a1), [`542dee2`](https://github.com/mastra-ai/mastra/commit/542dee254167f974ff8cbbbfc0ce10f9a2616a7b), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`895e9df`](https://github.com/mastra-ai/mastra/commit/895e9dfc17d6f34299eca64e317ded9e5f5e5ef8)]:
+  - @mastra/core@1.62.0-alpha.8
+
 ## 0.10.0-alpha.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -518,10 +518,7 @@ var E2BProcessManager = class extends _mastra_core_workspace.SandboxProcessManag
 	async spawn(command, options = {}) {
 		return this.sandbox.retryOnDead(async () => {
 			const e2b = this.sandbox.e2b;
-			const mergedEnv = {
-				...this.env,
-				...options.env
-			};
+			const mergedEnv = { ...options.env };
 			const envs = Object.fromEntries(Object.entries(mergedEnv).filter((entry) => entry[1] !== void 0));
 			let handle;
 			handle = new E2BProcessHandle(await e2b.commands.run(command, {
@@ -649,11 +646,11 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 	_isRetrying = false;
 	timeout;
 	templateSpec;
-	env;
 	metadata;
 	network;
 	lifecycle;
 	connectionOpts;
+	_preferredSandboxId;
 	_instructionsOverride;
 	_constructorOptions;
 	/** Resolved template ID after building (if needed) */
@@ -664,12 +661,11 @@ var E2BSandbox = class E2BSandbox extends _mastra_core_workspace.MastraSandbox {
 		super({
 			...options,
 			name: "E2BSandbox",
-			processes: new E2BProcessManager({ env: options.env ?? {} })
+			processes: new E2BProcessManager()
 		});
 		this.id = options.id ?? this.generateId();
 		this.timeout = options.timeout ?? 3e5;
 		this.templateSpec = options.template;
-		this.env = options.env ?? {};
 		this.metadata = options.metadata ?? {};
 		this.network = options.network;
 		this.lifecycle = options.lifecycle ?? { onTimeout: "pause" };
@@ -679,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) => {
@@ -697,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 }
 		});
@@ -735,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();
@@ -773,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}`);
@@ -854,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 }
+			}
 		};
 	}
 	/**
@@ -1132,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.