@mastra/platform-workspace 0.2.3 → 0.3.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @mastra/platform
 
+## 0.3.0-alpha.1
+
+### Minor Changes
+
+- `PlatformSandbox.executeCommand` now retries a dropped connection once and continues using direct execution for later commands. Previously a single connection hiccup permanently downgraded the sandbox to a slower fallback route for the rest of its lifetime. ([#20482](https://github.com/mastra-ai/mastra/pull/20482))
+
+  Execution failures now surface directly:
+
+  - A destroyed sandbox throws the new `SandboxDestroyedError`. The cached sandbox is cleared, so the next call provisions a fresh one.
+  - Two connection failures in a row against a live sandbox throw the new `SandboxExecTransportError`, which carries `sandboxId`, `command`, `attempts`, `opened`, `closeCode`, `closeReason`, and `wsEndpoint` for diagnostics.
+  - Other platform errors previously masked by the fallback now bubble out as `PlatformApiError`.
+
+  ```ts
+  import { SandboxDestroyedError, SandboxExecTransportError } from '@mastra/platform-workspace';
+
+  try {
+    await sandbox.executeCommand('pytest');
+  } catch (err) {
+    if (err instanceof SandboxDestroyedError) {
+      // Reprovision and retry.
+    } else if (err instanceof SandboxExecTransportError) {
+      // Connection failed twice; sandbox is still alive.
+    }
+  }
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`594f7b2`](https://github.com/mastra-ai/mastra/commit/594f7b28f5263fb9982fd50d95c471fb971ea984), [`311f943`](https://github.com/mastra-ai/mastra/commit/311f943bee60e8fdf5c84499ea50e884276c936c), [`0c89896`](https://github.com/mastra-ai/mastra/commit/0c8989673fb7d106837098398131e570c6023b68), [`23b4238`](https://github.com/mastra-ai/mastra/commit/23b423844ad0bcf2a502a68dd62866d6160f9f6d), [`e320a76`](https://github.com/mastra-ai/mastra/commit/e320a763feaf65c6be3cebecf746defcbde161b3), [`03b4918`](https://github.com/mastra-ai/mastra/commit/03b4918c80d188ce375334c393e131c6e94bd7eb), [`14ef73a`](https://github.com/mastra-ai/mastra/commit/14ef73a4bbd73e7808414816eb0628ce1d80b5d7), [`1d677d5`](https://github.com/mastra-ai/mastra/commit/1d677d5f99d7db403f7828585e8c25f299f72628), [`93e28ec`](https://github.com/mastra-ai/mastra/commit/93e28ecce9031c02397e0ae8406593e5c7a95883), [`729dab4`](https://github.com/mastra-ai/mastra/commit/729dab408faccfaef0cbb048e5a4338f9172847e), [`484003d`](https://github.com/mastra-ai/mastra/commit/484003d33ff59330c86b19863e4a38732d7e4155), [`933d291`](https://github.com/mastra-ai/mastra/commit/933d291146b789c19442ad206f94da3e4be90c64)]:
+  - @mastra/core@1.56.0-alpha.3
+
+## 0.2.4-alpha.0
+
+### Patch Changes
+
+- Fixed `PlatformSandbox.clone()` silently ignoring `checkpointName`. Clones created with `clone({ checkpointName })` now reuse a matching captured checkpoint on `start()` instead of always provisioning a fresh sandbox, so repeated boots of the same session start much faster. ([#20477](https://github.com/mastra-ai/mastra/pull/20477))
+
+  ```ts
+  const child = template.clone({ checkpointName: 'mastra-recovery-session-42' });
+  await child.start(); // Reuses the captured checkpoint when one is available.
+  ```
+
+  An explicit `id` still takes precedence over `checkpointName` when both are passed.
+
+- Updated dependencies [[`322daa6`](https://github.com/mastra-ai/mastra/commit/322daa6d90552909204044790d850958f6745fed), [`cadaa13`](https://github.com/mastra-ai/mastra/commit/cadaa1372e1077c8e85eb64c5499ba8803caa323), [`06000d7`](https://github.com/mastra-ai/mastra/commit/06000d73712911572e913b8a83339270296d0a22), [`3de0188`](https://github.com/mastra-ai/mastra/commit/3de0188bfaf9a9c09c95fe322b53838cf52c70b6)]:
+  - @mastra/core@1.56.0-alpha.2
+
 ## 0.2.3
 
 ### Patch Changes

package/README.md

@@ -106,3 +106,12 @@ try {
 `code` / `proxyMessage` are `undefined` when the proxy returns a non-JSON body (e.g. an HTML 502 from a load balancer).
 
 Filesystem-specific errors (`FileNotFoundError`, `FileExistsError`, `WorkspaceReadOnlyError`) are re-exported from `@mastra/core`.
+
+### Sandbox exec errors
+
+`PlatformSandbox.executeCommand` runs over the direct-exec data plane (a WebSocket straight to the Railway tcp-proxy) and can throw two typed errors on unrecoverable failure:
+
+- `SandboxDestroyedError` — the platform returned 410 for `/exec-lease`, meaning the sandbox has been destroyed. The cached sandbox id and lease are cleared, so a reused `PlatformSandbox` instance will re-provision on the next call. Fleet-level code that owns a binding store should catch this, clear the stale sandbox id, and reprovision + replay.
+- `SandboxExecTransportError` — both the initial WebSocket attempt and the built-in retry closed without an `exit` frame against a live sandbox. Carries `{ opened, closeCode, closeReason, wsEndpoint }` diagnostics plus `sandboxId`, `command`, and `attempts` so upstream logs / alerts can distinguish "the Railway data plane is broken" from "your command failed".
+
+`PlatformApiError` (with status 404 / 500 / 501 on `/exec-lease`) can also bubble up from `executeCommand` — those are configuration or platform errors, not "reprovision me" signals, and are propagated as-is.

package/dist/index.cjs

@@ -524,6 +524,59 @@ const CREATE_MAX_ATTEMPTS = 3;
 /** Base delay between create retries; multiplied by the attempt number. */
 const CREATE_RETRY_BASE_DELAY_MS = 2e3;
 /**
+* Diagnostic error thrown when the direct-exec WebSocket transport fails
+* twice in a row (opening handshake refused or socket closed mid-stream
+* without an `exit` frame). Distinguishes "the sandbox transport is broken"
+* from "your command failed" so callers can decide whether to retry at a
+* higher level (e.g. reprovision the sandbox) or surface the error.
+*
+* `opened` is `true` when the WebSocket completed its handshake at least
+* once before closing; `false` when Railway refused the upgrade outright.
+*/
+var SandboxExecTransportError = class extends Error {
+	sandboxId;
+	command;
+	attempts;
+	opened;
+	closeCode;
+	closeReason;
+	wsEndpoint;
+	constructor(message, diagnostics) {
+		super(message);
+		this.name = "SandboxExecTransportError";
+		this.sandboxId = diagnostics.sandboxId;
+		this.command = diagnostics.command;
+		this.attempts = diagnostics.attempts;
+		this.opened = diagnostics.opened;
+		this.closeCode = diagnostics.closeCode;
+		this.closeReason = diagnostics.closeReason;
+		this.wsEndpoint = diagnostics.wsEndpoint;
+	}
+};
+/**
+* Thrown when `/exec-lease` returns 410 Gone — the sandbox has been destroyed
+* (Railway destroy, quota reclamation, etc.). The client cannot recover from
+* this on its own because it does not own the binding store; only the fleet
+* layer can clear the stale sandbox id and provision a fresh one. Callers
+* (typically `SandboxFleet`) must catch this and reprovision-and-replay.
+*
+* When this is thrown the cached `_lease` and `_sandboxId` on the sandbox
+* instance are cleared, so the next `ensureRunning()` on a reused instance
+* will re-provision cleanly.
+*/
+var SandboxDestroyedError = class extends Error {
+	sandboxId;
+	command;
+	attempts;
+	constructor(message, diagnostics) {
+		super(message);
+		this.name = "SandboxDestroyedError";
+		this.sandboxId = diagnostics.sandboxId;
+		this.command = diagnostics.command;
+		this.attempts = diagnostics.attempts;
+	}
+};
+/**
 * Compose a shell command line from a `command` string and optional `args`.
 *
 * IMPORTANT: `command` is treated as a **shell string** and passed to the
@@ -623,16 +676,6 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* Cleared (regardless of success or failure) when the request settles.
 	*/
 	_leaseInFlight = null;
-	/**
-	* Tri-state feature detection for the platform's exec-lease endpoint:
-	*   undefined — not yet tried (default; try direct on first exec)
-	*   true      — endpoint present, use direct exec
-	*   false     — endpoint absent (404/501) OR the WebSocket transport failed
-	*               once; fall back permanently to /exec for this sandbox
-	* Sticky per instance so we make the fallback decision once per sandbox
-	* lifetime instead of paying an extra round-trip on every exec.
-	*/
-	_directExecAvailable = void 0;
 	constructor(options = {}) {
 		super({
 			...options,
@@ -667,8 +710,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* (e.g. one per project).
 	*/
 	clone(options = {}) {
+		const id = options.id ?? options.checkpointName;
 		return new PlatformSandbox({
-			...options.id !== void 0 && { id: options.id },
+			...id !== void 0 && { id },
 			accessToken: this._client.accessToken,
 			projectId: this._client.projectId,
 			fetch: this._client.fetch,
@@ -751,47 +795,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const started = Date.now();
 		const fullCommand = buildCommand(command, args);
 		const effectiveTimeout = options?.timeout ?? this._timeout;
-		if (this._directExecAvailable !== false) {
-			const leaseResult = await this._tryDirectExec(fullCommand, effectiveTimeout, options);
-			if (leaseResult) return {
-				...leaseResult,
-				executionTimeMs: Date.now() - started
-			};
-		}
-		return this._execViaProxy(fullCommand, effectiveTimeout, options, started);
-	}
-	async _tryDirectExec(fullCommand, effectiveTimeout, options) {
-		let lease;
-		try {
-			lease = await this._ensureLease();
-		} catch (error) {
-			if (error instanceof PlatformApiError && (error.status === 404 || error.status === 501)) {
-				this._directExecAvailable = false;
-				return null;
-			}
-			throw error;
-		}
-		this._directExecAvailable = true;
-		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
-		const result = await execViaLease(lease, {
-			command: fullCommand,
-			...options?.cwd !== void 0 && { cwd: options.cwd },
-			...filteredEnv !== void 0 && { env: filteredEnv },
-			...effectiveTimeout != null && effectiveTimeout > 0 && { timeoutMs: effectiveTimeout },
-			...this._webSocketFactory && { webSocketFactory: this._webSocketFactory }
-		});
-		if (result.exitCode === null && !result.timedOut) {
-			console.warn("[platform-workspace] direct-exec transport failed; falling back to /exec permanently for this sandbox", {
-				sandboxId: this._sandboxId,
-				opened: result.opened,
-				closeCode: result.closeCode,
-				closeReason: result.closeReason,
-				wsEndpoint: lease.wsEndpoint
-			});
-			this._lease = null;
-			this._directExecAvailable = false;
-			return null;
-		}
+		const result = await this._runDirectExec(fullCommand, effectiveTimeout, options);
 		const exitCode = result.exitCode ?? 124;
 		return {
 			success: exitCode === 0,
@@ -799,34 +803,78 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			stdout: result.stdout,
 			stderr: result.stderr,
 			timedOut: result.timedOut,
-			command: fullCommand
+			command: fullCommand,
+			executionTimeMs: Date.now() - started
 		};
 	}
-	async _execViaProxy(fullCommand, effectiveTimeout, options, started) {
-		if (!this._sandboxId) throw new _mastra_core_workspace.SandboxNotReadyError(this.id);
-		const timeoutSec = effectiveTimeout != null ? Math.ceil(effectiveTimeout / 1e3) : void 0;
-		const clientSignal = effectiveTimeout != null && effectiveTimeout > 0 ? AbortSignal.timeout(effectiveTimeout + 3e4) : void 0;
-		const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}/exec`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify({
+	/**
+	* Run a single exec against the direct-exec transport, with one in-flight
+	* retry on WebSocket transport failure (socket closed without an `exit`
+	* frame and the exec did not time out). The retry mints a fresh lease
+	* — the failure could be a stale JWT — and reopens a new WebSocket.
+	*
+	* Error taxonomy:
+	* - **410 on `/exec-lease`** (either attempt) → the sandbox is gone.
+	*   Nulls the cached `_lease` and `_sandboxId` and throws
+	*   {@link SandboxDestroyedError}. Callers (typically `SandboxFleet`) must
+	*   catch this, clear the stale binding, and reprovision + replay.
+	* - **Persistent transport failure** (both WS attempts close without an
+	*   `exit` frame against a live sandbox) → {@link SandboxExecTransportError}
+	*   with WebSocket close diagnostics.
+	* - **Other `PlatformApiError`s** (404/500/501) propagate directly.
+	* - **Real command result** (exit code from Railway's exit frame, or
+	*   `timedOut: true`) returns normally.
+	*
+	* Returns a result with a real `exitCode` OR `timedOut: true`. Never
+	* returns `{ exitCode: null, timedOut: false }` — that case throws.
+	*/
+	async _runDirectExec(fullCommand, effectiveTimeout, options) {
+		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		let lastResult;
+		let lastLease;
+		let attemptsMade = 0;
+		for (let attempt = 0; attempt < 2; attempt++) {
+			if (attempt > 0 && lastLease && this._lease === lastLease) this._lease = null;
+			let lease;
+			try {
+				lease = await this._ensureLease();
+			} catch (error) {
+				if (error instanceof PlatformApiError && error.status === 410) {
+					this._lease = null;
+					const priorSandboxId = this._sandboxId;
+					this._sandboxId = void 0;
+					throw new SandboxDestroyedError(`Sandbox ${priorSandboxId ?? "(unknown)"} was destroyed; /exec-lease returned 410`, {
+						...priorSandboxId && { sandboxId: priorSandboxId },
+						command: fullCommand,
+						attempts: attempt + 1
+					});
+				}
+				throw error;
+			}
+			lastLease = lease;
+			attemptsMade = attempt + 1;
+			const result = await execViaLease(lease, {
 				command: fullCommand,
-				timeoutSec,
-				cwd: options?.cwd,
-				env: options?.env
-			}),
-			signal: clientSignal
-		})).json();
-		const exitCode = json.exitCode ?? (json.timedOut ? 124 : 1);
-		return {
-			success: exitCode === 0,
-			exitCode,
-			stdout: json.stdout,
-			stderr: json.stderr,
-			executionTimeMs: Date.now() - started,
-			timedOut: json.timedOut,
-			command: fullCommand
-		};
+				...options?.cwd !== void 0 && { cwd: options.cwd },
+				...filteredEnv !== void 0 && { env: filteredEnv },
+				...effectiveTimeout != null && effectiveTimeout > 0 && { timeoutMs: effectiveTimeout },
+				...this._webSocketFactory && { webSocketFactory: this._webSocketFactory }
+			});
+			lastResult = result;
+			if (result.exitCode !== null || result.timedOut) return result;
+		}
+		const result = lastResult;
+		const lease = lastLease;
+		if (this._lease === lease) this._lease = null;
+		throw new SandboxExecTransportError(`Direct-exec transport failed for sandbox ${this._sandboxId ?? "(unknown)"} after ${attemptsMade} attempt(s)` + (result.closeCode !== void 0 ? ` (close ${result.closeCode}${result.closeReason ? ` ${result.closeReason}` : ""})` : ""), {
+			...this._sandboxId && { sandboxId: this._sandboxId },
+			command: fullCommand,
+			attempts: attemptsMade,
+			opened: result.opened ?? false,
+			...result.closeCode !== void 0 && { closeCode: result.closeCode },
+			...result.closeReason !== void 0 && { closeReason: result.closeReason },
+			wsEndpoint: lease.wsEndpoint
+		});
 	}
 	/**
 	* Return a cached exec lease, minting a fresh one when the cache is empty
@@ -974,6 +1022,8 @@ exports.PlatformApiError = PlatformApiError;
 exports.PlatformClient = PlatformClient;
 exports.PlatformFilesystem = PlatformFilesystem;
 exports.PlatformSandbox = PlatformSandbox;
+exports.SandboxDestroyedError = SandboxDestroyedError;
+exports.SandboxExecTransportError = SandboxExecTransportError;
 exports.platformFilesystemProvider = platformFilesystemProvider;
 exports.platformSandboxProvider = platformSandboxProvider;