@mastra/platform-workspace 1.8.2-alpha.0 → 1.9.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { Buffer as Buffer$1 } from "buffer";
-import nodePath from "path";
-import { FactorySandbox, FileExistsError, FileNotFoundError, MastraFilesystem, MastraSandbox, ProcessHandle, SandboxError, SandboxNotReadyError, SandboxProcessManager, UnsupportedStdinCloseError, WorkspaceReadOnlyError } from "@mastra/core/workspace";
+import nodePath, { posix } from "path";
+import { DirectoryNotEmptyError, DirectoryNotFoundError, FactorySandbox, FileExistsError, FileNotFoundError, IsDirectoryError, MastraFilesystem, MastraSandbox, NotDirectoryError, ProcessHandle, SandboxError, SandboxNotReadyError, SandboxProcessManager, UnsupportedStdinCloseError, WorkspaceReadOnlyError } from "@mastra/core/workspace";
 import { createHash } from "crypto";
-import { CommandExitError, Sandbox, TimeoutError } from "e2b";
+import { AuthenticationError, CommandExitError, InvalidArgumentError, NotFoundError, Sandbox, SandboxError as SandboxError$1, SandboxNotFoundError, TimeoutError } from "e2b";
 import { execFile } from "child_process";
 import { promisify } from "util";
 //#region src/client.ts
@@ -310,7 +310,7 @@ var PlatformFilesystem = class extends MastraFilesystem {
 			name: nameFromPath(object.key),
 			type: "file",
 			size: object.size
-		}))].filter((entry) => !options?.extension || entry.type === "directory" || matchesExtension(entry.name, options.extension));
+		}))].filter((entry) => !options?.extension || entry.type === "directory" || matchesExtension$1(entry.name, options.extension));
 	}
 	async listPrefix(prefix, recursive) {
 		const normalized = prefix.replace(/\/$/, "");
@@ -393,7 +393,7 @@ var PlatformFilesystem = class extends MastraFilesystem {
 		};
 	}
 };
