@mastra/platform-workspace 0.0.0-esbuild-bundle-worker-20260807173433

package/dist/index.js

@@ -0,0 +1,1459 @@
+import { Buffer } from "buffer";
+import nodePath from "path";
+import { FileExistsError, FileNotFoundError, MastraFilesystem, MastraSandbox, ProcessHandle, SandboxNotReadyError, SandboxProcessManager, WorkspaceReadOnlyError } from "@mastra/core/workspace";
+//#region src/client.ts
+const DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
+/**
+* Default per-request timeout for calls to the workspace proxy. Applied only
+* when the caller doesn't already pass an `AbortSignal`. Long-running routes
+* (e.g. `POST /sandbox/:id/exec`) pass their own longer signal.
+*/
+const DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+function requireOption(value, name) {
+	if (!value) throw new Error(`${name} is required`);
+	return value;
+}
+function resolvePlatformOptions(options) {
+	return {
+		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
+	};
+}
+function parseProxyError(body) {
+	if (!body) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const err = parsed.error;
+	if (typeof err !== "object" || err === null) return void 0;
+	const { message, type } = err;
+	if (typeof message !== "string" || typeof type !== "string") return void 0;
+	return {
+		message,
+		type
+	};
+}
+var PlatformApiError = class extends Error {
+	status;
+	body;
+	/** Machine-readable proxy error kind (e.g. `not_found`), when the response body matches `{ error: { message, type } }`. */
+	code;
+	/** Human-readable proxy error message, when the response body matches `{ error: { message, type } }`. */
+	proxyMessage;
+	constructor(status, body) {
+		const parsed = parseProxyError(body);
+		const summary = parsed ? `${parsed.type}: ${parsed.message}` : body;
+		super(`Platform proxy request failed with ${status}${summary ? `: ${summary}` : ""}`);
+		this.name = "PlatformApiError";
+		this.status = status;
+		this.body = body;
+		this.code = parsed?.type;
+		this.proxyMessage = parsed?.message;
+	}
+};
+var PlatformClient = class {
+	accessToken;
+	projectId;
+	proxyUrl;
+	fetch;
+	constructor(options) {
+		const resolved = resolvePlatformOptions(options);
+		this.accessToken = resolved.accessToken;
+		this.projectId = resolved.projectId;
+		this.proxyUrl = resolved.proxyUrl;
+		this.fetch = resolved.fetch;
+	}
+	async request(path, options = {}) {
+		const url = new URL(`${this.proxyUrl}/v1/projects/${encodeURIComponent(this.projectId)}${path}`);
+		for (const [key, value] of Object.entries(options.query ?? {})) if (value !== void 0) url.searchParams.set(key, String(value));
+		const headers = new Headers(options.headers);
+		headers.set("authorization", `Bearer ${this.accessToken}`);
+		const { query: _query, ...fetchOptions } = options;
+		const signal = fetchOptions.signal ?? AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
+		const response = await this.fetch(url, {
+			...fetchOptions,
+			headers,
+			signal
+		});
+		if (!response.ok) throw new PlatformApiError(response.status, await response.text());
+		return response;
+	}
+};
+//#endregion
+//#region src/filesystem.ts
+function normalizePath(input) {
+	if (!input || input === ".") return "/";
+	let normalized = input.startsWith("/") ? input : `/${input}`;
+	normalized = nodePath.posix.normalize(normalized);
+	return normalized === "." ? "/" : normalized;
+}
+function keyFromPath(path) {
+	const normalized = normalizePath(path);
+	return normalized === "/" ? "" : normalized.slice(1);
+}
+/**
+* Encode each `/`-delimited segment of an object key with `encodeURIComponent`
+* so reserved URL characters (`?`, `#`, `%`, `&`, `+`, spaces, etc.) are
+* treated as part of the key instead of URL syntax. Kept segment-aware so
+* `/` continues to act as a path separator on the wire.
+*/
+function encodeKeyPath(key) {
+	return key.split("/").map(encodeURIComponent).join("/");
+}
+function nameFromPath(path) {
+	const normalized = normalizePath(path);
+	if (normalized === "/") return "";
+	return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+function contentToBody(content) {
+	if (typeof content === "string") return content;
+	return Buffer.from(content);
+}
+function headerDate(headers, name) {
+	const value = headers.get(name);
+	return value ? new Date(value) : /* @__PURE__ */ new Date(0);
+}
+function headerSize(headers) {
+	const value = headers.get("content-length");
+	return value ? Number(value) : 0;
+}
+function isNotFound(error) {
+	return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+var PlatformFilesystem = class extends MastraFilesystem {
+	id;
+	name = "PlatformFilesystem";
+	provider = "platform";
+	readOnly;
+	displayName;
+	icon;
+	description;
+	status = "pending";
+	_client;
+	_bucketName;
+	_instructionsOverride;
+	constructor(options = {}) {
+		super({
+			...options,
+			name: "PlatformFilesystem"
+		});
+		this.id = options.id ?? this.generateId();
+		this._bucketName = options.bucketName ?? process.env.MASTRA_PLATFORM_BUCKET_NAME ?? "";
+		if (!this._bucketName) throw new Error("bucketName is required");
+		this.readOnly = options.readOnly;
+		this.displayName = options.displayName;
+		this.icon = options.icon ?? "cloud";
+		this.description = options.description;
+		this._instructionsOverride = options.instructions;
+		this._client = new PlatformClient(options);
+	}
+	generateId() {
+		return `platform-fs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+	}
+	async readFile(path, options) {
+		await this.ensureReady();
+		let response;
+		try {
+			response = await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`);
+		} catch (error) {
+			if (isNotFound(error)) throw new FileNotFoundError(path);
+			throw error;
+		}
+		const buffer = Buffer.from(await response.arrayBuffer());
+		return options?.encoding ? buffer.toString(options.encoding) : buffer;
+	}
+	async writeFile(path, content, options) {
+		await this.ensureReady();
+		if (this.readOnly) throw new WorkspaceReadOnlyError("writeFile");
+		const headers = {};
+		if (options?.mimeType) headers["content-type"] = options.mimeType;
+		if (options?.overwrite === false) headers["if-none-match"] = "*";
+		try {
+			await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`, {
+				method: "PUT",
+				headers,
+				body: contentToBody(content)
+			});
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "status" in error && error.status === 412) throw new FileExistsError(path);
+			throw error;
+		}
+	}
+	/**
+	* Append bytes to a file.
+	*
+	* **Not atomic.** Object storage behind the workspace proxy has no native
+	* append or compare-and-swap primitive, so this implementation is a
+	* read-modify-write: it reads the current contents, concatenates the new
+	* bytes, and PUTs the whole object back. Concurrent `appendFile` calls to
+	* the same path can overwrite each other's writes ("last write wins").
+	* Use `writeFile` with distinct keys for concurrent writers.
+	*/
+	async appendFile(path, content) {
+		const existing = await this.exists(path) ? await this.readFile(path) : Buffer.alloc(0);
+		await this.writeFile(path, Buffer.concat([Buffer.isBuffer(existing) ? existing : Buffer.from(existing), Buffer.from(content)]));
+	}
+	async deleteFile(path, options) {
+		await this.ensureReady();
+		if (this.readOnly) throw new WorkspaceReadOnlyError("deleteFile");
+		try {
+			await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`, {
+				method: "DELETE",
+				query: { recursive: options?.recursive }
+			});
+		} catch (error) {
+			if (isNotFound(error) && options?.force) return;
+			if (isNotFound(error)) throw new FileNotFoundError(path);
+			throw error;
+		}
+	}
+	async copyFile(src, dest, options) {
+		await this.ensureReady();
+		if (this.readOnly) throw new WorkspaceReadOnlyError("copyFile");
+		if (options?.overwrite === false) throw new Error("PlatformFilesystem.copyFile does not support overwrite: false — the proxy always overwrites.");
+		await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(src))}`, {
+			method: "POST",
+			query: { op: "copy" },
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ destination: keyFromPath(dest) })
+		});
+	}
+	async moveFile(src, dest, options) {
+		await this.ensureReady();
+		if (this.readOnly) throw new WorkspaceReadOnlyError("moveFile");
+		if (options?.overwrite === false) throw new Error("PlatformFilesystem.moveFile does not support overwrite: false — the proxy always overwrites.");
+		await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(src))}`, {
+			method: "POST",
+			query: { op: "rename" },
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ destination: keyFromPath(dest) })
+		});
+	}
+	async mkdir(path, _options) {
+		await this.ensureReady();
+		if (this.readOnly) throw new WorkspaceReadOnlyError("mkdir");
+		await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`, {
+			method: "POST",
+			query: { op: "mkdir" }
+		});
+	}
+	async rmdir(path, options) {
+		await this.deleteFile(path.endsWith("/") ? path : `${path}/`, {
+			recursive: true,
+			force: options?.force
+		});
+	}
+	async readdir(path, options) {
+		await this.ensureReady();
+		const prefix = keyFromPath(path);
+		const json = await (await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(prefix)}`, { query: {
+			delimiter: options?.recursive ? void 0 : "/",
+			prefix: prefix ? `${prefix.replace(/\/$/, "")}/` : void 0
+		} })).json();
+		return [...(json.commonPrefixes ?? []).map((prefix) => ({
+			name: nameFromPath(prefix.replace(/\/$/, "")),
+			type: "directory"
+		})), ...(json.contents ?? []).filter((object) => object.key && !object.key.endsWith("/")).map((object) => ({
+			name: nameFromPath(object.key),
+			type: "file",
+			size: object.size
+		}))].filter((entry) => !options?.extension || entry.type === "directory" || matchesExtension(entry.name, options.extension));
+	}
+	async exists(path) {
+		try {
+			await this.stat(path);
+			return true;
+		} catch (error) {
+			if (isNotFound(error) || error instanceof FileNotFoundError) return false;
+			throw error;
+		}
+	}
+	async stat(path) {
+		await this.ensureReady();
+		const normalized = normalizePath(path);
+		if (normalized === "/") return {
+			name: "",
+			path: "/",
+			type: "directory",
+			size: 0,
+			createdAt: /* @__PURE__ */ new Date(0),
+			modifiedAt: /* @__PURE__ */ new Date(0)
+		};
+		let response;
+		try {
+			response = await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`, { method: "HEAD" });
+		} catch (error) {
+			if (isNotFound(error)) throw new FileNotFoundError(path);
+			throw error;
+		}
+		return {
+			name: nameFromPath(path),
+			path: normalized,
+			type: normalized.endsWith("/") ? "directory" : "file",
+			size: headerSize(response.headers),
+			createdAt: headerDate(response.headers, "last-modified"),
+			modifiedAt: headerDate(response.headers, "last-modified"),
+			mimeType: response.headers.get("content-type") ?? void 0
+		};
+	}
+	realpath(path) {
+		return Promise.resolve(normalizePath(path));
+	}
+	getInstructions(opts) {
+		const defaultInstructions = `Platform filesystem backed by Mastra Platform bucket ${this._bucketName}. Use absolute workspace paths.`;
+		if (typeof this._instructionsOverride === "function") return this._instructionsOverride({
+			defaultInstructions,
+			requestContext: opts?.requestContext
+		});
+		if (typeof this._instructionsOverride === "string") return this._instructionsOverride;
+		return defaultInstructions;
+	}
+	getInfo() {
+		return {
+			id: this.id,
+			name: this.name,
+			provider: this.provider,
+			status: this.status,
+			readOnly: this.readOnly,
+			icon: this.icon,
+			metadata: {
+				bucketName: this._bucketName,
+				...this.displayName && { displayName: this.displayName },
+				...this.description && { description: this.description }
+			}
+		};
+	}
+};
+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/private-net-exec.ts
+/**
+* Thrown by {@link execViaPrivateNetwork} when the sidecar returns a non-2xx
+* HTTP response. This is an *application* error, not a transport error — the
+* sidecar is reachable and answered, it just refused the exec. Callers should
+* fall back to the lease path for this one call but MUST NOT invalidate the
+* cached `instanceUrl` (the address is still good).
+*/
+var PrivateNetExecHttpError = class extends Error {
+	status;
+	body;
+	constructor(status, body) {
+		super(`Sidecar /exec returned ${status}${body ? `: ${body.slice(0, 200)}` : ""}`);
+		this.name = "PrivateNetExecHttpError";
+		this.status = status;
+		this.body = body;
+	}
+};
+const DEFAULT_FETCH = (input, init) => {
+	const f = globalThis.fetch;
+	if (!f) throw new Error("Private-network exec requires a fetch implementation. Node 22+ provides one globally; on older runtimes, pass fetch explicitly.");
+	return f(input, init);
+};
+/**
+* Dial `${instanceUrl}/exec` and stream the response, resolving with the
+* accumulated stdout/stderr + exit code.
+*
+* Errors:
+* - Connection failure (DNS, refused, reset) → resolves with
+*   `{opened:false, exitCode:null, transportErrorMessage}`. Never throws for
+*   transport failures — the shape matches the lease-path result so the
+*   caller can treat both transports uniformly.
+* - Non-2xx HTTP response from the sidecar → throws {@link PrivateNetExecHttpError}.
+*   Application-level; caller decides whether to fall back.
+* - Stream ends without an `exit` frame → resolves with
+*   `{opened:true, exitCode:null}`, matching the lease-path semantics for a
+*   mid-stream drop.
+* - `timeoutMs` elapsed → aborts the request, resolves with
+*   `{timedOut:true, exitCode:124}`.
+*/
+async function execViaPrivateNetwork(instanceUrl, options) {
+	const fetchImpl = options.fetch ?? DEFAULT_FETCH;
+	const url = `${instanceUrl.replace(/\/$/, "")}/exec`;
+	const controller = new AbortController();
+	let timedOut = false;
+	let timeoutTimer;
+	if (options.timeoutMs !== void 0 && options.timeoutMs > 0) timeoutTimer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, options.timeoutMs);
+	const body = { command: options.command };
+	if (options.cwd) body.cwd = options.cwd;
+	if (options.env && Object.keys(options.env).length > 0) body.env = options.env;
+	if (options.timeoutMs !== void 0 && options.timeoutMs > 0) body.timeoutMs = options.timeoutMs;
+	const headers = { "content-type": "application/json" };
+	if (options.bearerToken) headers.authorization = `Bearer ${options.bearerToken}`;
+	let response;
+	try {
+		response = await fetchImpl(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+			signal: controller.signal
+		});
+	} catch (error) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		if (timedOut) return {
+			exitCode: 124,
+			stdout: "",
+			stderr: "",
+			timedOut: true,
+			opened: false
+		};
+		return {
+			exitCode: null,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			opened: false,
+			transportErrorMessage: error instanceof Error ? error.message : String(error)
+		};
+	}
+	if (!response.ok) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		const text = await response.text().catch(() => "");
+		throw new PrivateNetExecHttpError(response.status, text);
+	}
+	if (!response.body) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		return {
+			exitCode: null,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			opened: true,
+			status: response.status
+		};
+	}
+	let stdout = "";
+	let stderr = "";
+	let exitCode = null;
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const handleLine = (line) => {
+		if (!line) return;
+		let frame;
+		try {
+			frame = JSON.parse(line);
+		} catch {
+			return;
+		}
+		if (!frame || typeof frame !== "object") return;
+		if (frame.type === "stdout" && typeof frame.data === "string") {
+			stdout += frame.data;
+			options.onStdout?.(frame.data);
+		} else if (frame.type === "stderr" && typeof frame.data === "string") {
+			stderr += frame.data;
+			options.onStderr?.(frame.data);
+		} else if (frame.type === "exit" && typeof frame.code === "number") exitCode = frame.code;
+	};
+	try {
+		const reader = response.body.getReader();
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let newlineIdx = buffer.indexOf("\n");
+			while (newlineIdx !== -1) {
+				const line = buffer.slice(0, newlineIdx).trim();
+				buffer = buffer.slice(newlineIdx + 1);
+				handleLine(line);
+				newlineIdx = buffer.indexOf("\n");
+			}
+		}
+		buffer += decoder.decode();
+		const trailing = buffer.trim();
+		if (trailing) handleLine(trailing);
+	} catch (error) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		if (timedOut) return {
+			exitCode: 124,
+			stdout,
+			stderr,
+			timedOut: true,
+			opened: true,
+			status: response.status
+		};
+		return {
+			exitCode,
+			stdout,
+			stderr,
+			timedOut: false,
+			opened: true,
+			status: response.status,
+			transportErrorMessage: error instanceof Error ? error.message : String(error)
+		};
+	} finally {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+	}
+	return {
+		exitCode,
+		stdout,
+		stderr,
+		timedOut: false,
+		opened: true,
+		status: response.status
+	};
+}
+//#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. */
+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
+* remote shell verbatim so callers can use pipes, redirects, and chaining
+* (`ls -la | grep foo`). This matches the contract of {@link MastraSandbox}
+* and the local sandbox implementation. `args` are always shell-quoted so
+* they cannot inject syntax.
+*
+* Callers MUST NOT pass untrusted input as `command`. Untrusted values must
+* be passed via `args`, where they are safely quoted. Passing untrusted
+* input as `command` allows arbitrary shell syntax execution on the remote
+* sandbox.
+*/
+function buildCommand(command, args) {
+	return args?.length ? `${command} ${args.map(shellQuote).join(" ")}` : command;
+}
+function shellQuote(arg) {
+	if (/^[a-zA-Z0-9._\-/=:@]+$/.test(arg)) return arg;
+	return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+var PlatformProcessHandle = class extends ProcessHandle {
+	pid;
+	resultPromise;
+	exitCodeValue;
+	constructor(pid, resultPromise, options) {
+		super(options);
+		this.pid = pid;
+		this.resultPromise = resultPromise.then((result) => {
+			this.exitCodeValue = result.exitCode;
+			if (result.stdout) this.emitStdout(result.stdout);
+			if (result.stderr) this.emitStderr(result.stderr);
+			return result;
+		});
+	}
+	get exitCode() {
+		return this.exitCodeValue;
+	}
+	async wait() {
+		return this.resultPromise;
+	}
+	async kill() {
+		throw new Error("Platform sandbox command execution does not support killing individual processes");
+	}
+	async sendStdin() {
+		throw new Error("Platform sandbox command execution does not support stdin");
+	}
+};
+var PlatformProcessManager = class extends SandboxProcessManager {
+	spawnCounter = 0;
+	/**
+	* Spawn a process on the remote sandbox.
+	*
+	* `command` is interpreted as a shell string by the remote shell, matching
+	* the {@link MastraSandbox} contract. See {@link PlatformSandbox.executeCommand}
+	* for the untrusted-input caveat: never pass untrusted values as `command`.
+	*/
+	async spawn(command, options = {}) {
+		const handle = new PlatformProcessHandle(`platform-proc-${Date.now().toString(36)}-${(this.spawnCounter++).toString(36)}`, this.sandbox.executeCommand(command, void 0, options), options);
+		this._tracked.set(handle.pid, handle);
+		return handle;
+	}
+	async list() {
+		return Array.from(this._tracked.values()).map((handle) => ({
+			pid: handle.pid,
+			command: handle.command,
+			running: handle.exitCode === void 0,
+			...handle.exitCode !== void 0 && { exitCode: handle.exitCode }
+		}));
+	}
+};
+var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
+	id;
+	name = "PlatformSandbox";
+	provider = "platform";
+	status = "pending";
+	_client;
+	_environmentId;
+	_sandboxId;
+	_idleTimeoutMinutes;
+	_networkIsolation;
+	_env;
+	_timeout;
+	_instructionsOverride;
+	_createdAt = null;
+	_webSocketFactory;
+	_privateNetFetch;
+	/**
+	* Registry that maps `sandboxId → instanceUrl` for the private-network
+	* exec path. Injected by the composition site via
+	* {@link PlatformSandboxOptions.addressRegistry} and populated by this
+	* class itself in `start()` when the workspace-proxy's create/reattach
+	* response includes an `instanceUrl` field. The registry IS the cache —
+	* there is no per-instance mirror on `PlatformSandbox`, so every exec is
+	* a `Map.get()` (in the default in-process impl) against the live view.
+	* When absent, executes go straight to the lease path with no extra
+	* round-trip.
+	*/
+	_addressRegistry;
+	/**
+	* 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;
+	/**
+	* 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;
+	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 ?? "";
+		if (!this._environmentId && !options.sandboxId) throw new Error("environmentId is required");
+		this._sandboxId = options.sandboxId;
+		this._idleTimeoutMinutes = options.idleTimeoutMinutes;
+		this._networkIsolation = options.networkIsolation;
+		this._env = options.env ?? {};
+		this._timeout = options.timeout;
+		this._instructionsOverride = options.instructions;
+		this._webSocketFactory = options.webSocketFactory;
+		this._privateNetFetch = options.privateNetFetch;
+		this._addressRegistry = options.addressRegistry;
+	}
+	generateId() {
+		return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+	}
+	/**
+	* Construct a sibling {@link PlatformSandbox} that inherits this sandbox's
+	* credentials and defaults (access token, project, environment, network
+	* isolation, timeout, instructions, env, idle timeout) with per-instance
+	* overrides from `options`.
+	*
+	* Performs no I/O and does not require this sandbox to be started — the
+	* returned sandbox is not started and provisions (or reattaches, when
+	* `sandboxId` is set) on its own `start()`. Use it when one configured
+	* sandbox acts as the template for a fleet of independent sandboxes
+	* (e.g. one per project).
+	*/
+	clone(options = {}) {
+		const id = options.id ?? options.checkpointName;
+		return new PlatformSandbox({
+			...id !== void 0 && { id },
+			accessToken: this._client.accessToken,
+			projectId: this._client.projectId,
+			fetch: this._client.fetch,
+			environmentId: this._environmentId,
+			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
+			idleTimeoutMinutes: options.idleTimeoutMinutes ?? this._idleTimeoutMinutes,
+			...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._webSocketFactory !== void 0 && { webSocketFactory: this._webSocketFactory },
+			...this._privateNetFetch !== void 0 && { privateNetFetch: this._privateNetFetch },
+			...this._addressRegistry !== void 0 && { addressRegistry: this._addressRegistry }
+		});
+	}
+	async start() {
+		if (this._sandboxId) try {
+			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
+			if (!json.destroyedAt) {
+				this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+				this._populateAddressFromResponse(json);
+				return;
+			}
+			this._sandboxId = void 0;
+		} catch (error) {
+			if (!(error instanceof PlatformApiError) || error.status !== 404) throw error;
+			this._sandboxId = void 0;
+		}
+		if (!this._environmentId) throw new Error("environmentId is required");
+		const body = JSON.stringify({
+			id: this.id,
+			environmentId: this._environmentId,
+			idleTimeoutMinutes: this._idleTimeoutMinutes,
+			networkIsolation: this._networkIsolation,
+			env: this._env
+		});
+		let response;
+		for (let attempt = 1;; attempt++) try {
+			response = await this._client.request("/sandbox", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body
+			});
+			break;
+		} catch (error) {
+			if (!(error instanceof PlatformApiError && error.status >= 500) || attempt >= CREATE_MAX_ATTEMPTS) throw error;
+			await new Promise((resolve) => setTimeout(resolve, CREATE_RETRY_BASE_DELAY_MS * attempt));
+		}
+		const json = await response.json();
+		this._sandboxId = json.id;
+		this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+		this._populateAddressFromResponse(json);
+	}
+	/**
+	* Copy `response.instanceUrl` into the injected {@link SandboxAddressRegistry}
+	* when both are present. Called from both {@link start} branches (fresh
+	* provision + reattach) with the workspace-proxy response for this sandbox.
+	*
+	* The proxy discovers the IPv6 during `Sandbox.create()` and stores it in
+	* `environment_sandboxes.instance_url`; both the create response and
+	* `GET /sandbox/:id` echo the same field. The runtime does not do any
+	* discovery of its own — it only mirrors the field into an in-process map
+	* so {@link executeCommand} can `Map.get()` before every exec without an
+	* 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.
+	*/
+	_populateAddressFromResponse(json) {
+		if (!this._addressRegistry) return;
+		if (!json.instanceUrl) return;
+		this._addressRegistry.set(json.id, json.instanceUrl);
+	}
+	async stop() {
+		await this.destroy();
+	}
+	async destroy() {
+		if (!this._sandboxId) return;
+		const destroyedSandboxId = this._sandboxId;
+		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
+		this._sandboxId = void 0;
+		this._createdAt = null;
+		this._lease = null;
+		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
+	* command line sent to the remote shell, which lets callers use pipes,
+	* redirects, and chaining (`ls -la | grep foo`). This matches the contract
+	* of {@link MastraSandbox} and the local sandbox implementation.
+	*
+	* `args`, when provided, are always shell-quoted so they cannot inject
+	* additional shell syntax.
+	*
+	* Security: callers MUST NOT pass untrusted input as `command`. If any part
+	* of the invocation is derived from an untrusted source, pass it through
+	* `args` (which is safely quoted) or shell-quote it yourself before
+	* inclusion. Untrusted `command` values allow arbitrary shell syntax
+	* execution on the remote sandbox.
+	*/
+	async executeCommand(command, args, options) {
+		await this.ensureRunning();
+		if (!this._sandboxId) throw new SandboxNotReadyError(this.id);
+		const started = Date.now();
+		const fullCommand = buildCommand(command, args);
+		const effectiveTimeout = options?.timeout ?? this._timeout;
+		const instanceUrl = this._addressRegistry?.get(this._sandboxId);
+		if (instanceUrl) {
+			const privateNet = await this._tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options);
+			if (privateNet) {
+				const privateExit = privateNet.exitCode ?? 124;
+				return {
+					success: privateExit === 0,
+					exitCode: privateExit,
+					stdout: privateNet.stdout,
+					stderr: privateNet.stderr,
+					timedOut: privateNet.timedOut,
+					command: fullCommand,
+					executionTimeMs: Date.now() - started
+				};
+			}
+		}
+		const result = await this._runDirectExec(fullCommand, effectiveTimeout, options);
+		const exitCode = result.exitCode ?? 124;
+		return {
+			success: exitCode === 0,
+			exitCode,
+			stdout: result.stdout,
+			stderr: result.stderr,
+			timedOut: result.timedOut,
+			command: fullCommand,
+			executionTimeMs: Date.now() - started
+		};
+	}
+	/**
+	* 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,
+				...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
+		});
+	}
+	/**
+	* Try to run the exec against the in-sandbox sidecar over Railway's private
+	* network. Returns the result on success (including non-zero exit codes and
+	* timeouts — those are real command results, not failures). Returns
+	* `undefined` when the caller should fall back to the lease path:
+	*
+	* - Transport failure (connection refused, mid-stream drop, no `exit`
+	*   frame). The registry entry is evicted so subsequent execs skip the
+	*   private-net dial until the sidecar re-registers.
+	* - Sidecar answered with a non-2xx HTTP status. Registry is left intact —
+	*   the address is still valid; something else is wrong (bad request,
+	*   sidecar bug). Only this specific exec falls back.
+	*/
+	async _tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options) {
+		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		const execOptions = {
+			command: fullCommand,
+			...options?.cwd !== void 0 && { cwd: options.cwd },
+			...filteredEnv !== void 0 && { env: filteredEnv },
+			...effectiveTimeout != null && effectiveTimeout > 0 && { timeoutMs: effectiveTimeout },
+			...this._privateNetFetch && { fetch: this._privateNetFetch }
+		};
+		let result;
+		try {
+			result = await execViaPrivateNetwork(instanceUrl, execOptions);
+		} catch (error) {
+			if (error instanceof PrivateNetExecHttpError) return;
+			this._invalidateAddress();
+			return;
+		}
+		if (result.timedOut) {
+			if (!result.opened) this._invalidateAddress();
+			return result;
+		}
+		if (!result.opened || result.exitCode === null) {
+			this._invalidateAddress();
+			return;
+		}
+		return result;
+	}
+	/**
+	* Evict this sandbox's entry from the address registry after an observed
+	* transport failure. The entry stays gone until the next start() re-reads
+	* `instanceUrl` from a workspace-proxy response — until then, execs skip
+	* the private-net dial and go straight to the lease path.
+	*/
+	_invalidateAddress() {
+		if (this._sandboxId) this._addressRegistry?.delete(this._sandboxId);
+	}
+	/**
+	* 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 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,
+			name: this.name,
+			provider: this.provider,
+			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,
+			name: this.name,
+			provider: this.provider,
+			status: this.status,
+			createdAt: json.createdAt ? new Date(json.createdAt) : this._createdAt ?? /* @__PURE__ */ new Date(),
+			metadata: {
+				sandboxId: json.id,
+				providerResourceId: json.providerResourceId ?? void 0,
+				platformStatus: json.status
+			}
+		};
+	}
+	getInstructions(opts) {
+		const defaultInstructions = `Platform sandbox${this._sandboxId ? ` ${this._sandboxId}` : ""}. Execute commands with the sandbox command APIs.`;
+		if (typeof this._instructionsOverride === "function") return this._instructionsOverride({
+			defaultInstructions,
+			requestContext: opts?.requestContext
+		});
+		if (typeof this._instructionsOverride === "string") return this._instructionsOverride;
+		return defaultInstructions;
+	}
+};
+//#endregion
+//#region src/provider.ts
+const platformSandboxProvider = {
+	id: "platform",
+	name: "Mastra Platform Sandbox",
+	description: "Environment-scoped sandbox execution through Mastra Platform workspace proxy",
+	configSchema: {
+		type: "object",
+		properties: {
+			accessToken: {
+				type: "string",
+				description: "Mastra Platform access token (falls back to MASTRA_PLATFORM_ACCESS_TOKEN)"
+			},
+			projectId: {
+				type: "string",
+				description: "Platform project ID (falls back to MASTRA_PROJECT_ID)"
+			},
+			environmentId: {
+				type: "string",
+				description: "Platform environment ID (falls back to MASTRA_ENVIRONMENT_ID)"
+			},
+			sandboxId: {
+				type: "string",
+				description: "Reattach to an existing Platform sandbox by ID"
+			},
+			idleTimeoutMinutes: {
+				type: "number",
+				description: "Minutes before the sandbox can be destroyed while idle"
+			},
+			networkIsolation: {
+				type: "string",
+				description: "Network isolation mode",
+				enum: ["ISOLATED", "PRIVATE"],
+				default: "ISOLATED"
+			},
+			env: {
+				type: "object",
+				description: "Environment variables",
+				additionalProperties: { type: "string" }
+			},
+			timeout: {
+				type: "number",
+				description: "Default command timeout in ms"
+			}
+		}
+	},
+	createSandbox: (config) => new PlatformSandbox(config)
+};
+const platformFilesystemProvider = {
+	id: "platform",
+	name: "Mastra Platform Filesystem",
+	description: "Bucket-backed filesystem access through Mastra Platform workspace proxy",
+	configSchema: {
+		type: "object",
+		properties: {
+			accessToken: {
+				type: "string",
+				description: "Mastra Platform access token (falls back to MASTRA_PLATFORM_ACCESS_TOKEN)"
+			},
+			projectId: {
+				type: "string",
+				description: "Platform project ID (falls back to MASTRA_PROJECT_ID)"
+			},
+			bucketName: {
+				type: "string",
+				description: "Platform workspace bucket name (falls back to MASTRA_PLATFORM_BUCKET_NAME)"
+			},
+			readOnly: {
+				type: "boolean",
+				description: "Mount as read-only",
+				default: false
+			}
+		}
+	},
+	createFilesystem: (config) => new PlatformFilesystem(config)
+};
+//#endregion
+//#region src/address-registry.ts
+/**
+* Concrete in-process {@link SandboxAddressRegistry}. Backed by a `Map`; no
+* eviction policy, no TTL — entries live until an observed transport failure
+* calls `delete`, until the sandbox is explicitly destroyed, or until the
+* process exits.
+*/
+var InProcessSandboxAddressRegistry = class {
+	#map = /* @__PURE__ */ new Map();
+	get(sandboxId) {
+		return this.#map.get(sandboxId);
+	}
+	/**
+	* Populate or overwrite the address for a sandbox. Called by
+	* {@link PlatformSandbox.start} on every fresh provision and every reattach;
+	* overwriting is intentional so a re-provision with a fresh IPv6 heals the
+	* map without a branch.
+	*/
+	set(sandboxId, instanceUrl) {
+		this.#map.set(sandboxId, instanceUrl);
+	}
+	delete(sandboxId) {
+		this.#map.delete(sandboxId);
+	}
+	/**
+	* Test-only introspection. Not part of {@link SandboxAddressRegistry} —
+	* production callers must not read the registry as a whole.
+	*/
+	get size() {
+		return this.#map.size;
+	}
+};
+//#endregion
+export { InProcessSandboxAddressRegistry, PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, PrivateNetExecHttpError, SandboxDestroyedError, SandboxExecTransportError, execViaPrivateNetwork, platformFilesystemProvider, platformSandboxProvider };
+
+//# sourceMappingURL=index.js.map