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

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @mastra/platform
 
+## 1.3.0-alpha.2
+
+### Patch Changes
+
+- Added fallback checkpoint forwarding for Platform sandboxes so the workspace proxy can seed fresh sessions without changing their primary recovery key. ([#21803](https://github.com/mastra-ai/mastra/pull/21803))
+
+  ```typescript
+  const sandbox = new PlatformSandbox({
+    id: 'session-42',
+    seedCheckpointName: 'repo-base',
+  });
+  ```
+
+- Updated dependencies [[`58c43d3`](https://github.com/mastra-ai/mastra/commit/58c43d3f7cb2eeaeb8ac733ae71dde822348e588)]:
+  - @mastra/core@1.60.0-alpha.14
+
+## 1.3.0-alpha.1
+
+### Patch Changes
+
+- PlatformSandbox restarts use the current sandbox connection after the previous sandbox is deleted or the platform does not return an instance URL, so later commands do not hit a stale sidecar. ([#21798](https://github.com/mastra-ai/mastra/pull/21798))
+
+- PlatformSandbox now restarts a timed-out sidecar health probe on the next command instead of falling back to the slower lease-based exec path for the sandbox's lifetime. If the in-sandbox sidecar was just slow to boot, later commands recover the fast private-network transport automatically. ([#21798](https://github.com/mastra-ai/mastra/pull/21798))
+
+- Declared checkpoint support (`supportsCheckpoints`) so checkpoint-based features like warm base checkpoints and boot-from-checkpoint know snapshots are real. ([#21798](https://github.com/mastra-ai/mastra/pull/21798))
+
+  ```ts
+  // Gate checkpoint-dependent work on the provider's capability flag.
+  if (sandbox.supportsCheckpoints) {
+    await sandbox.snapshot(); // persists a checkpoint that can seed a later boot
+  }
+  ```
+
+- Updated dependencies [[`c549e2f`](https://github.com/mastra-ai/mastra/commit/c549e2f40edc1cac5d9e74e82f90da22b48df084), [`c549e2f`](https://github.com/mastra-ai/mastra/commit/c549e2f40edc1cac5d9e74e82f90da22b48df084), [`2ef2f23`](https://github.com/mastra-ai/mastra/commit/2ef2f230a7aed342e7dc3b2000cd42e4c43e08a7), [`5740ec6`](https://github.com/mastra-ai/mastra/commit/5740ec60c760ffdfbfaa59d603d03b847c864e05)]:
+  - @mastra/core@1.60.0-alpha.13
+
 ## 1.3.0-alpha.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -859,6 +859,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	_client;
 	_environmentId;
 	_sandboxId;
+	_seedCheckpointName;
 	_idleTimeoutMinutes;
 	_networkIsolation;
 	_env;
@@ -938,6 +939,12 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* failed/timed out, but now coalesced via `_leaseInFlight`).
 	*/
 	_transportReadyPromise = null;
+	/**
+	* The sidecar address of the most recent `start()`, kept so a timed-out
+	* probe can be restarted by a later exec ({@link _awaitTransportReady})
+	* instead of pinning the sandbox to the lease path for its lifetime.
+	*/
+	_probeTarget = null;
 	constructor(options = {}) {
 		super({
 			...options,
@@ -950,6 +957,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._seedCheckpointName = options.seedCheckpointName;
 		this._idleTimeoutMinutes = options.idleTimeoutMinutes;
 		this._networkIsolation = options.networkIsolation;
 		this._env = options.env ?? {};
@@ -986,6 +994,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			fetch: this._client.fetch,
 			environmentId: this._environmentId,
 			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
+			...(options.seedCheckpointName ?? this._seedCheckpointName) !== void 0 && { seedCheckpointName: options.seedCheckpointName ?? this._seedCheckpointName },
 			idleTimeoutMinutes: options.idleTimeoutMinutes ?? this._idleTimeoutMinutes,
 			...this._networkIsolation !== void 0 && { networkIsolation: this._networkIsolation },
 			env: options.env ?? this._env,
@@ -1032,6 +1041,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		if (!this._environmentId) throw new Error("environmentId is required");
 		const body = JSON.stringify({
 			id: this.id,
+			seedCheckpointName: this._seedCheckpointName,
 			environmentId: this._environmentId,
 			idleTimeoutMinutes: this._idleTimeoutMinutes,
 			networkIsolation: this._networkIsolation,
@@ -1090,14 +1100,24 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* HTTP round-trip.
 	*
 	* `null`/absent `instanceUrl` (proxy discovery failed, or an older proxy
-	* that predates the field) leaves the registry untouched — executes fall
-	* through to the lease path with no branch here.
+	* that predates the field) evicts any stale registry address and leaves
+	* executes on the lease path.
 	*/
 	_populateAddressFromResponse(json) {
 		if (!this._addressRegistry) return;
-		if (!json.instanceUrl) return;
+		if (!json.instanceUrl) {
+			this._probeGeneration++;
+			this._probeTarget = null;
+			this._transportReadyPromise = null;
+			this._addressRegistry.delete(json.id);
+			return;
+		}
 		this._addressRegistry.delete(json.id);
 		const generation = ++this._probeGeneration;
+		this._probeTarget = {
+			sandboxId: json.id,
+			instanceUrl: json.instanceUrl
+		};
 		this._transportReadyPromise = this._probeSidecarThenRegister(json.id, json.instanceUrl, generation);
 	}
 	/**
@@ -1107,8 +1127,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* fall back to the lease path until the probe succeeds.
 	*
 	* If the sidecar never comes up within {@link SIDECAR_PROBE_TIMEOUT_MS},
-	* the registry stays unpopulated and all execs go via lease for this
-	* sandbox's lifetime (or until a future `start()` re-runs the probe).
+	* the registry stays unpopulated, `_transportReadyPromise` is cleared,
+	* and a later {@link _awaitTransportReady} call restarts the probe
+	* instead of pinning this sandbox to the lease path.
 	*
 	* @param generation - The probe generation captured at call time. If this
 	*   no longer matches `_probeGeneration` when the probe succeeds, the probe
@@ -1142,6 +1163,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			} catch {}
 			await new Promise((r) => setTimeout(r, SIDECAR_PROBE_INTERVAL_MS));
 		}
+		if (generation === this._probeGeneration && this._transportReadyPromise) this._transportReadyPromise = null;
 		this.logger.warn("platform-workspace probe timed out", {
 			sandboxId,
 			sessionId: this._client.sessionId,
@@ -1162,7 +1184,12 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	*/
 	async _awaitTransportReady() {
 		if (this._sandboxId && this._addressRegistry?.get(this._sandboxId)) return;
-		if (!this._transportReadyPromise) return;
+		if (!this._transportReadyPromise) {
+			const target = this._probeTarget;
+			if (!target || this._sandboxId !== target.sandboxId) return;
+			const generation = ++this._probeGeneration;
+			this._transportReadyPromise = this._probeSidecarThenRegister(target.sandboxId, target.instanceUrl, generation);
+		}
 		await Promise.race([this._transportReadyPromise, new Promise((r) => setTimeout(r, TRANSPORT_READY_WAIT_MS))]);
 	}
 	/**
@@ -1229,6 +1256,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		if (!this._sandboxId) return;
 		const destroyedSandboxId = this._sandboxId;
 		this._probeGeneration++;
+		this._probeTarget = null;
+		this._transportReadyPromise = null;
 		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
@@ -1239,6 +1268,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	async snapshot() {
 		await this.captureCheckpoint();
 	}
+	/** Snapshots persist real checkpoints that can seed future sandboxes. */
+	supportsCheckpoints = true;
 	/**
 	* Capture the sandbox's checkpoint on demand, outside any refresh timer the
 	* workspace-proxy owns internally.
@@ -1358,6 +1389,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* the cached `'running'` state (see `MastraSandbox._start`).
 	*/
 	_clearDestroyedState(destroyedSandboxId) {
+		this._probeGeneration++;
+		this._probeTarget = null;
+		this._transportReadyPromise = null;
 		this._sandboxId = void 0;
 		this._createdAt = null;
 		this._lease = null;