@mastra/platform-workspace 0.2.2-alpha.0 → 0.2.3-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @mastra/platform
 
+## 0.2.3-alpha.0
+
+### Patch Changes
+
+- Fix direct-exec fallback loop: when the WebSocket transport fails on a sandbox (Railway rejects the handshake, mid-stream drop, etc.), disable direct-exec permanently for that sandbox instead of re-minting a fresh lease on every subsequent exec. Also surface WebSocket close code, reason, and `opened` state in `DirectExecResult` and emit a diagnostic warning on transport failure so we can see why Railway is refusing the upgrade in production. ([#20412](https://github.com/mastra-ai/mastra/pull/20412))
+
+- Updated dependencies [[`55c9e24`](https://github.com/mastra-ai/mastra/commit/55c9e248c27c1d72b5bb7e94ea6b8a3999eee49f), [`07f5b4b`](https://github.com/mastra-ai/mastra/commit/07f5b4ba9d608d88865030732e580298296adf99)]:
+  - @mastra/core@1.55.0-alpha.2
+
+## 0.2.2
+
+### Patch Changes
+
+- **Added:** Direct exec data plane for `PlatformSandbox`. ([#20326](https://github.com/mastra-ai/mastra/pull/20326))
+
+  Commands now execute against Railway's WebSocket endpoint directly using a short-lived JWT lease minted by the workspace proxy, instead of proxying every exec through the HTTP proxy. This removes the workspace proxy from the exec hot path — cutting latency for large-payload commands (e.g. `pnpm install`) and eliminating duplicated observability spans.
+
+  The change is transparent: `executeCommand` still returns the same `CommandResult` shape. If the proxy's `/exec-lease` endpoint is unavailable (older deployments), the client automatically falls back to the legacy `POST /sandbox/:id/exec` route for the lifetime of the sandbox.
+
+- Fixed platform sandbox reattach and made provisioning resilient to transient proxy failures: ([#20294](https://github.com/mastra-ai/mastra/pull/20294))
+
+  - The workspace proxy assigns its own sandbox id on create (the advisory id in the request body is not honored), but `getInfo()` never exposed it, so callers persisting a reattach id (e.g. the Factory sandbox fleet, which reads `metadata.sandboxId`) stored the locally generated construction id instead. Every reattach then 404'd and each session open provisioned a brand-new sandbox and re-cloned the repository. `getInfo()` now reports the platform-assigned id in `metadata.sandboxId`, and `start()` treats a sandbox record with `destroyedAt` set as gone (falls through to a fresh provision) instead of pointing exec at a dead resource.
+  - Sandbox creation retries transient workspace-proxy 5xx responses with a short backoff. Provisioning intermittently fails with proxy 500s while the provider is under load; a retry keeps a single flaky window from failing the caller's whole workflow (e.g. Factory kickoff runs). Non-transient errors (4xx) still fail immediately.
+
+- Updated dependencies [[`ce93a3c`](https://github.com/mastra-ai/mastra/commit/ce93a3c114ea1cbfbd576f3db41d7c26c9844f5b), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`a211d09`](https://github.com/mastra-ai/mastra/commit/a211d09185dc65a746534914cf38b67f21ee9bac), [`0dca9d0`](https://github.com/mastra-ai/mastra/commit/0dca9d0b1356024a53b72ea6f040db528b126caa), [`6218217`](https://github.com/mastra-ai/mastra/commit/62182171b6cfca0b099f1c6a77a2e65e7639ab86), [`5807d3a`](https://github.com/mastra-ai/mastra/commit/5807d3ae1d259b8b7d6df7e5bf2b485c694af9c8), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`05db566`](https://github.com/mastra-ai/mastra/commit/05db566fcbdcbf33d0bffca0c72ec30129e2e3ca), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`d1b7e3a`](https://github.com/mastra-ai/mastra/commit/d1b7e3a978a309a5653eeaa490d2d6c7c53bd093), [`29c584a`](https://github.com/mastra-ai/mastra/commit/29c584a13a88831e5ed1fdeb0ff8e82eae180433), [`c093146`](https://github.com/mastra-ai/mastra/commit/c0931466404d3c521308ea119cb165bb7e695155), [`8124754`](https://github.com/mastra-ai/mastra/commit/8124754ae89fbc69f8136d1df4a91904d0f84c4e), [`d12b2e4`](https://github.com/mastra-ai/mastra/commit/d12b2e4023fd9e3d3e93a9169f5088bcee2a849c)]:
+  - @mastra/core@1.54.0
+
 ## 0.2.2-alpha.0
 
 ### Patch Changes

package/dist/direct-exec.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Direct exec client — opens Railway's tcp-proxy exec WebSocket directly using
+ * a short-lived JWT minted by the workspace proxy's exec-lease endpoint. This
+ * removes the platform data plane from the exec stdout/stderr path entirely
+ * (see `docs/factory/direct-sandbox-connection.md` in the Platform repo),
+ * cutting payload-scaled Cloud Run egress and RTT for commands like
+ * `pnpm install` that stream tens of MB of output.
+ *
+ * The frame protocol below mirrors `connectExecWs()` in `railway@3.5.5`
+ * (`workspaces/railway/node_modules/railway/dist/index.js`). The `railway`
+ * SDK's version is pinned on both sides (platform + here); a version bump
+ * signals the protocol may have drifted and this module must be revisited.
+ */
+/**
+ * Minimal WebSocket surface this module depends on. Matches both the browser
+ * `WebSocket` global and Node 22+'s built-in `WebSocket`. Extracted so tests
+ * can inject a fake without pulling in `ws` or jsdom.
+ */
+export interface DirectExecWebSocket {
+    binaryType: 'blob' | 'arraybuffer';
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Factory that opens a WebSocket to `endpoint` with the given subprotocols.
+ * Defaults to the global `WebSocket` when omitted, which works on Node 22+
+ * (the package's minimum) and in the browser. Tests inject a fake here.
+ */
+export type DirectExecWebSocketFactory = (endpoint: string, subprotocols: string[]) => DirectExecWebSocket;
+/** Lease payload returned by `POST /v1/projects/:projectId/sandbox/:sandboxId/exec-lease`. */
+export interface ExecLease {
+    jwt: string;
+    wsEndpoint: string;
+    subprotocol: string;
+    /** ISO-8601 UTC. Null when the provider issues a JWT without an `exp` claim. */
+    expiresAt: string | null;
+}
+/** Inputs to a direct exec invocation. Mirrors the shape of the `/exec` route body. */
+export interface DirectExecOptions {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * Wall-clock cap for the exec. When elapsed, we close the socket and
+     * return `{timedOut: true, exitCode: 124}` matching the semantics of the
+     * proxy's `/exec` route.
+     */
+    timeoutMs?: number;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    /** Injected for tests. Defaults to `globalThis.WebSocket`. */
+    webSocketFactory?: DirectExecWebSocketFactory;
+}
+/**
+ * Result of a direct exec. Shape matches the workspace-proxy `/exec` response
+ * so the caller (`PlatformSandbox.executeCommand`) can hand it back with no
+ * translation.
+ *
+ * `exitCode` is `null` when the socket closed without an `exit` frame AND the
+ * exec did not time out (rare — usually a mid-stream network drop). Callers
+ * currently coerce `null` to `1` upstream; kept nullable here to preserve the
+ * distinction for future observability.
+ */
+export interface DirectExecResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+    timedOut: boolean;
+    /**
+     * WebSocket close metadata. Populated on any close (normal or transport
+     * failure). `opened` distinguishes handshake failures (never opened) from
+     * mid-stream drops. Callers use this for diagnostic logging; not part of
+     * the CommandResult contract.
+     */
+    closeCode?: number;
+    closeReason?: string;
+    opened?: boolean;
+}
+/**
+ * Open the provider exec WebSocket using `lease`, run `command`, and resolve
+ * with the accumulated stdout/stderr + exit code. See the module docstring
+ * for the wire protocol reference.
+ *
+ * The client sends `stdin_close` immediately after `init_exec`, matching the
+ * SDK's own one-shot exec behavior — we never stream stdin from the caller.
+ */
+export declare function execViaLease(lease: ExecLease, options: DirectExecOptions): Promise<DirectExecResult>;
+//# sourceMappingURL=direct-exec.d.ts.map

package/dist/direct-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-exec.d.ts","sourceRoot":"","sources":["../src/direct-exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,GAAG,aAAa,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACvD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,mBAAmB,CAAC;AAE3G,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;CAC/C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAcD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyJpG"}

package/dist/index.cjs

@@ -358,7 +358,167 @@ function matchesExtension(name, extension) {
 	return (Array.isArray(extension) ? extension : [extension]).some((ext) => name.endsWith(ext));
 }
 //#endregion
+//#region src/direct-exec.ts
+/**
+* Direct exec client — opens Railway's tcp-proxy exec WebSocket directly using
+* a short-lived JWT minted by the workspace proxy's exec-lease endpoint. This
+* removes the platform data plane from the exec stdout/stderr path entirely
+* (see `docs/factory/direct-sandbox-connection.md` in the Platform repo),
+* cutting payload-scaled Cloud Run egress and RTT for commands like
+* `pnpm install` that stream tens of MB of output.
+*
+* The frame protocol below mirrors `connectExecWs()` in `railway@3.5.5`
+* (`workspaces/railway/node_modules/railway/dist/index.js`). The `railway`
+* SDK's version is pinned on both sides (platform + here); a version bump
+* signals the protocol may have drifted and this module must be revisited.
+*/
+/** Byte-0 tag on binary WS frames for stdout output. */
+const STDOUT_FRAME = 1;
+/** Byte-0 tag on binary WS frames for stderr output. */
+const STDERR_FRAME = 3;
+/**
+* Upper bound on how long we'll wait for the WebSocket to open when the
+* caller didn't supply a `timeoutMs`. Guards against a stalled TLS/WS
+* handshake leaving the promise unresolved forever. Not applied once the
+* socket has opened — a caller with no timeout has opted in to unbounded
+* command runtime, just not to unbounded connection setup.
+*/
+const HANDSHAKE_DEADLINE_MS = 3e4;
+const DEFAULT_WS_FACTORY = (endpoint, subprotocols) => {
+	const WS = globalThis.WebSocket;
+	if (!WS) throw new Error("Direct exec requires a WebSocket implementation. Node 22+ provides one globally; on older runtimes, pass webSocketFactory explicitly.");
+	return new WS(endpoint, subprotocols);
+};
+/**
+* Open the provider exec WebSocket using `lease`, run `command`, and resolve
+* with the accumulated stdout/stderr + exit code. See the module docstring
+* for the wire protocol reference.
+*
+* The client sends `stdin_close` immediately after `init_exec`, matching the
+* SDK's own one-shot exec behavior — we never stream stdin from the caller.
+*/
+function execViaLease(lease, options) {
+	const factory = options.webSocketFactory ?? DEFAULT_WS_FACTORY;
+	const stdoutDecoder = new TextDecoder();
+	const stderrDecoder = new TextDecoder();
+	return new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let exitCode = null;
+		let timedOut = false;
+		let settled = false;
+		let opened = false;
+		let closeCode;
+		let closeReason;
+		let timer;
+		let handshakeTimer;
+		const settle = () => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			if (handshakeTimer) clearTimeout(handshakeTimer);
+			const stdoutTail = stdoutDecoder.decode();
+			if (stdoutTail) {
+				stdout += stdoutTail;
+				options.onStdout?.(stdoutTail);
+			}
+			const stderrTail = stderrDecoder.decode();
+			if (stderrTail) {
+				stderr += stderrTail;
+				options.onStderr?.(stderrTail);
+			}
+			try {
+				socket.close(1e3, "");
+			} catch {}
+			resolve({
+				exitCode,
+				stdout,
+				stderr,
+				truncated: false,
+				timedOut,
+				...closeCode !== void 0 && { closeCode },
+				...closeReason !== void 0 && { closeReason },
+				opened
+			});
+		};
+		if (options.timeoutMs !== void 0 && options.timeoutMs > 0) timer = setTimeout(() => {
+			timedOut = true;
+			if (exitCode === null) exitCode = 124;
+			settle();
+		}, options.timeoutMs);
+		else handshakeTimer = setTimeout(() => {
+			if (!opened) settle();
+		}, HANDSHAKE_DEADLINE_MS);
+		const socket = factory(lease.wsEndpoint, [lease.subprotocol, lease.jwt]);
+		socket.binaryType = "arraybuffer";
+		socket.onopen = () => {
+			opened = true;
+			if (handshakeTimer) {
+				clearTimeout(handshakeTimer);
+				handshakeTimer = void 0;
+			}
+			const data = { command: options.command };
+			if (options.cwd) data.cwd = options.cwd;
+			if (options.env && Object.keys(options.env).length > 0) data.env = options.env;
+			socket.send(JSON.stringify({
+				type: "init_exec",
+				data
+			}));
+			socket.send(JSON.stringify({ type: "stdin_close" }));
+		};
+		socket.onmessage = (event) => {
+			const { data } = event;
+			if (data instanceof ArrayBuffer) handleBinaryFrame(data);
+			else if (typeof data === "string") handleTextFrame(data);
+		};
+		socket.onclose = (event) => {
+			closeCode = event.code;
+			closeReason = event.reason;
+			if (!opened) {
+				settle();
+				return;
+			}
+			settle();
+		};
+		socket.onerror = () => {
+			if (settled) return;
+			if (!opened) settle();
+		};
+		function handleBinaryFrame(buffer) {
+			const view = new Uint8Array(buffer);
+			if (view.length <= 1) return;
+			if (view[0] === STDOUT_FRAME) {
+				const chunk = stdoutDecoder.decode(view.subarray(1), { stream: true });
+				stdout += chunk;
+				options.onStdout?.(chunk);
+			} else if (view[0] === STDERR_FRAME) {
+				const chunk = stderrDecoder.decode(view.subarray(1), { stream: true });
+				stderr += chunk;
+				options.onStderr?.(chunk);
+			}
+		}
+		function handleTextFrame(text) {
+			let frame;
+			try {
+				frame = JSON.parse(text);
+			} catch {
+				return;
+			}
+			if (frame.type === "exit") {
+				exitCode = frame.data?.exit_code ?? 0;
+				settle();
+			}
+		}
+	});
+}
+//#endregion
 //#region src/sandbox.ts
+/**
+* How long before a lease's stated `expiresAt` we should treat it as
+* expired. Avoids a race where the JWT is valid at cache-hit time but the
+* server rejects it by the time the WebSocket handshake completes.
+*/
+const LEASE_REFRESH_MARGIN_MS = 6e4;
 /** Max attempts for `POST /sandbox` when the proxy returns transient 5xx errors. */
 const CREATE_MAX_ATTEMPTS = 3;
 /** Base delay between create retries; multiplied by the attempt number. */
@@ -448,6 +608,31 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	_timeout;
 	_instructionsOverride;
 	_createdAt = null;
+	_webSocketFactory;
+	/**
+	* Cached exec lease for this sandbox. `null` before the first exec and
+	* after {@link destroy}. Refreshed when `expiresAt - LEASE_REFRESH_MARGIN_MS < now`
+	* (see {@link _ensureLease}); a lease without a disclosed `expiresAt`
+	* is refreshed on every call.
+	*/
+	_lease = null;
+	/**
+	* In-flight mint request; concurrent `_ensureLease` callers on a cold or
+	* near-expiry cache all await this single promise so we don't burn N
+	* `POST /exec-lease` round-trips when the sandbox is doing N parallel execs.
+	* 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,
@@ -464,6 +649,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		this._env = options.env ?? {};
 		this._timeout = options.timeout;
 		this._instructionsOverride = options.instructions;
+		this._webSocketFactory = options.webSocketFactory;
 	}
 	generateId() {
 		return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -492,7 +678,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			...this._networkIsolation !== void 0 && { networkIsolation: this._networkIsolation },
 			env: options.env ?? this._env,
 			...this._timeout !== void 0 && { timeout: this._timeout },
-			...this._instructionsOverride !== void 0 && { instructions: this._instructionsOverride }
+			...this._instructionsOverride !== void 0 && { instructions: this._instructionsOverride },
+			...this._webSocketFactory !== void 0 && { webSocketFactory: this._webSocketFactory }
 		});
 	}
 	async start() {
@@ -539,6 +726,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
+		this._lease = null;
 	}
 	/**
 	* Execute a command on the remote sandbox.
@@ -563,6 +751,59 @@ 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 exitCode = result.exitCode ?? 124;
+		return {
+			success: exitCode === 0,
+			exitCode,
+			stdout: result.stdout,
+			stderr: result.stderr,
+			timedOut: result.timedOut,
+			command: fullCommand
+		};
+	}
+	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`, {
@@ -587,6 +828,39 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			command: fullCommand
 		};
 	}
+	/**
+	* Return a cached exec lease, minting a fresh one when the cache is empty
+	* or the JWT is within {@link LEASE_REFRESH_MARGIN_MS} of `expiresAt`.
+	*
+	* Callers are expected to be on the "sandbox is running" path; we don't
+	* re-check `_sandboxId` here because `executeCommand` already gated on it.
+	*/
+	async _ensureLease() {
+		const now = Date.now();
+		if (this._lease && this._lease.expiresAtMs !== null && this._lease.expiresAtMs - LEASE_REFRESH_MARGIN_MS > now) return this._lease;
+		if (this._leaseInFlight) return this._leaseInFlight;
+		if (!this._sandboxId) throw new _mastra_core_workspace.SandboxNotReadyError(this.id);
+		const sandboxId = this._sandboxId;
+		const inFlight = (async () => {
+			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/exec-lease`, { method: "POST" })).json();
+			const expiresAtMs = json.expiresAt ? Date.parse(json.expiresAt) : null;
+			const lease = {
+				jwt: json.jwt,
+				wsEndpoint: json.wsEndpoint,
+				subprotocol: json.subprotocol,
+				expiresAt: json.expiresAt,
+				expiresAtMs: expiresAtMs !== null && !Number.isNaN(expiresAtMs) ? expiresAtMs : null
+			};
+			this._lease = lease;
+			return lease;
+		})();
+		this._leaseInFlight = inFlight;
+		try {
+			return await inFlight;
+		} finally {
+			if (this._leaseInFlight === inFlight) this._leaseInFlight = null;
+		}
+	}
 	async getInfo() {
 		if (!this._sandboxId) return {
 			id: this.id,