@mastra/e2b 0.14.2-alpha.0 → 0.15.0

package/dist/index.js

@@ -1,6 +1,8 @@
-import { FactorySandbox, MastraSandbox, ProcessHandle, SandboxError, SandboxNotReadyError, SandboxProcessManager, UnsupportedStdinCloseError, assertModesUnsupported } from "@mastra/core/workspace";
-import { ApiClient, ConnectionConfig, Sandbox, Template } from "e2b";
+import { DirectoryNotEmptyError, DirectoryNotFoundError, FactorySandbox, FileExistsError, FileNotFoundError, IsDirectoryError, MastraFilesystem, MastraSandbox, NotDirectoryError, ProcessHandle, SandboxError, SandboxNotReadyError, SandboxProcessManager, UnsupportedStdinCloseError, assertModesUnsupported } from "@mastra/core/workspace";
+import { ApiClient, ConnectionConfig, InvalidArgumentError, NotFoundError, Sandbox, SandboxNotFoundError, Template } from "e2b";
 import { createHash } from "crypto";
+import { posix } from "path";
+import { Buffer as Buffer$1 } from "buffer";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { FRAME_PREFIX, buildProgramModule, buildRunner, sanitizeToolId } from "@mastra/core/tools";
@@ -74,6 +76,514 @@ function createDefaultMountableTemplate(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$1(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$1(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 that the SDK
+* reports as `FileNotFoundError`. Same pattern as `E2BSandbox`'s dead-sandbox
+* check, so those errors reach `retryOnDead` instead of reading as a missing file.
+*/
+const DEAD_SANDBOX = /\b(?:paused\s+)?sandbox(?:\s+\S+)?\s+(?:was\s+)?not found\b/i;
+/**
+* The disk of an {@link E2BSandbox}, read and written through E2B's files API
+* (`sandbox.e2b.files`). Each operation starts the sandbox if needed, and each
+* files call is retried once on a sandbox that died server-side, like
+* `executeCommand`. 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 E2BSandboxFilesystem = class extends FilesApiFilesystem {
+	id;
+	name = "E2BSandboxFilesystem";
+	provider = "e2b";
+	status = "ready";
+	#sandbox;
+	constructor(sandbox) {
+		super({ name: "E2BSandboxFilesystem" });
+		this.id = `${sandbox.id}-filesystem`;
+		this.#sandbox = sandbox;
+	}
+	/**
+	* Wrap each files call in `retryOnDead`, so a sandbox that died mid-operation
+	* is restarted and only the call that failed runs again; the calls before it
+	* are never replayed. If the sandbox was killed and replaced rather than
+	* paused, the rest of a multi-call operation runs against the new sandbox's disk.
+	*/
+	async runFiles(_operation, fn) {
+		await this.#sandbox.ensureRunning();
+		const call = (invoke) => this.#sandbox.retryOnDead(() => invoke(this.#sandbox.e2b.files));
+		return fn({
+			read: (path) => call((files) => files.read(path, { format: "bytes" })),
+			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))
+		});
+	}
+	runCommand(operation, script) {
+		if (!this.#sandbox.executeCommand) throw new Error(`${operation} needs E2BSandbox.executeCommand`);
+		return this.#sandbox.executeCommand("sh", ["-c", script]);
+	}
+	errorKind(error) {
+		if (error instanceof NotFoundError && !(error instanceof SandboxNotFoundError) && !(error instanceof Error && DEAD_SANDBOX.test(error.message))) return "not-found";
+		if (error instanceof InvalidArgumentError) return "invalid-argument";
+	}
+};
+//#endregion
 //#region src/sandbox/mounts/types.ts
 const LOG_PREFIX = "[@mastra/e2b]";
 const SAFE_S3_BUCKET_NAME = /^[a-z0-9][a-z0-9.\-]{1,61}[a-z0-9]$/;
@@ -126,7 +636,7 @@ function validatePrefix(prefix) {
 * Arguments containing only safe characters are returned as-is.
 * All others are wrapped in single quotes with embedded single quotes escaped.
 */
-function shellQuote$2(arg) {
+function shellQuote(arg) {
 	if (/^[a-zA-Z0-9._\-/@:=]+$/.test(arg)) return arg;
 	return "'" + arg.replace(/'/g, "'\\''") + "'";
 }
@@ -179,12 +689,12 @@ Error details: ${installResult.stderr || installResult.stdout}`);
 	};
 	if (hasCredentials) {
 		const credentialsContent = useSessionToken ? [
-			`export AWSACCESSKEYID=${shellQuote$2(config.accessKeyId)}`,
-			`export AWSSECRETACCESSKEY=${shellQuote$2(config.secretAccessKey)}`,
-			`export AWSSESSIONTOKEN=${shellQuote$2(config.sessionToken)}`,
-			`export AWS_ACCESS_KEY_ID=${shellQuote$2(config.accessKeyId)}`,
-			`export AWS_SECRET_ACCESS_KEY=${shellQuote$2(config.secretAccessKey)}`,
-			`export AWS_SESSION_TOKEN=${shellQuote$2(config.sessionToken)}`
+			`export AWSACCESSKEYID=${shellQuote(config.accessKeyId)}`,
+			`export AWSSECRETACCESSKEY=${shellQuote(config.secretAccessKey)}`,
+			`export AWSSESSIONTOKEN=${shellQuote(config.sessionToken)}`,
+			`export AWS_ACCESS_KEY_ID=${shellQuote(config.accessKeyId)}`,
+			`export AWS_SECRET_ACCESS_KEY=${shellQuote(config.secretAccessKey)}`,
+			`export AWS_SESSION_TOKEN=${shellQuote(config.sessionToken)}`
 		].join("\n") : `${config.accessKeyId}:${config.secretAccessKey}`;
 		await sandbox.commands.run(`sudo rm -f ${credentialsPath}`);
 		try {
@@ -212,8 +722,8 @@ Error details: ${installResult.stderr || installResult.stdout}`);
 		mountOptions.push("ro");
 		logger.debug(`${LOG_PREFIX} Mounting as read-only`);
 	}
-	const s3fsCmd = `s3fs ${shellQuote$2(bucketArg)} ${shellQuote$2(mountPath)} -o ${mountOptions.join(" -o ")}`;
-	const mountCmd = useSessionToken ? `sudo sh -c ${shellQuote$2(`. ${credentialsPath} && exec ${s3fsCmd}`)}` : `sudo ${s3fsCmd}`;
+	const s3fsCmd = `s3fs ${shellQuote(bucketArg)} ${shellQuote(mountPath)} -o ${mountOptions.join(" -o ")}`;
+	const mountCmd = useSessionToken ? `sudo sh -c ${shellQuote(`. ${credentialsPath} && exec ${s3fsCmd}`)}` : `sudo ${s3fsCmd}`;
 	logger.debug(`${LOG_PREFIX} Mounting S3:`, hasCredentials ? mountCmd.replace(credentialsPath, "***") : mountCmd);
 	try {
 		const result = await sandbox.commands.run(mountCmd, { timeoutMs: 6e4 });
@@ -236,7 +746,7 @@ Error details: ${installResult.stderr || installResult.stdout}`);
 	} finally {
 		if (useSessionToken) await removeSessionCredentials();
 	}
-	if ((await sandbox.commands.run(`mountpoint -q ${shellQuote$2(mountPath)}`)).exitCode !== 0) throw new Error(`s3fs returned exit 0 but ${mountPath} is not a mountpoint. The s3fs daemon likely failed during FUSE init (common causes: region mismatch, invalid credentials, or an S3-compatible endpoint that rejects the signature). Re-run inside the sandbox with '-f -o dbglevel=info' to see the underlying error.`);
+	if ((await sandbox.commands.run(`mountpoint -q ${shellQuote(mountPath)}`)).exitCode !== 0) throw new Error(`s3fs returned exit 0 but ${mountPath} is not a mountpoint. The s3fs daemon likely failed during FUSE init (common causes: region mismatch, invalid credentials, or an S3-compatible endpoint that rejects the signature). Re-run inside the sandbox with '-f -o dbglevel=info' to see the underlying error.`);
 }
 //#endregion
 //#region src/sandbox/mounts/gcs.ts
@@ -256,7 +766,7 @@ async function mountGCS(mountPath, config, ctx) {
 	}
 	const [uid, gid] = (await sandbox.commands.run("id -u && id -g")).stdout.trim().split("\n");
 	const uidGidFlags = uid && gid ? `--uid=${uid} --gid=${gid}` : "";
-	const onlyDirFlag = config.prefix ? ` --only-dir=${shellQuote$2(validatePrefix(config.prefix))}` : "";
+	const onlyDirFlag = config.prefix ? ` --only-dir=${shellQuote(validatePrefix(config.prefix))}` : "";
 	const hasCredentials = !!config.serviceAccountKey;
 	let mountCmd;
 	if (hasCredentials) {
@@ -464,9 +974,9 @@ Error details: ${verifyResult.stderr || verifyResult.stdout || installResult?.st
 	await sandbox.commands.run(`sudo rm -f ${configPath}`);
 	await sandbox.files.write(configPath, yaml);
 	await sandbox.commands.run(`sudo chown root:root ${configPath} && sudo chmod 600 ${configPath}`);
-	await sandbox.commands.run(`sudo rm -rf ${shellQuote$2(cachePath)} && sudo mkdir -p ${shellQuote$2(cachePath)}`);
-	const prefixFlags = prefix ? ` --virtual-directory=true --subdirectory=${shellQuote$2(prefix)}` : "";
-	const mountCmd = `sudo blobfuse2 mount ${shellQuote$2(mountPath)} --config-file=${shellQuote$2(configPath)}${prefixFlags}`;
+	await sandbox.commands.run(`sudo rm -rf ${shellQuote(cachePath)} && sudo mkdir -p ${shellQuote(cachePath)}`);
+	const prefixFlags = prefix ? ` --virtual-directory=true --subdirectory=${shellQuote(prefix)}` : "";
+	const mountCmd = `sudo blobfuse2 mount ${shellQuote(mountPath)} --config-file=${shellQuote(configPath)}${prefixFlags}`;
 	logger.debug(`${LOG_PREFIX} Mounting Azure Blob:`, mountCmd);
 	try {
 		const result = await sandbox.commands.run(mountCmd, { timeoutMs: 6e4 });
@@ -705,6 +1215,7 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 	_sandbox = null;
 	_createdAt = null;
 	_isRetrying = false;
+	_filesystem;
 	timeout;
 	templateSpec;
 	metadata;
@@ -977,6 +1488,15 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 		};
 	}
 	/**
+	* The sandbox's disk through E2B's files API: one request per operation
+	* instead of a shell command. Paths are absolute inside the sandbox and are
+	* not confined to any root.
+	*/
+	get filesystem() {
+		this._filesystem ??= new E2BSandboxFilesystem(this);
+		return this._filesystem;
+	}
+	/**
 	* Bulk-write files into the sandbox filesystem via the SDK's native upload.
 	*
 	* Per-file permission modes are not supported; an explicit `mode` is
@@ -1607,82 +2127,6 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 	}
 };
 //#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$1(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$1(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/utils/repo-template.ts
 /**
 * Sha-tagged repo templates.
@@ -2586,6 +3030,6 @@ var E2BCodeModeTransport = class {
 	}
 };
 //#endregion
-export { DEFAULT_NODE_VERSION, E2BCodeModeTransport, E2BFactorySandbox, E2BProcessManager, E2BSandbox, createDefaultMountableTemplate, createRepoTemplate, e2bSandboxProvider, isDeferredNamedTemplateSpec, isNamedTemplateSpec, refreshRepoTemplate, repoTemplateRef };
+export { DEFAULT_NODE_VERSION, E2BCodeModeTransport, E2BFactorySandbox, E2BProcessManager, E2BSandbox, E2BSandboxFilesystem, createDefaultMountableTemplate, createRepoTemplate, e2bSandboxProvider, isDeferredNamedTemplateSpec, isNamedTemplateSpec, refreshRepoTemplate, repoTemplateRef };
 
 //# sourceMappingURL=index.js.map