-function matchesExtension(name, extension) {
+function matchesExtension$1(name, extension) {
 	return (Array.isArray(extension) ? extension : [extension]).some((ext) => name.endsWith(ext));
 }
 //#endregion
@@ -401,8 +401,8 @@ function matchesExtension(name, extension) {
 const SERIALIZE_TEMPLATE = Symbol("serializeTemplate");
 const GET_TEMPLATE_BUILD_ENVS = Symbol("getTemplateBuildEnvs");
 const MAX_OPERATIONS = 256;
-const MAX_SERIALIZED_BYTES = 256 * 1024;
-const MAX_STRING_LENGTH = 32 * 1024;
+const MAX_SERIALIZED_BYTES = 262144;
+const MAX_STRING_LENGTH = 32768;
 const MAX_COLLECTION_ITEMS = 512;
 const MAX_FAMILY_LENGTH = 200;
 var SerializableSandboxTemplateBuilder = class SerializableSandboxTemplateBuilder {
@@ -785,6 +785,14 @@ const execViaE2BLease = async (lease, options) => {
 		};
 	}
 };
+/** Opens E2B's files API directly against the VM, authenticated by the exec lease. */
+const e2bFilesForLease = (lease) => new Sandbox({
+	sandboxId: lease.sandboxId,
+	envdVersion: E2B_ENVD_VERSION,
+	envdAccessToken: lease.jwt,
+	sandboxUrl: lease.wsEndpoint,
+	validateApiKey: false
+}).files;
 //#endregion
 //#region src/private-net-exec.ts
 /**
@@ -955,6 +963,499 @@ async function execViaPrivateNetwork(instanceUrl, options) {
 	};
 }
 //#endregion
+//#region ../../packages/_internals/workspace/dist/index.js
+/** Directory, relative to the template's build cwd, that holds every marker below. */
+const SETUP_MARKER_DIR = ".mastra-sandbox";
+/**
+* Setup completion marker shared by repo templates and their consumers.
+*
+* A repo template writes this file beside the checkout as its last build
+* step, so it exists only in images where every setup command succeeded. Its
+* content is a digest of the setup commands the image ran, letting a sandbox
+* booted from the image tell whether the setup it is about to run already
+* happened. Relative to the template's build cwd, which is also the runtime
+* working directory the repo was cloned into.
+*
+* This is the single-repository marker. Templates built from a repository
+* list write one marker per repository instead ({@link repoSetupMarkerPath}).
+*/
+const SETUP_MARKER_PATH = ".mastra-sandbox/setup";
+/**
+* Marker for the workspace-level setup of a multi-repository template: the
+* commands that ran at the working directory after every repository was set
+* up. Written even when there were no such commands, so a consumer can tell
+* "ran nothing" from "never built".
+*/
+const WORKSPACE_SETUP_MARKER_PATH = ".mastra-sandbox/workspace-setup";
+/**
+* One line per repository directory whose setup failed while the build was
+* told to continue. Absent when nothing failed. Consumers check this before
+* trusting a per-repository marker: that marker means every step ran, not
+* that every step succeeded.
+*/
+const SETUP_FAILED_MARKER_PATH = ".mastra-sandbox/setup-failed";
+/** Per-repository marker of a multi-repository template, keyed by the clone directory name. */
+function repoSetupMarkerPath(repoDir) {
+	return `${SETUP_MARKER_DIR}/repos/${repoDir}`;
+}
+/** Blank entries never become build steps, so they never count toward the digest either. */
+function normalizeSetupCommands(setupCommand) {
+	return (setupCommand === void 0 ? [] : Array.isArray(setupCommand) ? setupCommand : [setupCommand]).filter((command) => command.trim() !== "");
+}
+/** The marker content for a setup command list: `sha256:<hex>` over the commands joined by newlines. */
+function setupMarkerContent(setupCommand) {
+	return `sha256:${createHash("sha256").update(normalizeSetupCommands(setupCommand).join("\n")).digest("hex")}`;
+}
+/** Shell step that writes the marker relative to the cwd. `content` is a digest, so it is shell-safe. */
+function setupMarkerCommand(content, markerPath = SETUP_MARKER_PATH) {
+	return `mkdir -p "$(dirname "${markerPath}")" && printf '%s' '${content}' > "${markerPath}"`;
+}
+/** A clone directory name is one path segment of word characters, dots and dashes, so it never needs quoting. */
+const REPO_DIR_PATTERN = /^[\w.-]+$/;
+/**
+* Shell step that runs one setup command inside a repository clone.
+*
+* Without the guard this is the plain `cd "<dir>" && <cmd>` step. With it,
+* the `cd` sits inside the parenthesized group so that the failure branch
+* runs back at the build cwd and the failure list lands at the workspace
+* level, never inside the repository.
+*/
+function guardedSetupCommand({ repoDir, command, continueOnFailure }) {
+	if (!REPO_DIR_PATTERN.test(repoDir)) throw new TypeError(`Repository directory "${repoDir}" must match ${REPO_DIR_PATTERN}.`);
+	if (!continueOnFailure) return `cd "${repoDir}" && ${command}`;
+	return `( cd "${repoDir}" && sh -c ${shellQuote$2(command)} ) || { mkdir -p "${SETUP_MARKER_DIR}" && grep -qxF -- '${repoDir}' "${SETUP_FAILED_MARKER_PATH}" 2>/dev/null || printf '%s\\n' '${repoDir}' >> "${SETUP_FAILED_MARKER_PATH}"; }`;
+}
+function shellQuote$2(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function repoCloneCommand({ cloneUrl, destination, branch, tokenEnv }) {
+	return `git ${tokenEnv ? `${gitAuthFlag$1(tokenEnv)} ` : ""}clone --depth=1 --single-branch ${branch ? `--branch ${shellQuote$1(branch)} ` : ""}${shellQuote$1(cloneUrl)} ${shellQuote$1(destination)}`;
+}
+/** Per-invocation auth header; `-c` config never reaches `.git/config`. */
+function gitAuthFlag$1(tokenEnv) {
+	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${tokenEnv}" | base64 -w0)"`;
+}
+function shellQuote$1(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* Shell scripts for the file operations a sandbox can only do atomically (or
+* without moving file bytes over the network) by running a command inside the
+* VM. Each builder takes absolute paths and returns one POSIX `sh` script; the
+* caller runs it with `sh -c` and maps the exit codes below to typed errors.
+*/
+/** Exit codes the scripts use for outcomes the caller turns into typed errors. Any other non-zero code is a plain failure. */
+const FILE_COMMAND_EXIT = {
+	notFound: 20,
+	isDirectory: 21,
+	exists: 22,
+	notDirectory: 23,
+	destIsDirectory: 24
+};
+/** Single-quote a string for safe POSIX shell interpolation. */
+function shellQuote$3(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+const { notFound, isDirectory, exists, notDirectory, destIsDirectory } = FILE_COMMAND_EXIT;
+/** `[ -e ]` is false for a broken symlink, which still occupies the path. */
+const present = (variable) => `{ [ -e "$${variable}" ] || [ -L "$${variable}" ]; }`;
+/**
+* A sibling temp path for `path`, so a later `ln` / `mv` onto `path` stays on
+* one filesystem. Hidden, and unique per call.
+*/
+function siblingTempPath(path) {
+	const suffix = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+	return posix.join(posix.dirname(path), `.${posix.basename(path)}.mastra-tmp-${suffix}`);
+}
+/**
+* Hard-link `$tmp` to `$dest` and delete `$tmp`, failing with `exists` when
+* something is at `$dest`. `ln` onto a directory (or a link to one) would
+* create the link inside it and succeed, so that case is undone and reported
+* as taken too.
+*/
+function linkTempIntoPlace() {
+	return [
+		`ln "$tmp" "$dest" 2>/dev/null || { rm -f "$tmp"; ${present("dest")} && exit ${exists}; exit 1; }`,
+		`if [ -d "$dest" ]; then rm -f "$dest/$(basename "$tmp")" "$tmp"; exit ${exists}; fi`,
+		`rm -f "$tmp"`
+	];
+}
+/**
+* Copy `src` to `dest` inside the sandbox, creating `dest`'s parent.
+*
+* A file source copies its content (a symlinked source is followed). A
+* directory source with `recursive` copies its contents into `dest`, keeping
+* symlinks inside the tree as links. With `overwrite: false` the destination
+* is claimed atomically: a directory with an exclusive `mkdir`, a file by
+* copying to a temp name and hard-linking it into place (`link(2)` fails when
+* the destination exists).
+*
+* Exits: `notFound` (no source), `isDirectory` (directory source without
+* `recursive`), `destIsDirectory` (a file onto an existing directory or a link
+* to one), `exists`.
+*/
+function copyCommand(src, dest, options = {}) {
+	const noClobber = options.overwrite === false;
+	return [
+		`src=${shellQuote$3(src)}`,
+		`dest=${shellQuote$3(dest)}`,
+		`[ -e "$src" ] || exit ${notFound}`,
+		`mkdir -p "$(dirname "$dest")" || exit 1`,
+		`if [ -d "$src" ]; then`,
+		options.recursive ? `  :` : `  exit ${isDirectory}`,
+		noClobber ? `  mkdir "$dest" 2>/dev/null || exit ${exists}` : `  mkdir -p "$dest" || exit 1`,
+		`  cp -R -P "$src"/. "$dest"/ || exit 1`,
+		`  exit 0`,
+		`fi`,
+		noClobber ? `${present("dest")} && exit ${exists}` : `if [ -d "$dest" ]; then exit ${destIsDirectory}; fi`,
+		...noClobber ? [
+			`tmp=${shellQuote$3(siblingTempPath(dest))}`,
+			`cp "$src" "$tmp" || { rm -f "$tmp"; exit 1; }`,
+			...linkTempIntoPlace()
+		] : [`cp "$src" "$dest" || exit 1`]
+	].join("\n");
+}
+/**
+* Move `src` to `dest` without replacing anything at `dest`, creating `dest`'s
+* parent. A skipped `mv -n` is detected by the source surviving, whatever
+* its exit code. If a directory appears at `dest` between the check and the
+* move, `mv` moves `src` into it (BSD `mv` has no `-T`), and that is reported
+* as success; the no-clobber rename itself is atomic.
+*
+* Exits: `notFound` (no source), `exists`.
+*/
+function moveNoClobberCommand(src, dest) {
+	return [
+		`src=${shellQuote$3(src)}`,
+		`dest=${shellQuote$3(dest)}`,
+		`${present("src")} || exit ${notFound}`,
+		`${present("dest")} && exit ${exists}`,
+		`mkdir -p "$(dirname "$dest")" || exit 1`,
+		`mv -n "$src" "$dest" 2>/dev/null || { ${present("src")} && ${present("dest")} && exit ${exists}; exit 1; }`,
+		`${present("src")} && exit ${exists}`,
+		`exit 0`
+	].join("\n");
+}
+/**
+* Append the bytes already written to `tmp` onto `dest`, then delete `tmp`.
+* The content travels as a file rather than a command argument, so it has no
+* size limit. Creates `dest` (and its parent) when missing.
+*
+* Exits: `isDirectory` (dest is a directory).
+*/
+function appendFromCommand(tmp, dest) {
+	return [
+		`tmp=${shellQuote$3(tmp)}`,
+		`dest=${shellQuote$3(dest)}`,
+		`if [ -d "$dest" ]; then rm -f "$tmp"; exit ${isDirectory}; fi`,
+		`mkdir -p "$(dirname "$dest")" && cat "$tmp" >> "$dest"`,
+		`status=$?`,
+		`rm -f "$tmp"`,
+		`exit $status`
+	].join("\n");
+}
+/**
+* Publish the file already written to `tmp` at `dest` only if nothing is
+* there, then delete `tmp`. `ln` (`link(2)`) is the atomic exclusivity check;
+* `tmp` must be on the same filesystem, e.g. from {@link siblingTempPath}.
+*
+* Exits: `exists`, `notDirectory` (dest's parent is not a directory).
+*/
+function linkNoClobberCommand(tmp, dest) {
+	return [
+		`tmp=${shellQuote$3(tmp)}`,
+		`dest=${shellQuote$3(dest)}`,
+		`if [ ! -d "$(dirname "$dest")" ]; then rm -f "$tmp"; exit ${notDirectory}; fi`,
+		`if ${present("dest")}; then rm -f "$tmp"; exit ${exists}; fi`,
+		...linkTempIntoPlace()
+	].join("\n");
+}
+/** Default recursion depth for `readdir({ recursive: true })`, matching `LocalFilesystem`. */
+const DEFAULT_MAX_DEPTH = 100;
+const toAbsolute = (path) => posix.resolve("/", path);
+/** The entry's own type: a symlink is a link even when it points at a directory. */
+const isSymlink = (info) => info.symlinkTarget !== void 0;
+function toWriteData(content) {
+	if (typeof content === "string") return content;
+	return content.buffer.slice(content.byteOffset, content.byteOffset + content.byteLength);
+}
+function matchesExtension(name, extension) {
+	if (!extension) return true;
+	const ext = posix.extname(name);
+	return (Array.isArray(extension) ? extension : [extension]).some((e) => e === ext || e === ext.slice(1));
+}
+/**
+* A sandbox's disk, read and written through E2B's envd files API, with the
+* operations the files API can't do in one call (copy, append, no-clobber
+* writes and moves) run as one shell command inside the VM so they are atomic
+* and file bytes never round-trip through the host. Paths are absolute inside
+* the sandbox; this class does not confine paths or symlinks to any root.
+*
+* Providers supply how to reach the files API and the shell, and how to read
+* their SDK's errors.
+*
+* If a provider's `runCommand` re-runs a command whose first run already
+* finished (e.g. a retry after a dropped connection), the second run sees the
+* first's result: a no-clobber copy, write or move reports `FileExistsError`
+* or `FileNotFoundError`, and an append fails, even though the work was done.
+*/
+var FilesApiFilesystem = class extends MastraFilesystem {
+	async readFile(path, options) {
+		const abs = toAbsolute(path);
+		const bytes = await this.runFiles("readFile", async (files) => {
+			try {
+				return await files.read(abs, { format: "bytes" });
+			} catch (error) {
+				const kind = this.errorKind(error);
+				if (kind === "not-found") throw new FileNotFoundError(path);
+				if (kind === "invalid-argument") throw new IsDirectoryError(path);
+				throw error;
+			}
+		});
+		const buffer = Buffer$1.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+		return options?.encoding ? buffer.toString(options.encoding) : buffer;
+	}
+	async writeFile(path, content, options) {
+		const abs = toAbsolute(path);
+		if (options?.overwrite !== false) {
+			await this.runFiles("writeFile", async (files) => {
+				if (options?.recursive === false) await this.#assertParentDirectory(files, abs, path);
+				await this.#write(files, abs, path, toWriteData(content));
+			});
+			return;
+		}
+		const tmp = siblingTempPath(abs);
+		const upload = async (files) => {
+			if (options.recursive === false) await this.#assertParentDirectory(files, abs, path);
+			await this.#write(files, tmp, path, toWriteData(content));
+		};
+		await this.#publishTemp(tmp, "writeFile", upload, linkNoClobberCommand(tmp, abs), path, {
+			exists: () => new FileExistsError(path),
+			notDirectory: () => new NotDirectoryError(posix.dirname(path))
+		});
+	}
+	async appendFile(path, content) {
+		const abs = toAbsolute(path);
+		const tmp = siblingTempPath(abs);
+		const upload = (files) => this.#write(files, tmp, path, toWriteData(content));
+		await this.#publishTemp(tmp, "appendFile", upload, appendFromCommand(tmp, abs), path, { isDirectory: () => new IsDirectoryError(path) });
+	}
+	async deleteFile(path, options) {
+		const abs = toAbsolute(path);
+		await this.runFiles("deleteFile", async (files) => {
+			const info = await this.#info(files, abs);
+			if (!info) {
+				if (options?.force) return;
+				throw new FileNotFoundError(path);
+			}
+			if (!isSymlink(info) && info.type === "dir") throw new IsDirectoryError(path);
+			await files.remove(abs);
+		});
+	}
+	/**
+	* One `cp` inside the VM. A recursive copy keeps symlinks inside the tree as
+	* links; `overwrite: false` claims the destination atomically.
+	*/
+	async copyFile(src, dest, options) {
+		const command = copyCommand(toAbsolute(src), toAbsolute(dest), {
+			recursive: options?.recursive,
+			overwrite: options?.overwrite
+		});
+		await this.#command("copyFile", command, `${src} -> ${dest}`, {
+			notFound: () => new FileNotFoundError(src),
+			isDirectory: () => new IsDirectoryError(src),
+			destIsDirectory: () => new IsDirectoryError(dest),
+			exists: () => new FileExistsError(dest)
+		});
+	}
+	async moveFile(src, dest, options) {
+		const srcAbs = toAbsolute(src);
+		const destAbs = toAbsolute(dest);
+		if (options?.overwrite === false) {
+			await this.#command("moveFile", moveNoClobberCommand(srcAbs, destAbs), `${src} -> ${dest}`, {
+				notFound: () => new FileNotFoundError(src),
+				exists: () => new FileExistsError(dest)
+			});
+			return;
+		}
+		await this.runFiles("moveFile", async (files) => {
+			try {
+				await files.rename(srcAbs, destAbs);
+			} catch (error) {
+				if (this.errorKind(error) === "not-found") throw new FileNotFoundError(src);
+				throw error;
+			}
+		});
+	}
+	async mkdir(path, options) {
+		const abs = toAbsolute(path);
+		await this.runFiles("mkdir", async (files) => {
+			if (options?.recursive === false) await this.#assertParentDirectory(files, abs, path);
+			try {
+				await files.makeDir(abs);
+			} catch (error) {
+				if (this.errorKind(error) === "invalid-argument") throw new FileExistsError(path);
+				throw error;
+			}
+		});
+	}
+	async rmdir(path, options) {
+		const abs = toAbsolute(path);
+		await this.runFiles("rmdir", async (files) => {
+			const info = await this.#info(files, abs);
+			if (!info) {
+				if (options?.force) return;
+				throw new DirectoryNotFoundError(path);
+			}
+			if (!options?.recursive) {
+				if (isSymlink(info) || info.type !== "dir") throw new NotDirectoryError(path);
+				if ((await files.list(abs)).length > 0) throw new DirectoryNotEmptyError(path);
+			} else if (!isSymlink(info) && info.type !== "dir") throw new NotDirectoryError(path);
+			await files.remove(abs);
+		});
+	}
+	async readdir(path, options) {
+		const abs = toAbsolute(path);
+		const depth = options?.recursive ? (options.maxDepth ?? DEFAULT_MAX_DEPTH) + 1 : 1;
+		const entries = await this.runFiles("readdir", async (files) => {
+			try {
+				return await files.list(abs, { depth });
+			} catch (error) {
+				const kind = this.errorKind(error);
+				if (kind === "not-found") throw new DirectoryNotFoundError(path);
+				if (kind === "invalid-argument") throw new NotDirectoryError(path);
+				throw error;
+			}
+		});
+		const result = [];
+		for (const entry of entries) {
+			if (!entry.type) continue;
+			const name = posix.relative(abs, entry.path);
+			const type = entry.type === "dir" ? "directory" : "file";
+			if (type === "file" && !matchesExtension(name, options?.extension)) continue;
+			const link = isSymlink(entry);
+			result.push({
+				name,
+				type,
+				...type === "file" && !link && { size: entry.size },
+				...link && {
+					isSymlink: true,
+					symlinkTarget: entry.symlinkTarget
+				}
+			});
+		}
+		return result;
+	}
+	async exists(path) {
+		const abs = toAbsolute(path);
+		return this.runFiles("exists", async (files) => Boolean((await this.#info(files, abs))?.type));
+	}
+	async stat(path) {
+		const abs = toAbsolute(path);
+		return this.runFiles("stat", async (files) => {
+			let info = await this.#info(files, abs);
+			if (info?.type && isSymlink(info)) info = await this.#info(files, posix.resolve(posix.dirname(abs), info.symlinkTarget));
+			if (!info?.type) throw new FileNotFoundError(path);
+			const modifiedAt = info.modifiedTime ?? /* @__PURE__ */ new Date(0);
+			return {
+				name: posix.basename(abs),
+				path: abs,
+				type: info.type === "dir" ? "directory" : "file",
+				size: info.type === "dir" ? 0 : info.size,
+				createdAt: modifiedAt,
+				modifiedAt
+			};
+		});
+	}
+	/** `getInfo` without following the entry itself, or `undefined` when nothing is there. */
+	async #info(files, abs) {
+		try {
+			return await files.getInfo(abs);
+		} catch (error) {
+			if (this.errorKind(error) === "not-found") return void 0;
+			throw error;
+		}
+	}
+	async #assertParentDirectory(files, abs, path) {
+		const parent = await this.#info(files, posix.dirname(abs));
+		if (!parent?.type) throw new DirectoryNotFoundError(posix.dirname(path));
+		if (parent.type !== "dir") throw new NotDirectoryError(posix.dirname(path));
+	}
+	async #write(files, abs, path, data) {
+		try {
+			await files.write(abs, data);
+		} catch (error) {
+			if (this.errorKind(error) === "invalid-argument") throw new IsDirectoryError(path);
+			throw error;
+		}
+	}
+	/**
+	* Upload the temp file `tmp`, then run the command that consumes it. The
+	* script deletes it on every path it controls; if the upload or the command
+	* fails part-way, delete it here so it doesn't linger in the user's tree.
+	*/
+	async #publishTemp(tmp, operation, upload, script, subject, errors) {
+		try {
+			await this.runFiles(operation, upload);
+			await this.#command(operation, script, subject, errors);
+		} catch (error) {
+			await this.runFiles(operation, (files) => files.remove(tmp)).catch(() => {});
+			throw error;
+		}
+	}
+	/** Run a file command and turn its known exit codes into typed errors. */
+	async #command(operation, script, subject, errors) {
+		const result = await this.runCommand(operation, script);
+		if (result.exitCode === 0) return;
+		for (const [outcome, code] of Object.entries(FILE_COMMAND_EXIT)) {
+			const toError = errors[outcome];
+			if (code === result.exitCode && toError) throw toError();
+		}
+		throw new Error(`${operation} ${subject} failed (exit ${result.exitCode}): ${result.stderr.trim()}`);
+	}
+};
+//#endregion
+//#region src/sandbox-filesystem.ts
+/**
+* envd's edge answers a paused or missing sandbox with a 404 or 502 that the
+* SDK reports as `FileNotFoundError` or `TimeoutError`. Same message pattern as
+* `E2BSandbox`'s dead-sandbox check.
+*/
+const DEAD_SANDBOX = /\b(?:paused\s+)?sandbox(?:\s+\S+)?\s+(?:was\s+)?not found\b/i;
+const isDeadSandbox = (error) => error instanceof SandboxNotFoundError || error instanceof Error && DEAD_SANDBOX.test(error.message);
+/** A failure that isn't a file-level answer from envd: the sandbox is gone, the call timed out, or it failed before envd replied. */
+const isBrokenSandboxError = (error) => isDeadSandbox(error) || error instanceof TimeoutError || !(error instanceof SandboxError$1);
+/**
+* The disk of a {@link PlatformSandbox}, read and written through E2B's files
+* API directly on the VM, authenticated by the same lease `executeCommand`
+* uses. Copies, appends and no-clobber writes and moves run as one shell
+* command in the VM, so they are atomic and file bytes don't round-trip
+* through the host. Paths are absolute inside the sandbox; this class does not
+* confine paths or symlinks to any root.
+*/
+var PlatformSandboxFilesystem = class extends FilesApiFilesystem {
+	id;
+	name = "PlatformSandboxFilesystem";
+	provider = "platform";
+	status = "ready";
+	#runner;
+	constructor(runner) {
+		super({ name: "PlatformSandboxFilesystem" });
+		this.id = `${runner.id}-filesystem`;
+		this.#runner = runner;
+	}
+	runFiles(operation, fn) {
+		return this.#runner.withFiles(operation, fn);
+	}
+	runCommand(_operation, script) {
+		return this.#runner.runCommand(script);
+	}
+	errorKind(error) {
+		if (error instanceof NotFoundError && !isDeadSandbox(error)) return "not-found";
+		if (error instanceof InvalidArgumentError) return "invalid-argument";
+	}
+};
+//#endregion
 //#region src/sandbox.ts
 /**
 * How long before a lease's stated `expiresAt` we should treat it as
@@ -1037,6 +1538,8 @@ var SandboxDestroyedError = class extends Error {
 		this.attempts = diagnostics.attempts;
 	}
 };
+/** Cap on one file command (a recursive copy can be large) when the sandbox sets no timeout. */
+const FILE_COMMAND_TIMEOUT_MS = 6e5;
 /**
 * Compose a shell command line from a `command` string and optional `args`.
 *
@@ -1052,9 +1555,9 @@ var SandboxDestroyedError = class extends Error {
 * sandbox.
 */
 function buildCommand(command, args) {
-	return args?.length ? `${command} ${args.map(shellQuote$2).join(" ")}` : command;
+	return args?.length ? `${command} ${args.map(shellQuote).join(" ")}` : command;
 }
-function shellQuote$2(arg) {
+function shellQuote(arg) {
 	if (/^[a-zA-Z0-9._\-/=:@]+$/.test(arg)) return arg;
 	return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
@@ -1155,6 +1658,10 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	_createdAt = null;
 	_webSocketFactory;
 	_e2bExecRunner;
+	_e2bFilesFactory;
+	/** Files handle for the current lease, rebuilt whenever the lease changes. */
+	_e2bFiles = null;
+	_filesystem;
 	_privateNetFetch;
 	/**
 	* Registry that maps `sandboxId → instanceUrl` for the private-network
@@ -1244,6 +1751,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		this._instructionsOverride = options.instructions;
 		this._webSocketFactory = options.webSocketFactory;
 		this._e2bExecRunner = options.e2bExecRunner ?? execViaE2BLease;
+		this._e2bFilesFactory = options.e2bFilesFactory ?? e2bFilesForLease;
 		this._privateNetFetch = options.privateNetFetch;
 		this._addressRegistry = options.addressRegistry;
 	}
@@ -1750,6 +2258,15 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	* execution on the remote sandbox.
 	*/
 	async executeCommand(command, args, options) {
+		return this._executeCommand(command, args, options, { once: false });
+	}
+	/**
+	* `executeCommand`, optionally sent at most once. With `once`, a transport
+	* failure after the command may have started is thrown instead of retried
+	* (on the lease or over the private network), so a script that changes files
+	* never runs twice.
+	*/
+	async _executeCommand(command, args, options, { once }) {
 		await this.ensureRunning();
 		if (!this._sandboxId) throw new SandboxNotReadyError(this.id);
 		const started = Date.now();
@@ -1764,7 +2281,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			}
 		} : options;
 		await this._awaitTransportReady();
-		const instanceUrl = this._addressRegistry?.get(this._sandboxId);
+		const instanceUrl = once ? void 0 : this._addressRegistry?.get(this._sandboxId);
 		if (instanceUrl) {
 			const privateNet = await this._tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, execCallOptions);
 			if (privateNet) {
@@ -1780,7 +2297,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 				};
 			}
 		}
-		const result = await this._runDirectExec(fullCommand, effectiveTimeout, execCallOptions);
+		const result = await this._runDirectExec(fullCommand, effectiveTimeout, execCallOptions, once ? 1 : 2);
 		const exitCode = result.exitCode ?? 124;
 		return {
 			success: exitCode === 0,
@@ -1825,12 +2342,12 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		const filtered = Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0));
 		return Object.keys(filtered).length > 0 ? filtered : void 0;
 	}
-	async _runDirectExec(fullCommand, effectiveTimeout, options) {
+	async _runDirectExec(fullCommand, effectiveTimeout, options, attempts = 2) {
 		const filteredEnv = this._execEnv(options);
 		let lastResult;
 		let lastLease;
 		let attemptsMade = 0;
-		for (let attempt = 0; attempt < 2; attempt++) {
+		for (let attempt = 0; attempt < attempts; attempt++) {
 			if (attempt > 0 && lastLease && this._lease === lastLease) this._lease = null;
 			let lease;
 			try {
@@ -1962,6 +2479,91 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			if (this._leaseInFlight === inFlight) this._leaseInFlight = null;
 		}
 	}
+	/**
+	* The sandbox's disk through E2B's files API, called directly on the VM with
+	* the same lease `executeCommand` uses. Paths are absolute inside the
+	* sandbox and are not confined to any root. Absent on non-E2B sandboxes, so
+	* callers fall back to `executeCommand`.
+	*/
+	get filesystem() {
+		if (this._client.sandboxProvider !== "e2b") return void 0;
+		this._filesystem ??= new PlatformSandboxFilesystem({
+			id: this.id,
+			withFiles: (operation, fn) => this._withE2BFiles(operation, fn),
+			runCommand: (script) => this._executeCommand("sh", ["-c", script], this._timeout === void 0 ? { timeout: FILE_COMMAND_TIMEOUT_MS } : {}, { once: true })
+		});
+		return this._filesystem;
+	}
+	/**
+	* Run a filesystem operation against the VM through the files API. Each
+	* files call that envd rejects for its token is retried once with a fresh
+	* lease: the rejection proves that call did nothing, and the calls before it
+	* already succeeded, so nothing is replayed. Any other failure is thrown
+	* unchanged. A dead sandbox or a broken transport also drops the cached
+	* lease, so the next operation re-mints it and learns about a destroyed
+	* sandbox (410) the same way `executeCommand` does.
+	*/
+	async _withE2BFiles(operation, fn) {
+		await this.ensureRunning();
+		if (!this._sandboxId) throw new SandboxNotReadyError(this.id);
+		let current = await this._filesHandle(operation, 1);
+		const call = async (invoke) => {
+			try {
+				return await invoke(current.files);
+			} catch (error) {
+				if (error instanceof AuthenticationError) {
+					if (this._lease === current.lease) this._lease = null;
+					current = await this._filesHandle(operation, 2);
+					try {
+						return await invoke(current.files);
+					} catch (retryError) {
+						if (isBrokenSandboxError(retryError) && this._lease === current.lease) this._lease = null;
+						throw retryError;
+					}
+				}
+				if (isBrokenSandboxError(error) && this._lease === current.lease) this._lease = null;
+				throw error;
+			}
+		};
+		return fn({
+			read: (path, opts) => call((files) => files.read(path, opts)),
+			write: (path, data) => call((files) => files.write(path, data)),
+			list: (path, opts) => call((files) => files.list(path, opts)),
+			makeDir: (path) => call((files) => files.makeDir(path)),
+			rename: (oldPath, newPath) => call((files) => files.rename(oldPath, newPath)),
+			remove: (path) => call((files) => files.remove(path)),
+			getInfo: (path) => call((files) => files.getInfo(path))
+		});
+	}
+	/** The files handle for the current lease, rebuilt only when the lease changes. */
+	async _filesHandle(operation, attempts) {
+		const lease = await this._fileLease(operation, attempts);
+		if (lease.provider !== "e2b") throw new Error(`PlatformSandbox.filesystem requires an E2B-backed sandbox; this sandbox's provider is "${lease.provider}"`);
+		if (this._e2bFiles?.lease !== lease) this._e2bFiles = {
+			lease,
+			files: this._e2bFilesFactory(lease)
+		};
+		return this._e2bFiles;
+	}
+	/** `_ensureLease`, with a 410 handled the same way `_runDirectExec` handles it. */
+	async _fileLease(operation, attempts) {
+		try {
+			return await this._ensureLease();
+		} catch (error) {
+			if (error instanceof PlatformApiError && error.status === 410) {
+				this._lease = null;
+				const priorSandboxId = this._sandboxId;
+				this._sandboxId = void 0;
+				this.status = "stopped";
+				throw new SandboxDestroyedError(`Sandbox ${priorSandboxId ?? "(unknown)"} was destroyed; /exec-lease returned 410`, {
+					...priorSandboxId && { sandboxId: priorSandboxId },
+					command: `filesystem.${operation}`,
+					attempts
+				});
+			}
+			throw error;
+		}
+	}
 	async getInfo() {
 		if (!this._sandboxId || this.status !== "running") return {
 			id: this.id,
@@ -2014,82 +2616,6 @@ function templateHash(definition) {
 	return createHash("sha256").update(JSON.stringify(content)).digest("hex").slice(0, 16);
 }
 //#endregion
-//#region ../../packages/_internals/workspace/dist/index.js
-/** Directory, relative to the template's build cwd, that holds every marker below. */
-const SETUP_MARKER_DIR = ".mastra-sandbox";
-/**
-* Setup completion marker shared by repo templates and their consumers.
-*
-* A repo template writes this file beside the checkout as its last build
-* step, so it exists only in images where every setup command succeeded. Its
-* content is a digest of the setup commands the image ran, letting a sandbox
-* booted from the image tell whether the setup it is about to run already
-* happened. Relative to the template's build cwd, which is also the runtime
-* working directory the repo was cloned into.
-*
-* This is the single-repository marker. Templates built from a repository
-* list write one marker per repository instead ({@link repoSetupMarkerPath}).
-*/
-const SETUP_MARKER_PATH = ".mastra-sandbox/setup";
-/**
-* Marker for the workspace-level setup of a multi-repository template: the
-* commands that ran at the working directory after every repository was set
-* up. Written even when there were no such commands, so a consumer can tell
-* "ran nothing" from "never built".
-*/
-const WORKSPACE_SETUP_MARKER_PATH = ".mastra-sandbox/workspace-setup";
-/**
-* One line per repository directory whose setup failed while the build was
-* told to continue. Absent when nothing failed. Consumers check this before
-* trusting a per-repository marker: that marker means every step ran, not
-* that every step succeeded.
-*/
-const SETUP_FAILED_MARKER_PATH = ".mastra-sandbox/setup-failed";
-/** Per-repository marker of a multi-repository template, keyed by the clone directory name. */
-function repoSetupMarkerPath(repoDir) {
-	return `${SETUP_MARKER_DIR}/repos/${repoDir}`;
-}
-/** Blank entries never become build steps, so they never count toward the digest either. */
-function normalizeSetupCommands(setupCommand) {
-	return (setupCommand === void 0 ? [] : Array.isArray(setupCommand) ? setupCommand : [setupCommand]).filter((command) => command.trim() !== "");
-}
-/** The marker content for a setup command list: `sha256:<hex>` over the commands joined by newlines. */
-function setupMarkerContent(setupCommand) {
-	return `sha256:${createHash("sha256").update(normalizeSetupCommands(setupCommand).join("\n")).digest("hex")}`;
-}
-/** Shell step that writes the marker relative to the cwd. `content` is a digest, so it is shell-safe. */
-function setupMarkerCommand(content, markerPath = SETUP_MARKER_PATH) {
-	return `mkdir -p "$(dirname "${markerPath}")" && printf '%s' '${content}' > "${markerPath}"`;
-}
-/** A clone directory name is one path segment of word characters, dots and dashes, so it never needs quoting. */
-const REPO_DIR_PATTERN = /^[\w.-]+$/;
-/**
-* Shell step that runs one setup command inside a repository clone.
-*
-* Without the guard this is the plain `cd "<dir>" && <cmd>` step. With it,
-* the `cd` sits inside the parenthesized group so that the failure branch
-* runs back at the build cwd and the failure list lands at the workspace
-* level, never inside the repository.
-*/
-function guardedSetupCommand({ repoDir, command, continueOnFailure }) {
-	if (!REPO_DIR_PATTERN.test(repoDir)) throw new TypeError(`Repository directory "${repoDir}" must match ${REPO_DIR_PATTERN}.`);
-	if (!continueOnFailure) return `cd "${repoDir}" && ${command}`;
-	return `( cd "${repoDir}" && sh -c ${shellQuote$1(command)} ) || { mkdir -p "${SETUP_MARKER_DIR}" && grep -qxF -- '${repoDir}' "${SETUP_FAILED_MARKER_PATH}" 2>/dev/null || printf '%s\\n' '${repoDir}' >> "${SETUP_FAILED_MARKER_PATH}"; }`;
-}
-function shellQuote$1(value) {
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-function repoCloneCommand({ cloneUrl, destination, branch, tokenEnv }) {
-	return `git ${tokenEnv ? `${gitAuthFlag$1(tokenEnv)} ` : ""}clone --depth=1 --single-branch ${branch ? `--branch ${shellQuote(branch)} ` : ""}${shellQuote(cloneUrl)} ${shellQuote(destination)}`;
-}
-/** Per-invocation auth header; `-c` config never reaches `.git/config`. */
-function gitAuthFlag$1(tokenEnv) {
-	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${tokenEnv}" | base64 -w0)"`;
-}
-function shellQuote(value) {
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-//#endregion
 //#region src/repo-template.ts
 const execFileAsync = promisify(execFile);
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
@@ -2368,7 +2894,7 @@ async function resolveDefaultBranchHead(cloneUrl, token, execute = execFileAsync
 			"HEAD"
 		], {
 			timeout: 1e4,
-			maxBuffer: 1024 * 1024,
+			maxBuffer: 1048576,
 			env
 		});
 		const sha = stdout.trim().split(/\s+/, 1)[0];
@@ -2670,6 +3196,6 @@ var InProcessSandboxAddressRegistry = class {
 	}
 };
 //#endregion
-export { InProcessSandboxAddressRegistry, PlatformApiError, PlatformClient, PlatformFactorySandbox, PlatformFilesystem, PlatformSandbox, PrivateNetExecHttpError, SandboxDestroyedError, SandboxExecTransportError, Template, createRepoTemplate, execViaPrivateNetwork, platformFilesystemProvider, platformSandboxProvider };
+export { InProcessSandboxAddressRegistry, PlatformApiError, PlatformClient, PlatformFactorySandbox, PlatformFilesystem, PlatformSandbox, PlatformSandboxFilesystem, PrivateNetExecHttpError, SandboxDestroyedError, SandboxExecTransportError, Template, createRepoTemplate, execViaPrivateNetwork, platformFilesystemProvider, platformSandboxProvider };
 
 //# sourceMappingURL=index.js.map