@mastra/platform-workspace 0.2.1 → 0.2.2

package/dist/index.js

@@ -1,632 +1,935 @@
-import { Buffer } from 'buffer';
-import nodePath from 'path';
-import { MastraFilesystem, FileNotFoundError, WorkspaceReadOnlyError, FileExistsError, MastraSandbox, SandboxNotReadyError, SandboxProcessManager, ProcessHandle } from '@mastra/core/workspace';
-
-// src/client.ts
-var DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
-var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+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;
+	if (!value) throw new Error(`${name} is required`);
+	return value;
 }
 function resolvePlatformOptions(options) {
-  return {
-    accessToken: requireOption(
-      options.accessToken ?? process.env.MASTRA_PLATFORM_SECRET_KEY ?? // Deprecated alias — prefer MASTRA_PLATFORM_SECRET_KEY.
-      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
-  };
+	return {
+		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_SECRET_KEY ?? 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 void 0;
-  }
-  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 };
+	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;
-  }
+	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;
-  }
+	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;
+	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);
+	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("/");
+	return key.split("/").map(encodeURIComponent).join("/");
 }
 function nameFromPath(path) {
-  const normalized = normalizePath(path);
-  if (normalized === "/") return "";
-  return normalized.slice(normalized.lastIndexOf("/") + 1);
+	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);
+	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);
+	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;
+	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;
+	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 \u2014 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 \u2014 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 response = await this._client.request(
-      `/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(prefix)}`,
-      {
-        query: {
-          delimiter: options?.recursive ? void 0 : "/",
-          prefix: prefix ? `${prefix.replace(/\/$/, "")}/` : void 0
-        }
-      }
-    );
-    const json = await response.json();
-    return [
-      ...(json.commonPrefixes ?? []).map((prefix2) => ({
-        name: nameFromPath(prefix2.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 }
-      }
-    };
-  }
+	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) {
-  const extensions = Array.isArray(extension) ? extension : [extension];
-  return extensions.some((ext) => name.endsWith(ext));
+	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 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
+			});
+		};
+		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) => {
+			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. */
+const CREATE_RETRY_BASE_DELAY_MS = 2e3;
+/**
+* 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;
+	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, `'\\''`)}'`;
+	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");
-  }
+	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 pid = `platform-proc-${Date.now().toString(36)}-${(this.spawnCounter++).toString(36)}`;
-    const resultPromise = this.sandbox.executeCommand(command, void 0, options);
-    const handle = new PlatformProcessHandle(pid, resultPromise, 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 }
-    }));
-  }
+	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;
-  constructor(options = {}) {
-    super({ ...options, name: "PlatformSandbox", processes: new PlatformProcessManager() });
-    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;
-  }
-  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 = {}) {
-    return new _PlatformSandbox({
-      ...options.id !== void 0 && { id: options.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 }
-    });
-  }
-  async start() {
-    if (this._sandboxId) {
-      try {
-        const response2 = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
-        const json2 = await response2.json();
-        this._createdAt = json2.createdAt ? new Date(json2.createdAt) : /* @__PURE__ */ new Date();
-        return;
-      } 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 response = await this._client.request("/sandbox", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({
-        // Sent so the platform can associate the provisioned resource with a
-        // caller-stable identifier (used for opt-in checkpoint recovery). The
-        // platform treats it as an advisory key: unknown values fall through
-        // to a fresh sandbox, matching pre-existing behavior.
-        id: this.id,
-        environmentId: this._environmentId,
-        idleTimeoutMinutes: this._idleTimeoutMinutes,
-        networkIsolation: this._networkIsolation,
-        env: this._env
-      })
-    });
-    const json = await response.json();
-    this._sandboxId = json.id;
-    this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
-  }
-  async stop() {
-    await this.destroy();
-  }
-  async destroy() {
-    if (!this._sandboxId) return;
-    await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`, { method: "DELETE" });
-    this._sandboxId = void 0;
-    this._createdAt = null;
-  }
-  /**
-   * 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 timeoutSec = effectiveTimeout != null ? Math.ceil(effectiveTimeout / 1e3) : void 0;
-    const clientSignal = effectiveTimeout != null && effectiveTimeout > 0 ? AbortSignal.timeout(effectiveTimeout + 3e4) : void 0;
-    const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}/exec`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({
-        command: fullCommand,
-        timeoutSec,
-        cwd: options?.cwd,
-        env: options?.env
-      }),
-      signal: clientSignal
-    });
-    const json = await response.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
-    };
-  }
-  async getInfo() {
-    if (!this._sandboxId) {
-      return {
-        id: this.id,
-        name: this.name,
-        provider: this.provider,
-        status: this.status,
-        createdAt: this._createdAt ?? /* @__PURE__ */ new Date()
-      };
-    }
-    const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
-    const json = await response.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: {
-        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;
-  }
+var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
+	id;
+	name = "PlatformSandbox";
+	provider = "platform";
+	status = "pending";
+	_client;
+	_environmentId;
+	_sandboxId;
+	_idleTimeoutMinutes;
+	_networkIsolation;
+	_env;
+	_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 returned 404 or 501, fall back permanently to /exec
+	* 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,
+			name: "PlatformSandbox",
+			processes: new PlatformProcessManager()
+		});
+		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;
+	}
+	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 = {}) {
+		return new PlatformSandbox({
+			...options.id !== void 0 && { id: options.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 }
+		});
+	}
+	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();
+				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();
+	}
+	async stop() {
+		await this.destroy();
+	}
+	async destroy() {
+		if (!this._sandboxId) return;
+		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.
+	*
+	* `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;
+		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) {
+			this._lease = null;
+			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 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({
+				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
+		};
+	}
+	/**
+	* 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()
+		};
+		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;
+	}
 };
-
-// src/provider.ts
-var 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 secret key (falls back to MASTRA_PLATFORM_SECRET_KEY)"
-      },
-      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)
+//#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 secret key (falls back to MASTRA_PLATFORM_SECRET_KEY)"
+			},
+			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)
 };
-var 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 secret key (falls back to MASTRA_PLATFORM_SECRET_KEY)"
-      },
-      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)
+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 secret key (falls back to MASTRA_PLATFORM_SECRET_KEY)"
+			},
+			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
 export { PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, platformFilesystemProvider, platformSandboxProvider };
-//# sourceMappingURL=index.js.map
+
 //# sourceMappingURL=index.js.map