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

package/dist/index.js

@@ -649,6 +649,7 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 	network;
 	lifecycle;
 	connectionOpts;
+	_preferredSandboxId;
 	_instructionsOverride;
 	_constructorOptions;
 	/** Resolved template ID after building (if needed) */
@@ -673,6 +674,7 @@ var E2BSandbox = class E2BSandbox extends 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) => {
@@ -691,13 +693,16 @@ var E2BSandbox = class E2BSandbox extends 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 }
 		});
@@ -729,25 +734,43 @@ var E2BSandbox = class E2BSandbox extends 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();
@@ -767,7 +790,7 @@ var E2BSandbox = class E2BSandbox extends 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}`);
@@ -848,7 +871,10 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 				path,
 				filesystem: entry.filesystem?.provider ?? entry.config?.type ?? "unknown"
 			})),
-			metadata: { ...this.metadata }
+			metadata: {
+				...this.metadata,
+				...this._sandbox && { sandboxId: this._sandbox.sandboxId }
+			}
 		};
 	}
 	/**
@@ -1126,6 +1152,52 @@ var E2BSandbox = class E2BSandbox extends 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 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 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.