@mastra/platform-workspace 1.1.0 → 1.2.0-alpha.1

package/dist/index.js

@@ -834,12 +834,42 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	* Cleared (regardless of success or failure) when the request settles.
 	*/
 	_leaseInFlight = null;
+	/**
+	* True when this sandbox was constructed with a caller-supplied `id` (the
+	* recovery key the proxy hashes into an on-provider checkpoint name).
+	* `captureCheckpoint()` needs this to distinguish "no checkpoint intent"
+	* (auto-generated random id — capture would land under a name no future
+	* boot would look for) from "capture on demand". Cloned sandboxes route
+	* `checkpointName` through `id`, so both entry points set this the same
+	* way.
+	*/
+	_hasRecoveryKey;
+	/**
+	* In-flight `captureCheckpoint()` request. Concurrent callers on the same
+	* instance coalesce onto this single promise so we don't burn N `POST
+	* /checkpoint` round-trips when the fleet fires several turn-end captures
+	* before the first one resolves. Cleared when the request settles.
+	*/
+	_captureInFlight = null;
+	/**
+	* In-flight `start()` attempt. Concurrent callers on a fresh instance
+	* coalesce onto this single promise so a `POST /sandbox` is not fired
+	* N times when N fleet callers race to bring the same logical sandbox
+	* up. Published **synchronously** with `??=` before the first `await`
+	* so a later caller cannot slip through the null check while the
+	* originator is mid-round-trip. Cleared when the shared attempt
+	* settles (success or failure) so the next call sees a clean slot.
+	*
+	* Mirrors OSS `@mastra/railway` `RailwaySandbox._startInFlight`.
+	*/
+	_startInFlight = null;
 	constructor(options = {}) {
 		super({
 			...options,
 			name: "PlatformSandbox",
 			processes: new PlatformProcessManager()
 		});
+		this._hasRecoveryKey = options.id !== void 0;
 		this.id = options.id ?? this.generateId();
 		this._client = new PlatformClient(options);
 		this._environmentId = options.environmentId ?? process.env.MASTRA_ENVIRONMENT_ID ?? "";
@@ -889,6 +919,21 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		});
 	}
 	async start() {
+		this._startInFlight ??= this._doStart().finally(() => {
+			this._startInFlight = null;
+		});
+		return this._startInFlight;
+	}
+	/**
+	* The single `start` attempt behind {@link start}'s coalescing wrapper.
+	*
+	* Split out so the wrapper can install a shared in-flight promise
+	* synchronously (before the first `await`) without inlining the reattach
+	* / retry logic. Joined callers observe whatever outcome this method
+	* produces — success returns normally, failures propagate to every
+	* awaiter.
+	*/
+	async _doStart() {
 		if (this._sandboxId) try {
 			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
 			if (!json.destroyedAt) {
@@ -947,10 +992,67 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		if (!json.instanceUrl) return;
 		this._addressRegistry.set(json.id, json.instanceUrl);
 	}
+	/**
+	* Stop the sandbox while **preserving its recovery checkpoint**.
+	*
+	* 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.
+	*
+	* Corresponds to `DELETE /v1/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.
+	*/
 	async stop() {
-		await this.destroy();
+		if (this._captureInFlight) await this._captureInFlight.catch((error) => {
+			this.logger.warn(`stop(): failed to flush in-flight capture before teardown:`, error);
+		});
+		await this._teardownSandbox();
 	}
+	/**
+	* Destroy the sandbox **and release its recovery checkpoint**.
+	*
+	* Semantic parity with `@mastra/railway` `RailwaySandbox.destroy()`:
+	* cancels any in-flight capture (the checkpoint is about to be deleted
+	* — no reason to burn a capture on state we're releasing), asks the
+	* proxy to delete the checkpoint, then releases the VM. Both remote
+	* operations are best-effort logged failures — a stray checkpoint or a
+	* transient proxy error must not leave the caller with a half-torn-down
+	* sandbox they can't safely retry.
+	*
+	* Requires the caller to have constructed with a recovery `id` (there is
+	* no checkpoint to delete otherwise); callers without one skip the
+	* checkpoint DELETE and behave identically to {@link stop}.
+	*/
 	async destroy() {
+		if (!this._sandboxId) return;
+		const destroyedSandboxId = this._sandboxId;
+		this._captureInFlight = null;
+		if (this._hasRecoveryKey) try {
+			await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
+				method: "DELETE",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ id: this.id })
+			});
+		} catch (error) {
+			if (error instanceof PlatformApiError && (error.status === 404 || error.status === 410)) this.logger.debug(`destroy(): checkpoint already absent upstream (status=${error.status})`);
+			else this.logger.warn(`destroy(): failed to delete checkpoint upstream:`, error);
+		}
+		await this._teardownSandbox();
+	}
+	/**
+	* 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.
+	*/
+	async _teardownSandbox() {
 		if (!this._sandboxId) return;
 		const destroyedSandboxId = this._sandboxId;
 		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
@@ -960,6 +1062,131 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		this._addressRegistry?.delete(destroyedSandboxId);
 	}
 	/**
+	* Capture the sandbox's checkpoint on demand, outside any refresh timer the
+	* workspace-proxy owns internally.
+	*
+	* Intended for callers (e.g. a factory-side scheduler) that want to refresh
+	* the recovery checkpoint at semantic moments — turn end, session-idle,
+	* pre-teardown — rather than only just before the upstream's idle destroy.
+	*
+	* Mirrors the OSS `@mastra/railway` `RailwaySandbox.captureCheckpoint()`
+	* shape so factory can call `sandbox.captureCheckpoint()` uniformly and
+	* branch on `status`/`reason` without knowing which provider is underneath.
+	* Both `captured` and `coalesced` carry the checkpoint name inline so the
+	* caller can persist a session→checkpoint binding atomically with the
+	* awaited capture.
+	*
+	* Skip semantics:
+	*  - No caller-supplied `id`: returns `{ status: 'skipped', reason:
+	*    'no-checkpoint-name-configured' }`. An auto-generated random id is
+	*    never a meaningful recovery key (no future boot would look for a
+	*    checkpoint under it), so capturing would silently produce dead data.
+	*  - Not started (no `_sandboxId`): returns `{ status: 'skipped', reason:
+	*    'sandbox-not-running' }` without a round-trip.
+	*  - Upstream 410 (workspace-proxy or Railway reports the sandbox is
+	*    already destroyed): returns the same `sandbox-not-running` skip so
+	*    the discriminant matches the pre-flight case. Local state
+	*    (`_sandboxId`, `_lease`, sidecar address) is cleared as a side
+	*    effect so the next `start()` provisions fresh instead of reattaching
+	*    to a dead id. The diagnostic distinction (pre-flight vs post-hoc)
+	*    is preserved in log level: debug for the expected pre-flight skip,
+	*    warn for the surprise upstream destroy.
+	*
+	* Concurrent callers on the same instance coalesce onto a single in-flight
+	* `POST /checkpoint` so N simultaneous turn-end fires (e.g. several tabs)
+	* do not each round-trip the proxy. Both the originator and joiners
+	* receive `{ status: 'coalesced', ... }` for the joined result — the
+	* outer contract does not distinguish who started the request, only that
+	* one upstream capture was made.
+	*
+	* Never throws for expected outcomes. Transport failures (5xx, 4xx other
+	* than 410) propagate as {@link PlatformApiError}; a 410 is normalized
+	* to a skip as described above.
+	*/
+	async captureCheckpoint() {
+		if (!this._hasRecoveryKey) {
+			this.logger.debug(`captureCheckpoint skipped: no recovery key configured for sandbox ${this._sandboxId ?? "(unstarted)"}`);
+			return {
+				status: "skipped",
+				reason: "no-checkpoint-name-configured"
+			};
+		}
+		if (!this._sandboxId) {
+			this.logger.debug(`captureCheckpoint skipped: sandbox not running (local pre-flight, id=${this.id})`);
+			return {
+				status: "skipped",
+				reason: "sandbox-not-running"
+			};
+		}
+		if (this._captureInFlight) return this._captureInFlight;
+		const sandboxId = this._sandboxId;
+		const capture = this._doCaptureCheckpoint(sandboxId).finally(() => {
+			if (this._captureInFlight === capture) this._captureInFlight = null;
+		});
+		this._captureInFlight = capture;
+		return capture;
+	}
+	/**
+	* The single `POST /checkpoint` attempt behind {@link captureCheckpoint}.
+	*
+	* Split out so the coalescing wrapper can install a shared in-flight
+	* promise without inlining the transport + response-mapping logic.
+	* Joined callers observe `{ status: 'coalesced', ... }` — the initiator
+	* sees the underlying `captured` / `coalesced` / `skipped` result the
+	* proxy returned. Both are legitimate: the OSS mirror uses the same
+	* "initiator sees the truth, joiners see coalesced" split.
+	*/
+	async _doCaptureCheckpoint(sandboxId) {
+		let response;
+		try {
+			response = await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/checkpoint`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ id: this.id })
+			});
+		} catch (error) {
+			if (error instanceof PlatformApiError && error.status === 410) {
+				this.logger.warn(`captureCheckpoint skipped: sandbox destroyed upstream (proxy 410, sandboxId=${sandboxId})`);
+				this._clearDestroyedState(sandboxId);
+				return {
+					status: "skipped",
+					reason: "sandbox-not-running"
+				};
+			}
+			throw error;
+		}
+		const json = await response.json();
+		if (json.status === "skipped") {
+			this.logger.warn(`captureCheckpoint skipped: sandbox destroyed upstream (proxy reported skipped, sandboxId=${sandboxId})`);
+			this._clearDestroyedState(sandboxId);
+			return {
+				status: "skipped",
+				reason: "sandbox-not-running"
+			};
+		}
+		return {
+			status: json.status,
+			checkpointName: json.checkpointName
+		};
+	}
+	/**
+	* Clear local state that would otherwise let the caller keep exec'ing
+	* against a sandbox the upstream has already destroyed. Mirrors what
+	* `destroy()` does minus the outbound DELETE — the sandbox is already
+	* gone, so all that remains is to stop pointing at it.
+	*
+	* Also resets `status` to `'pending'` so a subsequent `_start()` on this
+	* reused instance re-runs provisioning instead of short-circuiting on
+	* the cached `'running'` state (see `MastraSandbox._start`).
+	*/
+	_clearDestroyedState(destroyedSandboxId) {
+		this._sandboxId = void 0;
+		this._createdAt = null;
+		this._lease = null;
+		this._addressRegistry?.delete(destroyedSandboxId);
+		this.status = "pending";
+	}
+	/**
 	* Execute a command on the remote sandbox.
 	*
 	* `command` is a **shell string**: it is concatenated verbatim into the
@@ -1169,6 +1396,14 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			status: this.status,
 			createdAt: this._createdAt ?? /* @__PURE__ */ new Date()
 		};
+		if (this._addressRegistry?.get(this._sandboxId)) return {
+			id: this._sandboxId,
+			name: this.name,
+			provider: this.provider,
+			status: this.status,
+			createdAt: this._createdAt ?? /* @__PURE__ */ new Date(),
+			metadata: { sandboxId: this._sandboxId }
+		};
 		const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
 		return {
 			id: json.id,