@mastra/platform-workspace 1.7.0-alpha.0 → 1.7.0-alpha.2

package/dist/index.cjs

@@ -1151,10 +1151,21 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* on a later start.
 	*/
 	templatePending;
+	/**
+	* The platform's id for the provisioned sandbox, as returned by the create
+	* or reattach response. Persist this to reattach later via the `sandboxId`
+	* option. Undefined until the sandbox has been started in this process; a
+	* `sandboxId` passed to the constructor is only a hint for `start()` and is
+	* not reported here until the proxy confirms it.
+	*/
+	get sandboxId() {
+		return this.status === "running" ? this._sandboxId : void 0;
+	}
 	_client;
 	_usesProviderRoutes;
 	_environmentId;
 	_sandboxId;
+	_reattach;
 	_seedCheckpointName;
 	_templateDefinition;
 	_templateBuildEnvs;
@@ -1246,6 +1257,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		this._environmentId = options.environmentId ?? process.env.MASTRA_ENVIRONMENT_ID ?? "";
 		if (!this._environmentId && !options.sandboxId) throw new Error("environmentId is required");
 		this._sandboxId = options.sandboxId;
+		this._reattach = options.reattach ?? "best-effort";
 		this._seedCheckpointName = options.seedCheckpointName;
 		this._usesProviderRoutes = options.template !== void 0;
 		this._template = options.template;
@@ -1262,6 +1274,16 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	generateId() {
 		return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 	}
+	_failIfReattachRequired(reason, cause) {
+		if (this._reattach !== "required") return;
+		throw new _mastra_core_workspace.SandboxError(`Platform sandbox ${this._sandboxId} could not be reattached (${reason}); refusing to provision a replacement because reattach is 'required'. Clear the persisted sandboxId to start a fresh sandbox.`, "SANDBOX_REATTACH_FAILED", {
+			provider: "platform",
+			sandboxId: this._sandboxId,
+			logicalId: this.id,
+			reason,
+			...cause !== void 0 && { cause }
+		});
+	}
 	_request(path, options = {}) {
 		return this._usesProviderRoutes ? this._client.requestProvider(path, options) : this._client.request(path, options);
 	}
@@ -1291,6 +1313,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			fetch: this._client.fetch,
 			environmentId: this._environmentId,
 			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
+			reattach: this._reattach,
 			...seedCheckpointName !== void 0 && { seedCheckpointName },
 			...this._template !== void 0 && { template: this._template },
 			idleTimeoutMinutes: options.idleTimeoutMinutes ?? this._idleTimeoutMinutes,
@@ -1333,9 +1356,11 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 				this._logStartComplete(json.id, startedAt, requestMs, "reattach");
 				return { outcome: "connected" };
 			}
+			this._failIfReattachRequired("destroyed");
 			this._sandboxId = void 0;
 		} catch (error) {
-			if (!(error instanceof PlatformApiError) || error.status !== 404) throw error;
+			if (!(error instanceof PlatformApiError) || error.status !== 404 && error.status !== 410) throw error;
+			this._failIfReattachRequired(String(error.status), error);
 			this._sandboxId = void 0;
 		}
 		if (!this._environmentId) throw new Error("environmentId is required");
@@ -1518,23 +1543,28 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		await Promise.race([this._transportReadyPromise, new Promise((r) => setTimeout(r, TRANSPORT_READY_WAIT_MS))]);
 	}
 	/**
-	* Stop the sandbox while **preserving its recovery checkpoint**.
+	* Stop this process's use of the sandbox without touching the remote one.
 	*
-	* Semantic parity with `@mastra/railway` `RailwaySandbox.stop()`: the VM
-	* is released but the on-provider checkpoint survives, so a subsequent
-	* `start()` on a sandbox constructed with the same `id` can restore from
-	* it. Any in-flight capture is awaited first so the preserved checkpoint
-	* reflects the latest disk state we asked for.
+	* Nothing is sent to workspace-proxy. The VM keeps running and idles out
+	* under the environment's own idle policy, the recovery checkpoint stays,
+	* and `_sandboxId` is kept so a later `start()` on this instance, or on a
+	* new instance constructed with the same `id` or `sandboxId`, reattaches
+	* instead of provisioning. `Mastra.shutdown()` stops every registered
+	* workspace on SIGINT; releasing the VM here would destroy every live
+	* session on a host restart. Use {@link destroy} to release the VM and
+	* its checkpoint.
 	*
-	* Corresponds to `DELETE /v1/:provider/projects/:pid/sandbox/:sandboxId` on
-	* workspace-proxy, which by contract does not touch the checkpoint. Use
-	* {@link destroy} when you want the checkpoint released too.
+	* Any in-flight capture is awaited first so the checkpoint reflects the
+	* latest disk state the caller asked for.
 	*/
 	async stop() {
 		if (this._captureInFlight) await this._captureInFlight.catch((error) => {
-			this.logger.warn(`stop(): failed to flush in-flight capture before teardown:`, error);
+			this.logger.warn(`stop(): failed to flush in-flight capture before stop:`, error);
 		});
-		await this._teardownSandbox();
+		this._probeGeneration++;
+		this._probeTarget = null;
+		this._transportReadyPromise = null;
+		this._lease = null;
 	}
 	/**
 	* Destroy the sandbox **and release its recovery checkpoint**.
@@ -1571,12 +1601,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	/**
 	* Release the remote sandbox VM and clear the local state pointing at it.
 	*
-	* Shared body of {@link stop} and {@link destroy} — both funnel through
-	* here after they've dealt with the checkpoint (preserve vs release).
-	* The VM DELETE is safe to issue in either mode: the proxy's DELETE
-	* route does not touch the checkpoint on its own, so `stop()` correctly
-	* leaves the checkpoint intact and `destroy()` has already removed it
-	* before this call.
+	* Body of {@link destroy}, called after the checkpoint has been released.
+	* The proxy's DELETE route releases the VM (on E2B that kills it), so
+	* only destroy() may reach here; stop() never does.
 	*/
 	async _teardownSandbox() {
 		if (!this._sandboxId) return;
@@ -1955,7 +1982,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		}
 	}
 	async getInfo() {
-		if (!this._sandboxId) return {
+		if (!this._sandboxId || this.status !== "running") return {
 			id: this.id,
 			name: this.name,
 			provider: this.provider,