@mastra/platform-workspace 0.2.4-alpha.0 → 1.0.0-alpha.2

package/dist/index.js

@@ -15,7 +15,7 @@ function requireOption(value, name) {
 }
 function resolvePlatformOptions(options) {
 	return {
-		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_SECRET_KEY ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
+		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
 		projectId: requireOption(options.projectId ?? process.env.MASTRA_PROJECT_ID, "projectId"),
 		proxyUrl: (process.env.MASTRA_WORKSPACE_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/$/, ""),
 		fetch: options.fetch ?? fetch
@@ -500,6 +500,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
@@ -599,16 +652,6 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	* 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,
@@ -728,47 +771,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		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,
@@ -776,34 +779,78 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			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 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
@@ -881,7 +928,7 @@ const platformSandboxProvider = {
 		properties: {
 			accessToken: {
 				type: "string",
-				description: "Mastra Platform secret key (falls back to MASTRA_PLATFORM_SECRET_KEY)"
+				description: "Mastra Platform access token (falls back to MASTRA_PLATFORM_ACCESS_TOKEN)"
 			},
 			projectId: {
 				type: "string",
@@ -927,7 +974,7 @@ const platformFilesystemProvider = {
 		properties: {
 			accessToken: {
 				type: "string",
-				description: "Mastra Platform secret key (falls back to MASTRA_PLATFORM_SECRET_KEY)"
+				description: "Mastra Platform access token (falls back to MASTRA_PLATFORM_ACCESS_TOKEN)"
 			},
 			projectId: {
 				type: "string",
@@ -947,6 +994,6 @@ const platformFilesystemProvider = {
 	createFilesystem: (config) => new PlatformFilesystem(config)
 };
 //#endregion
-export { PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, platformFilesystemProvider, platformSandboxProvider };
+export { PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, SandboxDestroyedError, SandboxExecTransportError, platformFilesystemProvider, platformSandboxProvider };
 
 //# sourceMappingURL=index.js.map